codevector CLI
Command-line tool to wire Claude Code, opencode, and codex through CodeVector. One install, one login, one configure.
Your gateway URL
Pin your own gateway hostname and we'll rewrite the routes and curl examples on every docs page so you can click straight through to the live console. Stored locally in your browser.
The codevector CLI points your AI coding tools at CodeVector: install it globally, sign in once, then run codevector configure per tool. It deep-merges into your existing settings files and leaves your theme, hooks, and env vars untouched.
Install
Requires Node.js 20 or newer.
# pnpm
pnpm add -g @codevector/cli
# npm
npm i -g @codevector/cliAfter install, the codevector binary is on your PATH. Run codevector --help to confirm.
Sign in
Get a per-seat API key from your gateway admin (or create one yourself on the API Keys page), then sign in:
codevector auth login --profile default \
--gateway-url https://your-gateway.example.comOr pass the API key non-interactively for scripted onboarding:
codevector auth login --profile default \
--gateway-url https://your-gateway.example.com \
--api-key "$GATEWAY_KEY"Credentials are stored at ~/.config/codevector/credentials.json with file mode 0600. The file holds one or more named profiles, each with a gateway URL, API key, user ID, and email. One profile is marked active and is used by all commands. Override the directory with CODEVECTOR_CONFIG_DIR.
The file shape is:
{
"activeProfile": "default",
"profiles": {
"default": {
"gatewayUrl": "https://your-gateway.example.com",
"apiKey": "cv_live_...",
"userId": "...",
"email": "you@example.com",
"toolConfigs": [
{ "tool": "claude-code", "scope": "local", "model": "anthropic:claude-sonnet-4-5" }
]
}
}
}The toolConfigs array remembers which tools were wired (and any pinned model) so codevector profile switch can reapply them. You usually never need to edit this file by hand - the CLI commands manage it for you.
Configure this repo
codevector configure is the per-repo command. It writes local (default, gitignored, per-seat) or project (committed, shared with the team) config and never touches files outside the repo. For machine-wide defaults across every repo, use codevector system configure instead.
codevector configure # interactive picker for tools + scope
codevector configure claude-code # one specific tool
codevector configure --all --scope local # every supported tool at onceSupported tools
| Tool | Config path (project / local scope) | Scopes | Hooks installed |
|---|---|---|---|
| Claude Code | <repo>/.claude/settings(.local).json | project / local | Stop + SessionEnd |
| opencode (sst/opencode) | <repo>/opencode.json | project / local | - |
| codex (OpenAI codex CLI) | <repo>/.codex/config.toml | project / local | not wired |
Codex now supports per-repo scopes too. Per the Codex docs, Codex reads .codex/config.toml from each directory between the repo root and your current working directory (trusted projects only), so a project or local scope CLI write lands in <repo>/.codex/config.toml and is picked up automatically.
Cursor is not listed here because Cursor stores its endpoint settings in an internal SQLite database. The Connect page shows the manual GUI steps.
Pick a scope
| Scope | File location | Committed to git? | Use it for |
|---|---|---|---|
project | repo’s shared config dir (e.g. .claude/settings.json, .codex/config.toml) | yes - shared with team | base URL only - the CLI never embeds your API key here |
local | repo’s local-override file (or same path + a .gitignore entry) | no - auto-gitignored | per-seat key on your machine - the recommended default |
local is the default when you don’t pass --scope. The CLI adds .gitignore entries automatically for tools that don’t natively ignore their local file (opencode’s opencode.json, codex’s .codex/config.toml).
project scope writes an env-var reference instead of the literal key ({env:CODEVECTOR_GATEWAY_KEY} or an envKey field), so a committed config file never leaks credentials.
Configure global defaults across editors
codevector system configure writes user-scope config (~/.claude/settings.json, ~/.config/opencode/opencode.json, ~/.codex/config.toml) for every supported editor in one step. Before each file is overwritten, the original is copied to ~/.codevector/backups/<timestamp>/<tool>/<filename> so you can roll back with codevector system restore.
codevector system configureUse this when:
- You are setting up a brand-new machine and want every editor pointed at the gateway by default.
- You want the same global defaults across every repo so per-repo
configureruns become opt-in overrides. - You are migrating from a previous global setup and want a one-shot backup before changing anything.
The output prints each written file path plus the backup directory so you know exactly what to roll back to if needed.
Roll back a system configure run
codevector system restore reads ~/.codevector/backups/ and restores a chosen backup over your current user-scope files. Without arguments it prompts you to pick a backup; pass --latest to skip the picker or --timestamp <ts> to target a specific one.
codevector system restore # interactive picker
codevector system restore --latest # most recent backup, with confirmation
codevector system restore --latest --yes # skip the confirmation prompt
codevector system restore --timestamp 2026-05-25T19-30-12.488ZEach backup directory is a single system configure invocation; restoring one run puts every editor back to the state it was in immediately before that run. Backups are never deleted automatically.
Profiles
If you connect to more than one gateway (e.g. default vs. production, or different teams), create additional profiles with codevector auth login --profile <name>.
List all profiles:
codevector profile listSwitch the active profile:
codevector profile switch
# interactively pick the active profileWhen you switch profiles, the CLI automatically reapplies the stored tool configurations for that profile. If a previously pinned model is not reachable through the new gateway, the model pin is removed automatically.
codex requires updating an env var on switch
codex reads its API key from the CODEVECTOR_GATEWAY_KEY environment variable in your shell, not from credentials.json. Switching the active profile updates codex’s ~/.codex/config.toml, but the env var still holds the previous profile’s key until you update your shell:
export CODEVECTOR_GATEWAY_KEY=<new-profile-key>codevector profile switch prints the exact line for the new profile when codex was configured. Add it to your shell rc to persist across sessions.
Gateway unreachable during switch
If the gateway can’t be reached during codevector profile switch (network blip, gateway down), the active profile is still switched but the stored toolConfigs are left untouched - the CLI will not wipe a perfectly good config based on an empty reachable-model list. Re-run codevector profile switch once the gateway is back, or run codevector configure to refresh tool configurations against the new gateway.
Log out of a specific profile:
codevector auth logout --profile defaultInspect and verify
codevector status # who am I, where am I pointed, what models can I use
codevector doctor # health checks: creds, network, hook install, settings parsing
codevector auth whoami # the identity the current API key resolves toRun codevector doctor after configuring tools or whenever something seems off. It checks credentials, file permissions, gateway reachability, hook install paths, and whether each tool’s settings file parses cleanly.
Models and usage
codevector models list # models you can reach through the gateway
codevector models list --kind chat # filter by kind: chat or embedding
codevector models list --json # raw JSON for scripting
codevector models sync # refresh model list in opencode.json
codevector models sync --scope local # explicit scope
codevector usage # your gateway usage (today by default)
codevector usage --days 7 # last 7 days
codevector usage --json | jq .totals # raw JSON for scriptingcodevector models sync is useful for opencode after your admin adds new models on the Models page.
Project-aware attribution with codevector init
codevector init # writes .codevector.json
codevector init --project my-app # explicit project name
codevector init --ticket-pattern "JIRA-\d+" # custom ticket regexcodevector init writes a .codevector.json to the current repo with a project name and an optional ticket-extraction regex. The project name is sent as the x-project header on gateway requests so the Usage page can attribute spend per repo.
Stay up to date
codevector update # uses the same package manager that installed the CLI
codevector update --with pnpm # override and remember pnpm for next time
codevector update --with yarn # override and remember yarn for next timecodevector update shells out to your package manager to upgrade the global install. The install transcript is printed live so you can see exactly what runs.
How the package manager is picked
- Auto-detected on install. The CLI’s postinstall hook reads
process.env.npm_config_user_agent(set by npm, pnpm, and yarn) and writes the detected manager to~/.config/codevector/install.json.updatereuses it without prompting. --with <pm>overrides + remembers. Useful if you re-installed under a different manager and want to switch. The choice is persisted withsource: "user", so subsequent global installs by a different manager won’t silently overwrite it.- Prompt on miss. If the postinstall didn’t run (
npm install --ignore-scripts, sandboxed CI, or you upgraded from an older CLI version), the firstupdateshows a 3-option picker and persists your answer.
Every other command also does a background, best-effort check against the npm registry (cached for 24 hours at ~/.config/codevector/update-check.json). When a newer version is known, you’ll see a one-line notice on stderr:
› A new version of @codevector/cli is available: 1.9.2 → 1.10.0. Run `codevector update` to install.The check has a 2-second timeout, runs non-blocking, and silently swallows any error — it will never delay or fail a command. Set CODEVECTOR_NO_UPDATE_CHECK=1 to disable it entirely.
Sign out
codevector auth logout # removes the active profile
codevector auth logout --profile default # removes a specific profileRemoves the active profile (or the named profile) from ~/.config/codevector/credentials.json. If no profiles remain, the file is deleted. The acceptance-tracking hook is left in place - removing it manually is fine, the hook no-ops without credentials.
Frequently asked questions
Which tools does codevector configure?
Claude Code, opencode (sst/opencode), qwen-code (Alibaba Qwen CLI), and codex (OpenAI codex CLI). Cursor stores its settings in an internal database, so the CLI cannot configure it - the Connect page shows manual steps for Cursor.
What scope should I pick?
Use local for per-seat setup. The local file is auto-gitignored, so your API key stays on your machine and never gets committed. For machine-wide defaults that apply to every repo, use codevector system configure instead.
Can I commit a config without leaking my API key?
Yes. Pick the project scope. The CLI writes an env-var reference like {env:CODEVECTOR_GATEWAY_KEY} or an envKey field instead of the literal key, then prints the export line for your shell rc.
How do I set up Claude Code, opencode, and codex all at once for my account?
Run codevector system configure. It writes user-scope config for every supported editor in one pass and backs up any pre-existing files to ~/.codevector/backups/<timestamp>/ so you can roll back with codevector system restore. This replaces codevector configure --scope user — the per-repo and machine-wide flows are split so each command has one clear job.
How do I roll back a system configure run?
Run codevector system restore. It lists timestamped backups under ~/.codevector/backups/ and restores them over your current user-scope files. Pass --latest to pick the most recent without prompting, or --timestamp <ts> to target a specific backup.
Where are my credentials stored?
At ~/.config/codevector/credentials.json with file mode 0600. The file stores one or more named profiles; one profile is active at a time and is used by all commands. Override the directory with the CODEVECTOR_CONFIG_DIR environment variable. Run codevector auth logout to remove the active profile, or codevector auth logout --profile <name> to remove a specific one.
Does codevector modify my existing settings files?
It deep-merges the gateway entries into your existing JSON, JSONC, or TOML config. Themes, other hooks, and unrelated env vars are left in place. Re-running codevector configure is idempotent - it never creates duplicate entries.