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 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.1.0
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.
Connect a machine
There are two ways to connect. Both end by pinning your org's Ed25519 public key locally, so every bundle the CLI later loads must be signed by your org.
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.
skillsvault login # opens your browser
skillsvault login --headless # prints the URL + code instead of opening a browser
skillsvault login --url https://skillsvault.io
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-1234 (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 mints an agent key, pins the signing key, saves the config, and sends a first heartbeat to mark the machine online. Ctrl-C cancels the wait cleanly.
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_… \
--url https://skillsvault.io \
--machine ci-runner-7 # defaults to the hostname
--org and --key are required; --url defaults to http://localhost:3000. configure fetches and pins the org's public signing key, then writes the config.
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 → Agent 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 → Agent 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 → Agent keys if it leaks.
Local state
Everything the CLI persists lives under ~/.skillsvault (created 0700):
| File | Mode | Contents |
|---|---|---|
~/.skillsvault/config.json | 0600 | base URL, org slug, agent key, pinned public_key_pem, machine name |
~/.skillsvault/bundle.json | 0600 | the last verified bundle payload + received_at timestamp |
Run skillsvault status to see the current config and bundle freshness. skillsvault logout removes the config (and the bundle, 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 |
Color is only ever emitted to a real terminal, so piped and hook output stays byte-clean.