CLI Reference

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.

Validates your access key, detects your dev environment, pulls your library to disk, and (in Claude Code) offers to install the SessionStart hook. Idempotent — re-run it any time to refresh detection or pick up a new vendor.

skillrepo init [--key <key>] [--url <url>] [--yes] [--force]
                [--agent <list>] [--global] [--json] [--no-session-sync]

Flags

Auto-refresh hooks per agent

For every agent the CLI knows how to install a SessionStart hook for, init writes a user-scope hook config so skillrepo update runs automatically when you open a new agent session. Five vendors are covered today; two are deferred until their docs publish a SessionStart-equivalent event. The cohort hook command is always npx --yes skillrepo update --silent — no global install required, cross-platform. Pass --no-session-sync to skip all hook installs in a single run. See the CLI README's session-sync section for the canonical JSON shapes the merger writes into each file.

Unit tip when copying snippets between vendors: Gemini CLI's timeout is in milliseconds; Cursor, Codex CLI, and VS Code + Copilot all use seconds. The values look interchangeable but a 60 that means a minute on one vendor means 60 milliseconds on Gemini — check the unit before hand-editing a hook entry.

Re-running init with a valid existing config re-runs detection and the per-vendor MCP merge prompts 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.

Non-interactive setup: under --yes the picker is skipped and the pre-checked rows become the selection. With no detection signals, both default rows (.claude/skills/ and .agents/skills/) are pre-checked — so running init --yes on a fresh clone always produces a working library. Pass --agent (e.g. --agent claude, --agent agents, or --agent claude,agents) to bypass the picker entirely. Pass --agent none to skip placement and just write config + gitignore.

Accepting a team invitation

init doubles as the invitation-acceptance flow for invitees who have not clicked the email link yet. When the CLI does not already have a working access key, it opens the browser to the SkillRepo authentication page; after sign in, that page lists pending invitations for the email address alongside the accounts the user already belongs to.

1. Run npx skillrepo init in any project.
2. Sign in with the email address the invitation was sent to (GitHub or Google OAuth).
3. Pick the invitation from the list. Acceptance and key issuance run in a single database transaction, so there is never a state where the membership exists without a key, or vice versa.
4. The CLI receives the key and finishes its first-run sync against the team library.

The email-driven accept link still works exactly as before; the CLI flow is an alternative entry point for users whose starting point is a terminal rather than an inbox.

Pulls 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] [--agent <list>] [--json]

Flags

One-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] [--agent <list>] [--json]

Flags

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

Queries /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

POSTs 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] [--agent <list>] [--json]

Same flags as get.

DELETEs 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] [--agent <list>] [--json]

Same flags as get.

Installs (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.

Flags

Surgically 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.skillrepo from .mcp.json, .cursor/mcp.json, and .vscode/mcp.json (plus the matching inputs prompt 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

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.