Command reference
The complete skillsvault command set. Every command returns through a single dispatcher that prints any error and sets the exit code; the one exception is gate, whose exit code is the protocol the harness hook reads.
skillsvault <command> [flags]
Exit codes at a glance
Most commands exit 0 on success, 1 on error. gate is special: 0 for allow and warn, 2 for halt. A Ctrl-C interrupt exits 130 (128 + SIGINT). An unknown command exits 1.
login
Sign in and authorize this machine via the browser device-code flow. Mints an agent key for you — no key needed up front. See Install & connect.
skillsvault login [--url <base>] [--headless] [--machine <name>]
| Flag | Default | Meaning |
|---|---|---|
--url | http://localhost:3000 | control-plane base URL |
--machine | hostname | machine name recorded in the fleet |
--headless | off | print the URL + code instead of opening a browser |
Exit: 0 authorized · 1 denied / expired / timed out · 130 Ctrl-C.
logout
Remove this machine's local config (org + agent key) and, unless told otherwise, the synced bundle. Idempotent — running it when nothing is configured is a no-op.
skillsvault logout [--keep-bundle]
--keep-bundle clears credentials but leaves ~/.skillsvault/bundle.json in place. Exit: 0 / 1.
configure
Connect non-interactively with an org slug and an agent key (CI, headless). Pins the org's signing key.
skillsvault configure --org <slug> --key <agent-key> [--url <base>] [--machine <name>]
| Flag | Default | Meaning |
|---|---|---|
--org | — (required) | organisation slug |
--key | — (required) | agent key (skillsvault_ak_…) |
--url | http://localhost:3000 | control-plane base URL |
--machine | hostname | machine name |
Exit: 0 / 1 (missing --org/--key is an error).
sync
Pull and verify the signed policy bundle, then store it locally. A bundle whose Ed25519 signature does not verify against the pinned key is rejected and the last-good bundle is kept.
skillsvault sync
✓ bundle v1750848000 verified & synced · 4 skills · 3 active policies
→ next: skillsvault pull
Exit: 0 / 1 (network error, non-200 status, bad envelope, or signature failure).
pull
Install the org's approved skills into a harness; banned skills already present are removed (the governance action). Writes SKILL.md plus any bundled scripts//references//assets/ files, rejecting unsafe paths (absolute or ..). Reports the installed inventory back to the fleet via a heartbeat.
skillsvault pull [--harness <h>] [--all] [--dir <skills dir>]
| Flag | Default | Meaning |
|---|---|---|
--harness | claude_code | target a single harness by key |
--all | off | install into every detected harness on the machine |
--dir | — | override the skills directory (e.g. for tests / unknown harnesses) |
▶ claude_code ~/.claude/skills
✓ acme/hubspot-crm-entry@1.3.0
⛔ removed banned acme/teamleader-crm-entry
1 installed · 1 banned removed (1 banned total)
With --all and no harness detected, it errors and suggests --harness or --dir. Exit: 0 / 1.
publish
Publish a skill folder to the org registry, creating a new immutable, current version. Reads SKILL.md (required) and an optional skillsvault.json manifest; falls back to the SKILL.md frontmatter description when the manifest omits one. Bundles every file under scripts/, references/, and assets/.
skillsvault publish <path> [--name <org/skill>] [--version <semver>]
| Input | Source | Notes |
|---|---|---|
| path | first non-flag dir arg, else . | folder containing SKILL.md |
| name | --name, else skillsvault.json.name | required; namespace/skill-name |
| version | --version, else skillsvault.json.version | defaults to 1.0.0 |
| intent / targets / description | skillsvault.json | matcher inputs |
✓ published acme/hubspot-crm-entry@1.3.0 (2 bundled files)
Exit: 0 / 1 (no SKILL.md, missing name, or non-200 from the registry). See Authoring & publishing.
detect
List the AI agents/harnesses found on this machine and whether each is enforced (has a vetoing hook) or distribution-only.
skillsvault detect
skillsvault detect — AI agents found on this machine
• claude_code ~/.claude/skills enforced (hook)
• cursor ~/.cursor/rules distribution only
→ skillsvault pull --all installs approved skills into all of the above
Exit: 0. See Harness coverage.
gate
Evaluate a skill against the synced bundle and emit allow / warn / halt. Full behaviour, including hook mode, is on The runtime gate.
skillsvault gate [--skill <name>] [--harness <h>] [--machine <name>] [--quiet]
| Flag | Default | Meaning |
|---|---|---|
--skill | — | skill to evaluate; if omitted, read from the hook payload on stdin |
--harness | claude_code | harness label recorded in the audit event |
--machine | config machine | machine-name override for the audit event |
--quiet | off | only emit on warn / halt |
Exit: 0 allow · 0 warn · 2 halt. (In Claude Code hook mode the command always exits 0 and signals the veto in JSON — see the gate page.)
status
Show the current config and synced-bundle freshness.
skillsvault status # human-readable
skillsvault status --json # machine-readable
The --json shape:
{
"org": "acme",
"base_url": "https://skillsvault.io",
"machine": "macbook-pro",
"bundle": {
"version": 1750848000,
"skills": 4,
"policies": 3,
"received_at": "2026-06-25T10:00:00Z"
}
}
bundle is null when nothing has been synced yet. Exit: 0 / 1.
install-hook
Print the Claude Code PreToolUse hook config to wire the gate into .claude/settings.json. See Harness coverage.
skillsvault install-hook
Exit: 0.
version
Print the binary version.
skillsvault version # also: --version, -v
# -> skillsvault 0.1.0