Skip to main content

​
CLIProxy Sync

CCS can automatically sync your API profiles (GLM, Kimi for Coding, etc.) to a local or remote CLIProxy configuration. This enables centralized management of all your API keys and models.

​
Overview

CLIProxy Sync transforms CCS settings-based profiles into CLIProxy ClaudeKey format and writes them to config.yaml. Changes to profiles automatically trigger a sync when auto_sync is enabled. Use Cases:
  • Centralized API key management across devices
  • Remote CLIProxy deployment with synced profiles
  • Dashboard-managed profiles available to all providers

​
Quick Start

​
Enable Auto-Sync

Auto-sync is enabled by default. It watches for changes to ~/.ccs/*.settings.json and syncs to local CLIProxy config. 
# Check sync status and perform sync
ccs cliproxy sync

# Dry-run to preview changes without syncing
ccs cliproxy sync --dry-run

# Verbose output
ccs cliproxy sync --verbose

​
Configure Profiles

Profiles with valid API keys are automatically synced: 
# Create API profile via CLI
ccs api create glm

# Or via Dashboard
ccs config
# → Go to "API Profiles" → Add GLM/KM/custom

​
Auto-Sync Behavior

​
Watcher

When cliproxy.auto_sync is enabled, CCS watches for file changes: Watch Pattern: ~/.ccs/*.settings.json Trigger Events:
  • File created (new profile)
  • File modified (API key/model changed)
  • File deleted (profile removed)
Debounce: 3 seconds (prevents sync storms during rapid edits)

​
Sync Target

Local Sync: Writes to ~/.ccs/cliproxy/config.yaml Profile Mapping:
  • Profile name → prefix (e.g., glm → glm-)
  • ANTHROPIC_AUTH_TOKEN → api-key
  • ANTHROPIC_BASE_URL → base-url (optional)
  • ANTHROPIC_MODEL → models[0].name

​
Example

CCS Profile (glm.settings.json): 
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
    "ANTHROPIC_BASE_URL": "https://api.glm.cn/anthropic",
    "ANTHROPIC_MODEL": "glm-4-plus"
  }
}
Synced to CLIProxy (config.yaml): 
claude-keys:
  - api-key: sk-xxx
    base-url: https://api.glm.cn/anthropic
    prefix: glm-
    models:
      - name: glm-4-plus
        alias: ""

​
CLI Commands

​
ccs cliproxy sync

Sync profiles to CLIProxy config and show status. 
ccs cliproxy sync

# Output:
# CLIProxy Sync Status
#
# Auto-sync: Enabled
# Watcher:   Running
# Profiles:  2 syncable
#
# Syncable Profiles:
#   glm      (glm-4-plus)
#   kimi     (moonshot-v1-128k)
#
# [OK] Synced 2 profile(s) to ~/.ccs/cliproxy/config.yaml

​
ccs cliproxy sync --dry-run

Preview sync changes without writing to config. 
ccs cliproxy sync --dry-run

# Output shows what would be synced without making changes

​
ccs cliproxy sync --verbose

Show detailed sync information. 
ccs cliproxy sync --verbose

# Output includes detailed profile mapping and config changes

​
Configuration

​
Enable/Disable Auto-Sync

Config location: ~/.ccs/config.yaml 
cliproxy:
  auto_sync: true  # Enable auto-sync watcher (default)
  # Set to false to disable automatic syncing

​
Profile Filtering

Only profiles with valid API keys are synced. Profiles are skipped if:
  • ANTHROPIC_AUTH_TOKEN is missing
  • API key contains placeholder text (YOUR_, your-)
  • settings.json is unreadable
  • Profile name is invalid (non-alphanumeric, too long)

​
Target-Aware Filtering

Available since v7.48.0
Sync only processes profiles with target: claude (or no target, which defaults to claude). Profiles with target: droid are excluded because Droid uses a different configuration format (~/.factory/settings.json). This means:
  • API profiles with target: droid are not synced to CLIProxy config
  • CLIProxy variants with target: droid are still managed but their settings path differs
  • Use the Droid dashboard page to manage Droid-targeted profiles

​
Dashboard Integration

​
Sync Status Card

Dashboard shows real-time sync status: Location: Settings → CLIProxy Sync Displays:
  • Auto-sync enabled/disabled
  • Watcher status (running/stopped)
  • Syncable profile count
  • Last sync timestamp
Actions:
  • Toggle auto-sync
  • Manual sync trigger
  • View profile list

​
Profile Management

Profiles managed via Dashboard are automatically synced:
  1. Go to Dashboard → API Profiles
  2. Add/edit GLM, Kimi for Coding, or custom profile
  3. Auto-sync triggers within 3 seconds
  4. Profile available via ccs <prefix>-

​
Troubleshooting

​
Auto-Sync Not Working

Check watcher status: 
ccs cliproxy sync
# → Shows "Watcher: Running" or "Watcher: Stopped"
Common issues:
  • Auto-sync disabled → Enable in ~/.ccs/config.yaml (cliproxy.auto_sync: true)
  • Watcher crashed → Restart Dashboard or run ccs cliproxy sync
  • Invalid profile → Check settings.json for syntax errors

​
Profile Not Syncing

Verify profile is syncable: 
ccs cliproxy sync
# → Lists "Syncable Profiles"
Profile missing from list means:
  • API key placeholder not replaced
  • ANTHROPIC_AUTH_TOKEN missing from settings.json
  • Profile name contains invalid characters
Fix: 
# Reconfigure profile
ccs api create glm
# → Enter real API key (not placeholder)

​
Manual Sync Fails

Error: “Failed to sync: <error>” Solutions: 
# Check CLIProxy config permissions
ls -la ~/.ccs/cliproxy/config.yaml

# Ensure CLIProxy directory exists
mkdir -p ~/.ccs/cliproxy

# Trigger sync
ccs cliproxy sync

​
Remote Proxy Sync

For remote CLIProxy deployments, sync profiles to remote server. Coming Soon: Remote sync via Management API Current Workaround:
  1. Sync locally: ccs cliproxy sync
  2. Copy ~/.ccs/cliproxy/config.yaml to remote server
  3. Restart remote CLIProxy instance

​
Security Considerations

API Key Storage:
  • Keys stored in ~/.ccs/*.settings.json (plain text)
  • Synced to ~/.ccs/cliproxy/config.yaml (plain text)
  • File permissions: 600 (owner read/write only)
Best Practices:
  • Never commit *.settings.json or config.yaml to git
  • Use environment variables for sensitive keys
  • Rotate API keys regularly
  • Encrypt home directory on shared machines

​
Hybrid Model Catalog Sync

Available since v7.39.0
CCS automatically syncs remote model catalogs from CLIProxyAPI with static fallback catalogs to provide accurate, up-to-date model information.

​
Overview

Catalog sync merges remote model catalogs (fetched from CLIProxy Management API) with CCS’s static fallback catalogs. This ensures you always have access to the latest models while maintaining backward compatibility. Syncable Providers:
  • agy (Antigravity)
  • gemini (Google Gemini)
  • codex (OpenAI Codex)
  • claude (Claude via CLIProxy)

​
How It Works

Merge Behavior:
  1. Remote catalog overrides static fields (name, alias, version)
  2. Static-only fields preserved (tier, broken, deprecated)
  3. Models in remote but not static → added
  4. Models in static but not remote → kept
Cache:
  • Location: ~/.ccs/model-catalog-cache.json
  • TTL: 24 hours
  • Auto-refresh on cache expiry

​
CLI Commands

# View current catalog cache status
ccs cliproxy catalog

# Force refresh from remote
ccs cliproxy catalog refresh

# Reset to static catalog (clear cache)
ccs cliproxy catalog reset

​
Dashboard Integration

Dashboard fetches synced catalog via /api/cliproxy/catalog endpoint. Model selection dropdowns automatically show latest available models.

​
Troubleshooting

Catalog out of date: 
# Force refresh
ccs cliproxy catalog refresh
Remote fetch fails:
  • Falls back to static catalog automatically
  • Cache preserved until successful refresh
  • 24hr retry interval
Clear corrupted cache: 
ccs cliproxy catalog reset