CLI Reference
The skillrepo CLI is the recommended way to wire SkillRepo into a project. One command (npx skillrepo init) validates your access key, detects every installed IDE, writes the MCP config for each, and pulls your library to disk. Use the same binary day-to-day to sync, search, add, and remove skills from the terminal.
On this page
Overview
skillrepo is a pull-based CLI. It reads your library from the registry and writes skills to disk, where your IDE picks them up directly — no long-running daemon, no background process. Every command is idempotent and safe to re-run.
Use the CLI when you want SkillRepo wired into a project the way most users do: skills on disk under .claude/skills/, MCP servers registered in every detected IDE’s config file, and a single command (skillrepo update) to keep everything current. Configure MCP by hand only if you need an environment the CLI doesn’t support — see the MCP Reference for the manual path.
npx skillrepo initValidates your access key, auto-detects your IDEs, wires up the MCP config, and pulls your library. Safe to re-run at any time.
Install
skillrepo is published to npm. Use npx for one-off invocations, or install globally so the binary lives at a stable absolute path on your machine — required for the session-sync hook to call back into the CLI on every Claude Code session start.
# One-off via npx (recommended for first run)
npx skillrepo <command>
# Or install globally
npm install -g skillrepo
skillrepo <command>Requires Node.js 18 or later. The CLI ships as ESM and uses node:-prefixed builtins; older Node releases will refuse to load it.
Authentication
The CLI authenticates with the same sk_live_* access keys SkillRepo issues for any registry surface. The CLI is the developer-machine surface; the MCP server and REST API serve remote agents and integrations. Mint a key from the dashboard’s Connect page; see Getting Started for the click path.
On first init, the CLI writes credentials to ~/.claude/skillrepo/config.json (chmod 0600 on POSIX) so subsequent commands run without a prompt. The file looks like:
{
"schemaVersion": 1,
"apiKey": "sk_live_...",
"serverUrl": "https://skillrepo.dev",
"accountSlug": "alice",
"accountId": "acc_...",
"userId": "user_...",
"writtenAt": "2026-04-15T00:00:00Z"
}Resolution order
Every command except init looks for credentials in this order. The first source that yields a key wins; later sources are ignored.
--key/--urlCLI flags~/.claude/skillrepo/config.jsonSKILLREPO_ACCESS_KEY/SKILLREPO_URLenvironment variables- Hard-fail with a hint to run
skillrepo init
init uses a slightly different order so it can reuse an existing config when one is already valid, fall back to .env.local / .env for the project, and finally prompt interactively. Pass --force to skip the cached config and re-prompt.
Keep your key secret
Access keys grant full read/write access to your account. Never commit keys to source control. Rotate compromised keys from the dashboard immediately.
Commands
Every command accepts --json to emit structured output suitable for scripting, and --verbose to print stack traces and per-attempt retry timings on failure.
skillrepo initValidates your access key, detects installed IDEs, writes the MCP config, optionally installs the Claude Code SessionStart hook, and runs the first library sync. Idempotent — re-run it any time to refresh detection or pick up a new IDE.
skillrepo init [--key <key>] [--url <url>] [--yes] [--force]
[--ide <list>] [--global] [--json] [--no-session-sync]Flags
| Flag | Description |
|---|---|
--key, -k | Access key. Falls back to SKILLREPO_ACCESS_KEY, then an interactive prompt. |
--url, -u | Server URL. Defaults to https://skillrepo.dev. Use this to point at a self-hosted instance. |
--yes, -y | Non-interactive mode. Skips every confirmation prompt; required for CI. Installs the session-sync hook by default — pair with --no-session-sync to opt out. Under npx, also auto-runs npm install -g skillrepo if no global install is present so the hook can use a stable absolute path. |
--force | Re-prompt for a new key even if ~/.claude/skillrepo/config.json is valid. Use this to rotate credentials. |
--ide <list> | Comma-separated vendor override. One or more of claude, cursor, windsurf, vscode, or all. Required when running from a directory with no IDE markers (e.g. CI). |
--global | Write skills to ~/.claude/skills/ (personal cache) instead of .claude/skills/ (project-scoped). |
--no-session-sync | Skip the SessionStart hook install. Works in both interactive and --yes modes. Use this in CI scripts that bootstrap a project but never start a Claude Code session. |
--json | Emit a structured JSON summary on success. Includes a sessionSync block describing whether the hook was installed and where it lives. |
Re-running init with a valid existing config re-runs detection and the MCP merge without re-prompting for a key. If the stored key has been revoked (the server returns 401), the CLI falls back to the interactive prompt automatically — no --force needed.
Headless / CI: if you run from a directory with no IDE markers, init refuses and prints a copy-pasteable MCP config for manual wiring. To proceed anyway, pass --ide claude (or your target vendor).
skillrepo updatePulls the latest state of your library from the server using a delta sync. Writes new and updated skills, removes skills that were removed from the library, and skips skills that are unchanged. Uses ETag caching so repeat runs return 304 Not Modified when nothing has changed.
skillrepo update [--global] [--ide <list>] [--json]Flags
| Flag | Description |
|---|---|
--global | Write to ~/.claude/skills/ instead of the project directory. |
--ide <list> | Comma-separated vendor override. Same values as init. |
--json | Emit a structured summary of what was added, updated, or removed. |
skillrepo getOne-shot fetch. Reads GET /api/v1/skills/{owner}/{name} and writes the skill to disk without mutating your library or the server. Use this to preview or pin a specific skill without adding it.
skillrepo get <@owner/name> [--global] [--ide <list>] [--json]Flags
| Flag | Description |
|---|---|
--global | Write to ~/.claude/skills/. |
--ide <list> | Comma-separated vendor override. |
--json | Emit a structured summary including the resolved version and the on-disk path. |
skillrepo listRenders your library as a table — owner, name, version, description. Uses the same cached ETag as update, so a repeat call hits a 304 and reads from cache.
skillrepo list [--json]--json emits the same data as a JSON array, suitable for piping into jq or another script.
skillrepo searchQueries /api/v1/skills/search for public skills matching query. Returns the same metadata you see in the catalog UI.
skillrepo search <query> [--limit <n>] [--json] [--semantic]Flags
| Flag | Description |
|---|---|
--limit <n> | Cap the result count. Defaults to 20. |
--semantic | Accepted but currently a no-op. Semantic search is a planned backend feature; the flag is reserved so scripts written today keep working when it ships. |
--json | Emit results as a JSON array. |
skillrepo addPOSTs to /api/v1/library, then fetches the single skill directly and writes it to disk. Requires a write-scoped access key. On 409 (the skill is already in your library), re-fetches the current version so your local state stays consistent with the server.
skillrepo add <@owner/name> [--global] [--ide <list>] [--json]Same flags as get.
skillrepo removeDELETEs from /api/v1/library and removes the local directory. Requires a write-scoped access key. The local delete is immediate and does not wait for a follow-up sync.
skillrepo remove <@owner/name> [--global] [--ide <list>] [--json]Same flags as get.
skillrepo session-syncInstalls (or removes) a Claude Code SessionStart hook that runs skillrepo update every time you open a Claude Code session. The hook lives in .claude/settings.local.json (per-developer, gitignored by default) and shells out to your global skillrepo binary.
skillrepo session-sync enable [--global] [--json]
skillrepo session-sync disable [--global] [--json]skillrepo init offers to install this hook on first run; if you said no (or passed --no-session-sync), turn it on later with session-sync enable.
session-sync enable does not auto-install the global binary the way init --yes does. It assumes the global install already exists; under npx without one present, it prints a clear “install globally first” message rather than mutating your global package set.
The hook never blocks your session
The hook command runs update --session-hook, which exits 0 on every failure — network outage, revoked key, disk error — and prints a one-line failure message. On POSIX a || true backstop is appended for belt-and-suspenders. Session starts are never blocked by sync failures, and a 304 Not Modified response runs silently with no per-session noise.
Flags
| Flag | Description |
|---|---|
--global | Operate on ~/.claude/settings.local.json so the hook fires in every Claude Code session across every project on your machine. |
--json | Emit structured JSON with action, path, and command fields for scripting. |
skillrepo uninstallSurgically removes every SkillRepo artifact from the current project. Non-SkillRepo entries in shared files are preserved. Runs offline, so a revoked or missing access key is not a problem. Interactive by default — prints a full list of what will be removed and prompts before touching anything.
skillrepo uninstall [--dry-run] [--yes] [--global] [--json]What gets removed
mcpServers.skillrepofrom.mcp.json,.cursor/mcp.json, and.vscode/mcp.json(plus the matchinginputsprompt in the VS Code config)SKILLREPO_ACCESS_KEY=...lines from.env.local- The SkillRepo section of
.gitignore - The SkillRepo SessionStart hook from
.claude/settings.local.json(if present) - The
.claude/skills/directory
With --global, also removes mcpServers.skillrepo from ~/.codeium/windsurf/mcp_config.json, the ~/.claude/skills/ global skill cache, and the ~/.claude/skillrepo/ directory (stored credentials and sync cache). Without it, your credential and other projects’ integrations are left untouched.
Flags
| Flag | Description |
|---|---|
--dry-run, -n | Print what would be removed and exit without touching any file. |
--yes, -y | Skip the confirmation prompt. |
--global | Also remove user-global state. |
--json | Emit a structured summary with removed[] and errors[] arrays. Useful for scripting. |
The command is idempotent — a second run with nothing left to remove exits 0 and prints “Nothing to remove.” If any artifact fails to remove (e.g. a read-only file), the command processes the rest, surfaces every error at the end, and exits with code 3.
Environment variables
The CLI reads four environment variables. Each one has a higher-precedence override (a CLI flag or the config file) so you only need them in environments where flags and config aren’t practical — typically CI.
| Variable | Purpose |
|---|---|
SKILLREPO_ACCESS_KEY | Access key for any command. Takes precedence over the config file but not over --key. Use this in CI where writing a config file would leave credentials on disk. |
SKILLREPO_URL | Server URL. Same precedence as SKILLREPO_ACCESS_KEY. Use for self-hosted instances or to point a session at staging. |
SKILLREPO_TIMEOUT_MS | Per-request fetch timeout in milliseconds. Defaults to 30000. Set to 0 to disable. Raise this on slow networks where the default is triggering false-positive timeouts. |
NO_COLOR | Set to any non-empty value to disable ANSI color in CLI output. The CLI also respects the variable when piping into a non-TTY consumer. |
Exit codes
Every command exits with a stable code so CI scripts can branch on the failure class. Pass --verbose to print stack traces and retry attempts when diagnosing a non-zero exit.
| Code | Meaning |
|---|---|
0 | Success |
1 | Network error (unreachable server, DNS, timeout, exhausted retries) |
2 | Auth error (invalid key, revoked, suspended account) |
3 | Disk error (cannot read or write a file or directory) |
4 | Scope error (key lacks the required registry:write scope) |
5 | Validation error (bad flag, malformed identifier, unknown vendor) |
Retries
The CLI automatically retries transient server failures on every idempotent API call — specifically POST /auth/validate, GET /library, GET /skills/:owner/:name, and GET /skills/search. The read-only commands (update, get, list, search) and the validate plus sync calls inside init benefit automatically.
- Triggered by:
429,502,503,504, and raw network errors (DNS, TCP reset, timeout). - Not triggered by: 4xx auth and validation errors — those never succeed on retry — and
500, which is treated as a real-bug signal that should surface loudly rather than be masked. - Backoff: exponential with full jitter, three attempts total, base 500 ms, capped at 8 s per sleep.
- Write endpoints (
add,remove) are single-shot. A503mid-POSTcan mean either “body never reached the server” or “body processed, response lost,” and the client cannot distinguish — so retrying would risk a duplicate library mutation.
Self-hosted
The CLI works against any SkillRepo instance that implements the v1 API. Point it at a custom host with --url on init:
skillrepo init --url https://skillrepo.internal.company.comOr persist it via environment variables in your shell profile so every command picks it up without flags:
export SKILLREPO_URL=https://skillrepo.internal.company.com
export SKILLREPO_ACCESS_KEY=sk_live_...Troubleshooting
No access key configured
Run skillrepo init, pass --key, or set SKILLREPO_ACCESS_KEY.
Invalid access key format
Keys must start with sk_live_. The CLI trims leading and trailing whitespace from keys in every path — both the interactive prompt in init and the Bearer header used by every subsequent command — so pasting from email or a browser with a trailing newline is safe.
No IDEs detected in this directory
The CLI found no .claude/, .cursor/, .vscode/, or ~/.codeium/windsurf/ markers. Either run from inside a project with one of those folders, pass --ide <vendor> to target a specific IDE, or copy the printed MCP config into your IDE’s settings by hand.
Rate limit exceeded — retried automatically and still getting 429
The CLI already retried with backoff. Wait a minute and retry. Pass --verbose to see per-attempt timings.
Windows note: skill updates use a best-effort atomic-rename pattern. A crash mid-update may leave a partial state; the next update run fully overwrites it.
Next steps
Configure MCP by hand if the CLI doesn’t fit your environment, or browse the REST API for everything that lives outside the read-only MCP surface — publishing, library management, search.