> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# CLIProxy Sync

> Sync CCS API profiles to CLIProxy config automatically

# 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.

```bash theme={null}
# 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:

```bash theme={null}
# 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`):**

```json theme={null}
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-xxx",
    "ANTHROPIC_BASE_URL": "https://api.glm.cn/anthropic",
    "ANTHROPIC_MODEL": "glm-4-plus"
  }
}
```

**Synced to CLIProxy (`config.yaml`):**

```yaml theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
ccs cliproxy sync --dry-run

# Output shows what would be synced without making changes
```

### `ccs cliproxy sync --verbose`

Show detailed sync information.

```bash theme={null}
ccs cliproxy sync --verbose

# Output includes detailed profile mapping and config changes
```

## Configuration

### Enable/Disable Auto-Sync

**Config location:** `~/.ccs/config.yaml`

```yaml theme={null}
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

<Note>Available since v7.48.0</Note>

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](/features/workflow/droid-adapter#dashboard-droid-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:**

```bash theme={null}
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:**

```bash theme={null}
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:**

```bash theme={null}
# Reconfigure profile
ccs api create glm
# → Enter real API key (not placeholder)
```

### Manual Sync Fails

**Error:** "Failed to sync: `<error>`"

**Solutions:**

```bash theme={null}
# 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

<Note>Available since v7.39.0</Note>

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

```bash theme={null}
# 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:**

```bash theme={null}
# 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:**

```bash theme={null}
ccs cliproxy catalog reset
```

***

## Related

* [CLIProxy API](/features/proxy/cliproxy-api) - OAuth provider integration
* [API Profiles](/providers/concepts/api-profiles) - Profile configuration
* [Dashboard](/features/dashboard/overview) - Visual management
* [CLI Commands](/reference/cli-commands) - Full command reference