Install & connect

skillsvault is a single, statically-linked Go binary — the entire data plane. It pulls approved skills, holds the signed policy bundle, and runs the cooperative gate. There is no runtime to install and no per-invocation network call.

One binary

Every capability is a subcommand of the same skillsvault binary — including the gate, which the harness hook invokes per skill call. Nothing else to install or run.

Install

Install script (recommended)

The fastest path on macOS and Linux — downloads the right binary for your platform, verifies it against the release's published SHA256SUMS (the install aborts if the checksum is missing or does not match), and puts skillsvault on your PATH:

curl -fsSL https://skillsvault.io/install.sh | sh

This is also what the CLI points you at when it detects it is out of date.

From source

If you have Go (1.26+) and prefer to build it yourself:

cd cli
go build -o skillsvault .
cp skillsvault /usr/local/bin/        # anywhere on your PATH

Verify

skillsvault version        # -> skillsvault 0.6.5
skillsvault --help

Keep it current

The control plane tells each machine whether its skillsvault is current (on every sync/heartbeat) and prints an upgrade hint when a newer release is out. Re-running the install script upgrades in place.

Upgrading an existing machine

The minimum supported CLI is 0.5.1. Older gates miss ways a banned skill can be invoked — before 0.5.0 a skill invoked by its bare folder name (deploy, which is how Claude Code invokes installed skills) was allowed, and before 0.5.1 subagents, typed /commands and the /name and ns:name forms were never checked. The console's Harnesses page marks such machines CLI outdated — upgrade. On each machine:

curl -fsSL https://skillsvault.io/install.sh | sh   # 1. upgrade the binary
skillsvault install-hook                             # 2. print the current hook config
skillsvault pull --all                               # 3. reinstall, recording invocation names
skillsvault sync                                     # 4. report the new hook coverage

Step 2 matters for every machine set up before 0.5.1: its hook has matcher "Skill" and no UserPromptExpansion entry. Paste the printed block over the old skillsvault entry in the settings file that holds it. Until then the machine shows Gating: partial, and sync and detect print a one-line reminder. See Harness coverage.

Connect a machine

There are two ways to connect. Both end by pinning skillsvault's Ed25519 public signing key locally (one key for the whole deployment, the same for every organisation), so every bundle the CLI later loads must carry a valid skillsvault signature.

`skillsvault login` — interactive (recommended)

A browser device-code flow. No key to copy; you sign in (or sign up) and authorize the machine, and the CLI receives a real agent key. If your account has no organisation yet, the same page creates one before approving the machine. Once approved, login syncs your org's policy bundle and prints the next command to run.

skillsvault login                 # opens your browser
skillsvault login --headless      # prints the URL + code instead of opening a browser
skillsvault login --url https://vault.example.com   # a self-hosted control plane

login and configure talk to https://skillsvault.io unless told otherwise. The control-plane URL is resolved in this order:

the --url flag
the SKILLSVAULT_URL environment variable
the URL this machine is already configured for (so re-running login stays on the same server)
https://skillsvault.io

For local development against npm run dev, point the CLI at your machine:

export SKILLSVAULT_URL=http://localhost:3000
skillsvault login

Start the handshake

The CLI calls the control plane and receives a long secret device_code (which only it ever sees) and a short, human user_code like WXYZ-7K3M (the alphabet excludes ambiguous 0/O/1/I/L).

Authorize in the browser

The CLI opens — or prints — the verification URL and shows the user_code. You sign in and approve the machine on the /activate page in the console.

Poll until approved

The CLI polls every few seconds (default ~4s) until the code is approved, denied, or expired (10-minute TTL). On approval it receives an agent key, pins the signing key and saves the config. Ctrl-C cancels the wait cleanly.

Sync and the next step

The CLI then syncs the signed bundle — which also marks the machine online in the console — and prints what to do next: skillsvault try and then skillsvault install-hook when your org already bans a skill, otherwise skillsvault pull --all. Add --import-scan to also upload this machine's scan (metadata only unless you add --with-content).

`skillsvault configure` — non-interactive (CI / headless)

Connect with an org slug and an agent key you generated in the console — no browser:

skillsvault configure \
  --org acme \
  --key skillsvault_ak_… \
  --machine ci-runner-7      # defaults to the hostname

--org and --key are required; --url defaults to $SKILLSVAULT_URL, then the previously configured URL, then https://skillsvault.io (same order as login). configure fetches and pins the public signing key, writes the config, then syncs and prints the next step like login. skillsvault login --key <key> --org <slug> does the same.

Agent keys

An agent key is the bearer credential the CLI uses for every authenticated control-plane call. Tokens look like skillsvault_ak_ followed by hex (skillsvault_ak_ + 24 random bytes). Create and revoke them in Settings → API keys; the console only ever shows a masked form (skillsvault_a…1234) after creation — copy the full value when you mint it.

The CLI sends the key on each request as either header:

X-Skillsvault-Key: skillsvault_ak_…
Authorization: Bearer skillsvault_ak_…

The server validates the key and resolves the org it belongs to: a missing or unknown key gets 401, and a valid key used against a different org gets 403. login mints one of these for you automatically; you can also create and revoke them in Settings → API keys.

Treat it like a password

An agent key is org-scoped — it authorizes publish, pull, sync, heartbeat, and audit-ingest for that one organisation. Store it in a secret manager, never commit it to a repo, and revoke it immediately in Settings → API keys if it leaks.

Local state

The CLI keeps your sign-in and your organisation's current policy snapshot under ~/.skillsvault, readable only by your user account.

Run skillsvault status to see the current connection and how fresh the policy snapshot is. skillsvault logout removes the sign-in (and the snapshot, unless you pass --keep-bundle); it is idempotent.

Global flags

These work on any command:

Flag / env	Effect
`--no-color`	disable ANSI colors (position-independent)
`NO_COLOR=1`	same, via environment
`TERM=dumb`	also disables colors
`-h`, `--help`	help for the binary or any subcommand
`-v`, `--version`	print the version and exit — only as the first argument (`skillsvault -v`), like the `version` command

Color is only ever emitted to a real terminal, so piped and hook output stays byte-clean.

Command reference

Every subcommand, its flags, behaviour, and exit codes.

The runtime gate

How skillsvault gate evaluates the bundle and vetoes a banned skill.