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:

Go to Dashboard → API Profiles
Add/edit GLM, Kimi for Coding, or custom profile
Auto-sync triggers within 3 seconds
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:

Sync locally: ccs cliproxy sync
Copy ~/.ccs/cliproxy/config.yaml to remote server
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 and keeps static fallback catalogs for times when no usable live or cached catalog is available.

Overview

Catalog sync prefers a live CLIProxy management catalog, then an unexpired local cache, then the bundled static catalog. Static metadata can enrich matching live models, but static-only models are not re-added to a successful live catalog. Syncable Providers:

agy (Antigravity)
claude (Claude via CLIProxy)
codex (OpenAI Codex)
gemini (Google Gemini)
iflow (iFlow)
kimi (Moonshot Kimi)
kiro (Kiro)
qoder (Qoder)
qwen (Qwen; catalog only, no bundled account linking)
xai (xAI Grok)
ghcp (deprecated GitHub Copilot compatibility)

How It Works

Live Catalog Behavior:

Live models are authoritative when available.
Matching static metadata is overlaid where the live definition omits it.
Models present only in the live catalog are added.
Static-only models are not re-added to a successful live catalog.
The complete static catalog is used only when neither live data nor an unexpired cache is usable.

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:

Uses an unexpired cache when one exists; otherwise uses the static catalog
A failed refresh does not delete the cache file, but an expired cache is ignored
The 24-hour value is the cache TTL, not a refresh retry interval

Clear corrupted cache:

ccs cliproxy catalog reset

CLIProxy API - OAuth provider integration
API Profiles - Profile configuration
Dashboard - Visual management
CLI Commands - Full command reference

Getting Started

Providers

Features

Tutorials

CLIProxy Sync

CLIProxy Sync

Overview

Quick Start

Enable Auto-Sync

Configure Profiles

Auto-Sync Behavior

Watcher

Sync Target

Example

CLI Commands

`ccs cliproxy sync`

`ccs cliproxy sync --dry-run`

`ccs cliproxy sync --verbose`

Configuration

Enable/Disable Auto-Sync

Profile Filtering

Target-Aware Filtering

Dashboard Integration

Sync Status Card

Profile Management

Troubleshooting

Auto-Sync Not Working

Profile Not Syncing

Manual Sync Fails

Remote Proxy Sync

Security Considerations

Hybrid Model Catalog Sync

Overview

How It Works

CLI Commands

Dashboard Integration

Troubleshooting

​CLIProxy Sync

​Overview

​Quick Start

​Enable Auto-Sync

​Configure Profiles

​Auto-Sync Behavior

​Watcher

​Sync Target

​Example

​CLI Commands

​ccs cliproxy sync

​ccs cliproxy sync --dry-run

​ccs cliproxy sync --verbose

​Configuration

​Enable/Disable Auto-Sync

​Profile Filtering

​Target-Aware Filtering

​Dashboard Integration

​Sync Status Card

​Profile Management

​Troubleshooting

​Auto-Sync Not Working

​Profile Not Syncing

​Manual Sync Fails

​Remote Proxy Sync

​Security Considerations

​Hybrid Model Catalog Sync

​Overview

​How It Works

​CLI Commands

​Dashboard Integration

​Troubleshooting

​Related

CLIProxy Sync

Overview

Quick Start

Enable Auto-Sync

Configure Profiles

Auto-Sync Behavior

Watcher

Sync Target

Example

CLI Commands

`ccs cliproxy sync`

`ccs cliproxy sync --dry-run`

`ccs cliproxy sync --verbose`

Configuration

Enable/Disable Auto-Sync

Profile Filtering

Target-Aware Filtering

Dashboard Integration

Sync Status Card

Profile Management

Troubleshooting

Auto-Sync Not Working

Profile Not Syncing

Manual Sync Fails

Remote Proxy Sync

Security Considerations

Hybrid Model Catalog Sync

Overview

How It Works

CLI Commands

Dashboard Integration

Troubleshooting

Related