A JSON-first command surface.

Argument grammar#

One command name, then positional values, then options. An option is written either as two words or joined by an equals sign, and a bare option with no value that follows it is simply present. Long-running process interfaces — serve, mcp, native-host, and the sync daemon — are the exception to the one-JSON-value rule; every finite command prints one JSON value to stdout.

Options are single-valued: repeating one keeps the last value rather than accumulating a list. Commands that take several values use a comma-separated option or several positional values. In particular, the fields written by set are positional name and value pairs, not a repeated field option.

skarbiec <command> [positionals...] [--key value | --key=value] [--flag]

Vault items#

init creates the vault sealed to a fresh gpg owner key and a recovery key. set writes a schema-validated typed item; get returns one item's decrypted fields as JSON; list returns metadata only — id, item_uid, kind, state, revision, management, tags, recipients, and timestamps — never values. delete moves an item to a recoverable trash, and restore-version rolls an item back by timestamp.

rename changes an item's id and keeps everything else: the envelope moves whole, so the identifier, history, revision, tags, recipients, management, and the ciphertext are the same bytes under the new name, and nothing is decrypted on the way. It is owner-controlled items only. backfill-item-uids stamps a permanent identifier onto every item written before that field existed, touches the cleartext envelope only, and is idempotent.

skarbiec set github --type login \
  username=alice@example.com password=correct-horse-battery-staple \
  --tags dev,ci
skarbiec get github
skarbiec list --all
skarbiec rename github github-primary
skarbiec backfill-item-uids
skarbiec restore-version github-primary 2026-07-01T12:00:00Z

Access: the declared consumer grant and acquisition#

One group answers the whole declared consumer grant. grant issue registers exact structured capabilities for a consumer; grant list reports consumers, capabilities, expiry, audience, and whether each identity is workload-bound; grant verify checks one exact action/resource/field binding, from --token or an owner-only --token-file; grant revoke drops a grant or workload identity; grant capability issues one bounded, use-counted redemption of a declaration against a routed resource.

acquisition-request verifies an Ed25519 workload proof and issues the opaque short-TTL bearer; acquisition-read returns only the bound field and atomically consumes the bearer.

Grants are edited, not mutated in place. Re-issuing the same consumer with the same capabilities rotates the bearer: a new value is shown once and the old one stops verifying. Changing the capability set is refused unless the call states --replace-capabilities, which rewrites the scope and rotates the bearer. grant ensure widens an existing direct grant by one exact field read without rotating anything — the owner proves possession through a 0600 --token-file that must hash to the recorded bearer. Direct grants expire after --ttl-seconds (default 30 days); the vault stores only the bearer's hash, so no listing or backup can leak the value.

skarbiec grant issue ci --capabilities acquire:github#password \
  --workload-public-key-file ci.pub.pem
skarbiec acquisition-request ci github password \
  --workload-id ci-1 --workload-timestamp "$EPOCH" \
  --workload-nonce "$NONCE" --workload-signature "$SIG_HEX"
skarbiec acquisition-read ci github password --token "$ONE_USE_TOKEN"

# Edit an existing grant
skarbiec grant issue ci --capabilities read:github#username \
  --replace-capabilities true   # rewrite scope, rotate bearer
skarbiec grant ensure ci github --field password \
  --token-file bearer.txt       # widen by one field, keep bearer

Servers: serve, mcp, native-host#

serve starts the loopback HTTP API — it binds 127.0.0.1 only, on port 8787 unless --port says otherwise. mcp starts the stdio Model Context Protocol server for agents. native-host runs the length-framed browser native-messaging bridge, and browser-host-install rotates the narrow browser grant and registers the installed host.

skarbiec serve --port 8787
skarbiec mcp
skarbiec native-host

Diagnostics and audit#

• status — vault path and non-sensitive counts of items, recipients, tokens, and bonds.
• key-doctor — whether any key on this machine can still open the vault, reading vault and keyring directly so it answers while the service is down.
• doctor — vault, audit chain, canonical endpoint, WORM receipts, and consumer grants, each pass, fail, or not_configured. The grants check tests every live grant against the vault it names and decrypts nothing.
• audit-query — local provenance by operation, consumer, item, and time window, without decrypting a credential.
• verify-chain — recompute journal linkage and digests and name the file it verified.

The full inventory#

Every public command has a dedicated page below, and skarbiec help remains the machine-readable top-level inventory.

skarbiec help