tvault CLI

tvault is the Token Vault command-line client. It mirrors the web console: manage tokens, agents, grants, and the vault lock, with a browser-based login and kubectl-style contexts for switching between admin and agent personas.

tvault login                # browser-based admin login
tvault ls                   # list tokens
tvault get github           # print a credential to stdout — safe for $(...)
tvault add stripe --value sk_test_...     # create a token
tvault set stripe --value sk_test_new     # rotate it

The CLI is a single Go binary; full source at c-lgrant/tvault.

Install

With the Go toolchain:

go install github.com/c-lgrant/tvault@latest

Or grab a prebuilt binary (Linux/macOS, amd64/arm64). The installer detects your OS/arch, downloads the matching GitHub release, and verifies its SHA256:

curl -fsSL https://raw.githubusercontent.com/c-lgrant/tvault/main/install.sh | bash

Contexts: admin vs. agent

tvault stores one or more contexts, each holding either an admin login (Firebase identity, full console access) or an agent login (a tvagent_* key, scoped to its grants). Commands resolve the active context automatically; override it per-invocation with --context <name> (alias --ctx).

Top-level shortcuts

The most common verbs are available at the root level so you don't have to type tokens / context / agents grants for every operation.

The bare tvault <service> form is the legacy back-compat shim and still works — it prints that service's credential to stdout.

Tokens — tvault tokens (tk)

Token types offered by tk new: JWT (OAuth · JWT), PlainText (API key / PAT), Certificate (X.509), SSHKey, RawCredential (raw blob), and TOTP (2FA).

Agents — tvault agents (ag)

Agent references (<name-or-id>) accept either the human-readable name or the backend-assigned ID — the CLI resolves names through agents list.

Grants — tvault grants (gr)

tvault grant <agent> <service>... is the flat-verb shortcut for gr add.

Vault — tvault vault

Webhook — tvault webhook (wh)

Deploy and connect your own Webhook Mode vault. The CLI generates the Docker Compose project and binds the webhook to your vault without a browser, reusing your admin context's session.

Typical first run:

tvault webhook init          # pick a method, answer the prompts
cd tvault-webhook
tvault webhook up            # start it
tvault webhook bind          # connect it to your vault

Global flags

Examples

Use tokens in API calls

# GitHub
curl -H "Authorization: token $(tvault get github)" https://api.github.com/user

# Anthropic Claude
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $(tvault get anthropic)" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'

# OpenAI
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $(tvault get openai)" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

Use in CI/CD

Log in as an agent (one-time, non-interactive) and read tokens from any job:

- name: Set up tvault
  env:
    TV_AGENT_KEY: ${{ secrets.TV_AGENT_KEY }}
  run: |
    curl -fsSL https://raw.githubusercontent.com/c-lgrant/tvault/main/install.sh | bash
    tvault login --key "$TV_AGENT_KEY" --as ci

- name: Deploy
  run: |
    export DEPLOY_TOKEN=$(tvault get deploy-service)
    ./deploy.sh

Check whether a token exists before using it

--check is a presence-only probe — exits 0 when the token has a value, 6 when it's an empty placeholder, and never prints the secret:

if tvault get stripe --check >/dev/null 2>&1; then
  ./pay-with-stripe
else
  echo "no stripe token yet — set one with: tvault set stripe --value <key>"
fi

Switch contexts mid-pipeline

tvault --ctx production get github   # read from prod context
tvault --ctx staging set github --value $(tvault --ctx production get github)

How agent fetches work

1. Create an agent in the dashboard (or via tvault ag new) and copy the tvagent_* API key.
2. Grant the agent access to specific services. Grants are time-limited and revocable; every access is logged in the audit trail.
3. The agent calls GET /api/agents/credentials?service=<name> with the key in X-Agent-Key. In Webhook mode the request 307-redirects to the user's webhook so the secret never traverses Token Vault.
4. The CLI prints the credential to stdout — $(tvault get <svc>) captures it inline without writing to disk.

Claude Code integration

Once tvault is installed and logged in, Claude Code can fetch credentials using the same $(tvault get <svc>) pattern. The credential lives on stdout for the lifetime of one shell substitution; no token ever lands in your config files or environment unless you explicitly export it.

Requirements

• Linux or macOS (amd64 or arm64). Windows is not currently supported.
• A working browser for the initial admin login, or an existing tvagent_* key for tvault login --key.