usync - AI CLI Config Sync
Sync configurations and skills from ClaudeCode, OpenCode, Codex, and Gemini CLI to GitHub Gist for backup and cross-machine sync.
When to Use
- •Backing up AI CLI tool settings and skills to the cloud
- •Syncing configurations across multiple machines
- •Restoring AI CLI configs on a new machine
- •Auto-syncing config changes with watch mode
- •Managing settings for multiple AI CLI tools in one place
Quick Start
bash
# Install pnpm add -g usync-cli # Initialize — verify token and create a Gist usync-cli init # Scan — list all discovered config files usync-cli scan # Upload — sync local configs to Gist usync-cli upload --gist-id <id> # Download — restore configs from Gist usync-cli download --gist-id <id> # Watch mode — auto-upload on changes usync-cli upload --gist-id <id> --watch
Supported Providers
| Provider | Global Config | Project Config |
|---|---|---|
| ClaudeCode | ~/.claude/settings.json, ~/.claude/skills/ | .claude/settings.json, .claude/skills/ |
| OpenCode | ~/.config/opencode/ (macOS), %APPDATA%/opencode/ (Windows) | opencode.json, .opencode/skills/ |
| Codex | ~/.codex/config.json, ~/.codex/skills/ | .codex/config.json, .codex/skills/ |
| Gemini CLI | ~/.gemini/settings.json, ~/.gemini/skills/ | .gemini/settings.json, .gemini/skills/ |
Commands
| Command | Description | Reference |
|---|---|---|
usync-cli init | Verify token, create or validate Gist | command-init |
usync-cli scan | List discovered local config files | command-scan |
usync-cli upload | Upload configs to GitHub Gist | command-upload |
usync-cli download | Download and restore configs from Gist | command-download |
References
| Topic | Description | Reference |
|---|---|---|
| Getting Started | Setup, token creation, first sync | guide-getting-started |
| Providers | All supported providers and config paths | reference-providers |
| Architecture | Template paths, manifest, incremental sync | reference-architecture |
Token Setup
usync-cli requires a GitHub Personal Access Token with gist scope:
- •Go to https://github.com/settings/tokens/new
- •Select scope: gist
- •Generate and save the token
Token resolution order:
- •
--token <PAT>flag - •Environment variable (default:
GITHUB_TOKEN, or custom via--token-env) - •
GH_TOKENfallback
Common Patterns
First-time setup
bash
# Set token in environment export GITHUB_TOKEN=ghp_xxx # Initialize and create a new Gist usync-cli init # Upload all configs usync-cli upload --gist-id <id-from-init>
Restore on new machine
bash
export GITHUB_TOKEN=ghp_xxx usync-cli download --gist-id <id>
Watch mode for continuous sync
bash
usync-cli upload --gist-id <id> --watch --interval 30
Filter specific providers
bash
usync-cli scan --providers claudecode,opencode usync-cli upload --gist-id <id> --providers claudecode
Security
- •Sensitive files are auto-excluded:
.env*,.key,.pem,.p12 - •File contents are base64-encoded in the Gist
- •Use private Gists (default) for security
- •Tokens are never stored locally — use env vars
Tech Stack
- •CLI Framework: citty (unjs)
- •Interactive Prompts: @clack/prompts
- •Logging: consola + colorette
- •Build: tsdown
- •Path Handling: pathe (cross-platform)
- •Package Manager: pnpm
- •Versioning: changesets