CLI
Run npx vault from the cloned repository (or npm run vault -- <command>) until the npm package is published. Process environment names are VAULT_*. The local server listens on 8788. vault <command> --help prints the usage for every command.
Environment
| Variable | Purpose |
|---|---|
VAULT_HOME | Vault directory. Default $HOME/.botpasses |
VAULT_MASTER_KEY | 32 bytes as 64 hex characters (or standard base64). Generated by vault init into master.key when unset |
VAULT_PUBLIC_URL | Hosted origin for vault login and vault mcp --user-jwt. First-party botpasses.com, a self-host https origin, or loopback on plane dev |
VAULT_USER_JWT | Access token used by vault mcp --user-jwt |
Commands
| Command | Purpose |
|---|---|
vault init | Create $VAULT_HOME, the SQLite schema, and a master key if needed |
vault set NAME [--host api.example.com]... [--inject MODE] [--username USER] | Read the value from stdin (or a no-echo prompt on a terminal), encrypt, and store. There is no --value flag: argv is visible to every process. Prints the name and last-4, never the value. --host allowlists the APIs http_request may send it to; --inject takes the same modes as hosted (bearer, basic, client_credentials, refresh, sigv4, header:Name, query:param, cookie:name, hmac:...); --username is the HTTP Basic user, OAuth client id, or AWS access key id |
vault list | Names and last-4 |
vault grant --secret NAME --agent A --tool T [--once | --session [--ttl 8h]] | Approve a pending request. --once (the default) is spent by the first use and has no expiry. --session stays active until --ttl elapses (default 8h). --ttl applies to --session only, and the two scope flags exclude each other; either mistake is refused |
vault revoke --id GRANT_ID (or --secret NAME --agent A --tool T) | Stop later injects |
vault audit | Store, grant, revoke, and inject events. No values |
vault run --with NAME --agent A --tool T -- CMD | Inject the value into the child process environment and run the command. Nothing is printed |
vault serve [--host 127.0.0.1] [--port 8788] | Loopback HTTP, the local console, and POST /mcp. Prints two loopback bearers: the operator bearer for /api and the console, the model bearer for POST /mcp. Neither opens the other surface. --port must be a whole number from 1 to 65535 |
vault mcp | MCP over stdio against the local vault (the same six tools as hosted, setup and http_request included) |
vault mcp --remote [URL] | MCP over stdio forwarded to a running vault serve (default http://127.0.0.1:8788) with the model bearer, derived from the master key so nothing is pasted into a client config. Carries the Mcp-Session-Id that initialize returned, so the stdio client is one session on the server |
vault mcp --user-jwt [TOKEN] | MCP over stdio proxied to the hosted server. The token comes from --user-jwt TOKEN, --user-jwt=TOKEN, or VAULT_USER_JWT when the flag is bare; the flag alone selects hosted mode, so a missing token is an error, never the local vault |
vault login | Print the hosted /sign-in, /console, and /device URLs |
vault kek-wrap, vault kek-rotate | Self-hosting only. Wrap or rotate the platform key with AWS KMS. See Self-hosting |
list, grant, and audit never print a secret value.
Example
export VAULT_HOME="$PWD/.botpasses"
npx vault init
printf '%s' 'sk_test_example_not_real' | npx vault set STRIPE_KEY
npx vault list
npx vault grant --secret STRIPE_KEY --agent invoicer --tool stripe --once
npx vault run --with STRIPE_KEY --agent invoicer --tool stripe -- \
node -e 'console.log(Boolean(process.env.STRIPE_KEY))'
npx vault audit
npx vault revoke --secret STRIPE_KEY --agent invoicer --tool stripeHosted login and MCP over stdio
export VAULT_PUBLIC_URL=https://botpasses.com
npx vault login
export VAULT_USER_JWT=eyJ...
npx vault mcp --user-jwtDevice login is RFC 8628: after your authenticator, enter the code shown by the CLI at /device.
Hosted server
VAULT_MODE=hosted vault serve starts the multi-user process (Postgres, KMS, email). It refuses VAULT_HOME and exits with code 78 on configuration errors. Required secrets are listed in Self-hosting.
npm run hosted:dev starts the same kernel on loopback with sqlite-hosted (or --postgres). It writes .botpasses-hosted/ and prints OTP codes in the terminal. Run one process per sqlite file (a second writer can get SQLITE_BUSY). The CLI vault callback stays http://127.0.0.1:8888/callback; hosted connect uses {origin}/connect/callback.