CLI reference

Complete reference for all Agent Vault CLI commands.

Server

agent-vault server

agent-vault server [flags]

Start the Agent Vault server. Default port is 14321. On a fresh install, generates a random data encryption key (DEK) and optionally wraps it with a master password.

Password resolution order: AGENT_VAULT_MASTER_PASSWORD env var, then --password-stdin, then interactive prompt. If no password is provided, runs in passwordless mode (DEK stored unwrapped). The env var is unset from the process immediately after reading.

Flag	Default	Description
--host	127.0.0.1	Host to bind to
--port	14321	Port to listen on. Also respects the PORT env var (common on PaaS platforms); the flag takes precedence.
-d, --detach	false	Run in background (detached) mode
--password-stdin	false	Read master password from stdin
--mitm-port	14322	Port for the transparent MITM proxy. Enabled by default; set to 0 to disable. On first launch the root CA is created under ~/.agent-vault/ca/ — clients fetch it with agent-vault ca fetch. Bind failures are non-fatal.
--log-level	info	Log level: info (default) or debug. At debug, emits one structured line per proxied request on stderr covering method, host, path, matched service, injected credential key names, upstream status, and duration. Credential values are never logged.

Environment variables:

Variable	Description
PORT	Server listen port (default 14321). The --port flag takes precedence.
AGENT_VAULT_MASTER_PASSWORD	Derives a KEK that wraps the data encryption key. Omit for passwordless mode.
AGENT_VAULT_LOG_LEVEL	Fallback for --log-level when the flag is not set. Accepts info or debug.
AGENT_VAULT_ADDR	Externally-reachable base URL (e.g. https://agent-vault.example.com). Used for links in emails, invites, and discovery. Falls back to https://<FLY_APP_NAME>.fly.dev on Fly.io, then http://{host}:{port}.
FLY_APP_NAME	Auto-detected on Fly.io. When AGENT_VAULT_ADDR is unset, derives the base URL as https://<FLY_APP_NAME>.fly.dev.
AGENT_VAULT_OAUTH_GOOGLE_CLIENT_ID	Google OAuth client ID. When both this and the client secret are set, Google OAuth is enabled.
AGENT_VAULT_OAUTH_GOOGLE_CLIENT_SECRET	Google OAuth client secret
AGENT_VAULT_SMTP_HOST	SMTP server host. If unset, email notifications are silently disabled.
AGENT_VAULT_SMTP_PORT	SMTP server port (default 587)
AGENT_VAULT_SMTP_USERNAME	SMTP username
AGENT_VAULT_SMTP_PASSWORD	SMTP password
AGENT_VAULT_SMTP_FROM	Sender address for outgoing emails
AGENT_VAULT_SMTP_FROM_NAME	Sender display name (default Agent Vault)
AGENT_VAULT_SMTP_TLS_MODE	TLS mode: opportunistic (default), required, or none
AGENT_VAULT_SMTP_TLS_SKIP_VERIFY	Skip TLS certificate verification (default false)
AGENT_VAULT_RATELIMIT_PROFILE	Rate-limit profile: default, strict, loose, or off. Affects anonymous auth, token-redeem, proxy, authenticated CRUD, and the global in-flight / RPS ceilings.
AGENT_VAULT_RATELIMIT_LOCK	When true, the rate-limit section in the Manage Instance UI is read-only and UI overrides are ignored. Use when you want limits pinned to env vars on PaaS.
AGENT_VAULT_RATELIMIT_<TIER>_<KNOB>	Fine-grained per-tier overrides. TIER ∈ AUTH, PROXY, AUTHED, GLOBAL. KNOB ∈ RATE, BURST, WINDOW, MAX, CONCURRENCY. Env-set knobs always beat UI overrides.
AGENT_VAULT_LOGS_MAX_AGE_HOURS	Retention ceiling for the per-vault request log. Default 168 (7 days). Rows older than this are trimmed by a background job every 15 minutes. Only non-secret metadata is stored.
AGENT_VAULT_LOGS_MAX_ROWS_PER_VAULT	Per-vault row cap for the request log. Default 10000. Whichever limit (age or rows) fills first wins. Set 0 to disable the cap.
AGENT_VAULT_LOGS_RETENTION_LOCK	When true, owner-UI overrides for log retention are ignored and env values (or defaults) are pinned.

agent-vault server stop

agent-vault server stop

Stop a running server. Reads the PID from ~/.agent-vault/agent-vault.pid and sends SIGTERM.

CA

agent-vault ca fetch

agent-vault ca fetch [flags]

Fetch the root CA certificate used by Agent Vault’s transparent MITM proxy, in PEM form. Install the output into your client trust store so HTTPS traffic routed through the proxy validates cleanly.

The transparent proxy is enabled by default, so this command works out of the box. The endpoint is public — no authentication required. Returns an error only if the server was started with --mitm-port 0.

Flag	Default	Description
-o, --output		Write PEM to file instead of stdout
--address		Server URL

Examples:

# Print to stdout
agent-vault ca fetch > ca.pem

# Save directly to a file
agent-vault ca fetch -o /etc/ssl/certs/agent-vault-ca.pem

# Pipe into the macOS system keychain
agent-vault ca fetch | sudo security add-trusted-cert -d -r trustRoot \
    -k /Library/Keychains/System.keychain /dev/stdin

Authentication

agent-vault auth register

agent-vault auth register [flags]

Self-signup for a new account. The first user to register becomes the instance owner, is auto-activated, and is granted admin on the default vault. Subsequent users receive a 6-digit email verification code.

Flag	Default	Description
--address		Server URL
--email		Email address
--password-stdin	false	Read password from stdin

agent-vault auth login

agent-vault auth login [flags]

Authenticate with email and password. Prompts interactively by default. Rejects inactive (unverified) accounts.

Flag	Default	Description
--address		Server URL
--email		Email address
--password-stdin	false	Read password from stdin

Account

agent-vault account whoami

agent-vault account whoami

Show current user and session info.

agent-vault account change-password

agent-vault account change-password [flags]

Change your own password. Prompts interactively for current password, new password, and confirmation. Invalidates all existing sessions and issues a new one.

Flag	Default	Description
--password-stdin	false	Read current and new passwords as two lines from stdin

agent-vault account delete

agent-vault account delete

Permanently delete your own account. Owners cannot delete themselves — transfer ownership first.

Vaults

agent-vault vault create

agent-vault vault create <name>

Create a new vault. Name must be in slug format (lowercase alphanumeric and hyphens).

agent-vault vault list

agent-vault vault list

List vaults the current user has access to.

agent-vault vault delete

agent-vault vault delete <name> [flags]

Delete a vault and all its credentials, services, and proposals. Requires vault admin or instance owner role. The default vault cannot be deleted.

Flag	Default	Description
--yes	false	Skip confirmation prompt

agent-vault vault rename

agent-vault vault rename <old-name> <new-name>

Rename a vault. Requires vault admin or instance owner role. The default vault cannot be renamed.

agent-vault vault use

agent-vault vault use <name>

Set the active vault for subsequent commands. When set, commands that accept --vault will default to this vault instead of default.

agent-vault vault current

agent-vault vault current

Show the active vault.

agent-vault vault init

agent-vault vault init [flags]

Bind the current directory to a vault by writing an agent-vault.json file. This file is meant to be committed to version control so the whole team shares the vault binding.

Vault resolution priority: --vault flag > AGENT_VAULT_VAULT env var > agent-vault.json > user context > "default".

Uses an interactive picker if multiple vaults are available. Use --vault to skip the picker.

agent-vault vault discover

agent-vault vault discover [flags]

Show available services and credentials for the current vault. Requires a vault-scoped session (via agent-vault vault run or AGENT_VAULT_SESSION_TOKEN + AGENT_VAULT_ADDR env vars).

Flag	Default	Description
--json	false	Output response as JSON

agent-vault vault run

agent-vault vault run [flags] -- <command>

Wrap a process with Agent Vault environment variables. The child process always receives AGENT_VAULT_ADDR, AGENT_VAULT_SESSION_TOKEN, and AGENT_VAULT_VAULT. When the server’s transparent MITM proxy is reachable (default), it also receives HTTPS_PROXY / NO_PROXY / NODE_USE_ENV_PROXY plus CA-trust variables (SSL_CERT_FILE, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, GIT_SSL_CAINFO, DENO_CERT) pointing at ~/.agent-vault/mitm-ca.pem, so standard HTTPS clients transparently route through the broker.

Flag	Default	Description
--address		Server address override
--role	proxy	Vault role for the session: proxy, member, or admin
--ttl	0	Session TTL in seconds (300–604800). Default: server default (24h).
--no-mitm	false	Skip HTTPS_PROXY/CA env injection; rely solely on the explicit /proxy/{host}/{path} endpoint.
--sandbox	process	Sandbox mode for the child: process (default, cooperative) or container (non-cooperative Docker sandbox; see Container sandbox). Also read from AGENT_VAULT_SANDBOX.
--image		Override the bundled container image (--sandbox=container only).
--mount		Extra bind mount src:dst[:ro]; repeatable (--sandbox=container only). Host paths are EvalSymlinks-resolved; reserved paths rejected.
--keep	false	Omit --rm from docker run (--sandbox=container only; useful for debugging).
--no-firewall	false	Skip the iptables egress lockdown (--sandbox=container only; debug, prints a warning).
--home-volume-shared	false	Share /home/claude/.claude across invocations (--sandbox=container only). Default is a per-invocation volume — auth doesn’t persist but concurrent runs can’t corrupt each other.

agent-vault vault token

agent-vault vault token [flags]

Mint a vault-scoped session token and print it to stdout. Useful when you need a scoped token without wrapping a child process via vault run.

Flag	Default	Description
--address		Server address override
--role	proxy	Vault role for the session: proxy, member, or admin
--ttl	0	Session TTL in seconds (300–604800). Default: server default (24h).

# Export token for use in other commands
export AGENT_VAULT_SESSION_TOKEN=$(agent-vault vault token)
export AGENT_VAULT_ADDR=http://localhost:14321
export AGENT_VAULT_VAULT=default

# Mint a short-lived token with member role
agent-vault vault token --vault myproject --role member --ttl 3600

Vault users

agent-vault vault user add

agent-vault vault user add <email> [flags]

Add an existing instance user to a vault (direct grant, no invite needed).

Flag	Default	Description
--vault	default	Target vault
--role	member	Vault role: admin or member

agent-vault vault user list

agent-vault vault user list [flags]

List members of a vault. Includes pending invite pre-assignments with “pending” status.

Flag	Default	Description
--vault	default	Target vault

agent-vault vault user remove

agent-vault vault user remove <email> [flags]

Remove a user from a vault.

Flag	Default	Description
--vault	default	Target vault

agent-vault vault user set-role

agent-vault vault user set-role <email> [flags]

Change a user’s vault-level role.

Flag	Default	Description
--vault	default	Target vault
--role		Vault role: admin or member (required)

Users

agent-vault user list

agent-vault user list

List all users in the instance. Owners see vault memberships; members see email, role, and creation date.

agent-vault user invite

agent-vault user invite <email> [flags]

Invite a user to the Agent Vault instance. Sends an HTML email with an acceptance link if SMTP is configured; always returns the invite_link in the response. Any authenticated user can create invites. Invites optionally pre-assign vault access.

Flag	Default	Description
--role	member	Instance role for the invited user: owner or member
--vault		Vault pre-assignment in name:role format (repeatable). Role defaults to member.

# Invite with vault pre-assignments
agent-vault user invite [e-mail] --vault default:admin --vault payments:member

agent-vault user invite list

agent-vault user invite list [flags]

List user invites. Owners see all invites; others see invites they created or with pre-assignments to vaults they admin.

Flag	Default	Description
--status		Filter by status (e.g. pending)

agent-vault user invite revoke

agent-vault user invite revoke <token_suffix>

Revoke a pending user invite by the last 8 or more characters of the token.

Services

agent-vault vault service list

agent-vault vault service list [flags]

Print the current vault services as YAML.

Flag	Default	Description
--vault	default	Target vault

agent-vault vault service set

agent-vault vault service set [flags]

Set the vault services. Without -f, launches an interactive builder that prompts for services, auth configs, and credentials (requires TTY). With -f, replaces the services from a YAML file.

Flag	Default	Description
--vault	default	Target vault
-f		Path to a YAML services file

agent-vault vault service add

agent-vault vault service add [flags]

Add or update a single service (upsert by host). Use -f to upsert services from a YAML file non-destructively (unlike set -f, which replaces all).

Flag	Default	Description
--vault	default	Target vault
-f		Path to a YAML services file (upsert mode)
--host		Target service host (e.g. api.stripe.com)
--description		Service description
--auth-type		Auth type: bearer, basic, api-key, custom, passthrough
--token-key		Credential key for bearer auth
--username-key		Credential key for basic auth username
--password-key		Credential key for basic auth password
--api-key-key		Credential key for api-key auth
--api-key-header	Authorization	Header name for api-key
--api-key-prefix		Prefix for api-key value
--disabled	false	Create the service in a disabled state (proxy traffic returns 403 until enabled)

The passthrough auth type accepts no credential flags; Agent Vault allowlists the host and forwards the client’s request headers unchanged, stripping only hop-by-hop and broker-scoped headers (X-Vault, Proxy-Authorization).

New services are enabled by default. Pass --disabled to create the service in a disabled state, or use agent-vault vault service disable <host> after creation.

agent-vault vault service enable

agent-vault vault service enable <host> [flags]

Enable a service so proxy traffic to the host resumes. Idempotent — no error if the service is already enabled.

Flag	Default	Description
--vault	default	Target vault

agent-vault vault service disable

agent-vault vault service disable <host> [flags]

Disable a service while preserving its configuration. Agents proxying to the host receive 403 with error code service_disabled until the service is re-enabled. Idempotent.

Flag	Default	Description
--vault	default	Target vault

agent-vault vault service remove

agent-vault vault service remove <host> [flags]

Remove a specific service by host. Prompts for confirmation unless --yes is passed.

Flag	Default	Description
--vault	default	Target vault
--yes	false	Skip confirmation prompt

agent-vault vault service clear

agent-vault vault service clear [flags]

Remove all vault services. Prompts for confirmation unless --yes is passed.

Flag	Default	Description
--vault	default	Target vault
--yes	false	Skip confirmation prompt

Credentials

agent-vault vault credential list

agent-vault vault credential list [flags]

List credential keys in a vault. Alias: agent-vault vault creds list.

Flag	Default	Description
--vault	default	Target vault
--reveal	false	Show decrypted credential values (requires member+ role)

agent-vault vault credential get

agent-vault vault credential get <KEY> [flags]

Print the decrypted value of a single credential to stdout. Pipe-friendly. Requires member+ role. Alias: agent-vault vault creds get.

Flag	Default	Description
--vault	default	Target vault

agent-vault vault credential set

agent-vault vault credential set <KEY=VALUE> [KEY2=VALUE2 ...] [flags]

Store one or more credentials using KEY=VALUE format. Alias: agent-vault vault creds set.

Flag	Default	Description
--vault	default	Target vault

agent-vault vault credential delete

agent-vault vault credential delete <KEY> [KEY2 ...] [flags]

Delete one or more credentials. Alias: agent-vault vault creds delete.

Flag	Default	Description
--vault	default	Target vault

Proposals

agent-vault vault proposal list

agent-vault vault proposal list [flags]

List proposals for a vault.

Flag	Default	Description
--vault	default	Target vault
--status		Filter by status (e.g. pending)

agent-vault vault proposal show

agent-vault vault proposal show <number> [flags]

Show details of a proposal.

Flag	Default	Description
--vault	default	Target vault

agent-vault vault proposal create

agent-vault vault proposal create [flags]

Create a proposal to request services or credentials. Supports two modes: flag-driven (for simple single-service proposals) and JSON file (for complex or multi-service proposals).

Flag	Default	Description
--vault	default	Target vault
-f, --file		Path to JSON proposal file (use - for stdin)
--host		Target service host (e.g. api.stripe.com)
--description		Service description
--auth-type		Auth type: bearer, basic, api-key, or passthrough
--token-key		Credential key for bearer auth
--username-key		Credential key for basic auth username
--password-key		Credential key for basic auth password
--api-key-key		Credential key for api-key auth
--api-key-header		Header name for api-key (default Authorization)
--api-key-prefix		Prefix for api-key value
--credential		Credential to request: KEY or KEY=description (repeatable)
-m, --message		Proposal message/reason
--user-message		Human-facing explanation for the browser approval page
--json	false	Output response as JSON

# Flag-driven: request a bearer-auth service with a credential
agent-vault vault proposal create \
  --host api.stripe.com \
  --auth-type bearer \
  --token-key STRIPE_KEY \
  --credential STRIPE_KEY="Stripe secret key" \
  -m "Need Stripe access for payment processing"

# JSON file: complex multi-service proposal
agent-vault vault proposal create -f proposal.json

agent-vault vault proposal approve

agent-vault vault proposal approve <number> [KEY=VALUE ...] [flags]

Approve and apply a proposal. Requires an active login session. Pass credential values as KEY=VALUE arguments or the command will prompt for any missing credentials.

Flag	Default	Description
--vault	default	Target vault
--yes	false	Skip confirmation prompt

agent-vault vault proposal reject

agent-vault vault proposal reject <number> [flags]

Reject a pending proposal. Requires an active login session.

Flag	Default	Description
--vault	default	Target vault
--reason		Rejection reason

agent-vault vault proposal review

agent-vault vault proposal review [flags]

Interactively walk through all pending proposals. For each proposal you can approve, reject, skip, or quit. Requires an active login session.

Flag	Default	Description
--vault	default	Target vault

Agents (instance-level)

agent-vault agent invite

agent-vault agent invite <name> [flags]

Create an agent invite and print the onboarding prompt (copies to clipboard). The agent redeems the invite via HTTP and receives an instance-level agent token.

Flag	Default	Description
--role	member	Instance-level role: owner or member
--vault		Vault pre-assignment in name:role format (repeatable). Role defaults to proxy.
--invite-ttl	15m	Invite link expiration time (Go duration format)
--address		Agent Vault server address (default: from session)
--token-only	false	Output only the raw invite token (for programmatic use)

# Invite with vault pre-assignments
agent-vault agent invite my-agent --vault default:proxy --vault payments:member

# Invite as an instance owner
agent-vault agent invite my-agent --role owner --vault default:admin

agent-vault agent invite list

agent-vault agent invite list [flags]

List agent invites.

Flag	Default	Description
--status		Filter by status (e.g. pending)

agent-vault agent invite revoke

agent-vault agent invite revoke <token_suffix>

Revoke a pending invite by the last 8 or more characters of the token.

agent-vault agent list

agent-vault agent list

List all agents across the instance.

agent-vault agent info

agent-vault agent info <name>

Show agent details including vaults, status, and active session count.

agent-vault agent delete

agent-vault agent delete <name>

Delete an agent and all its sessions across all vaults.

agent-vault agent rotate

agent-vault agent rotate <name>

Create a rotation invite to re-issue an agent’s session. The old sessions are invalidated when the agent redeems the new invite.

agent-vault agent rename

agent-vault agent rename <name> <new-name>

Rename an agent. Keeps the same vault access.

agent-vault agent set-role

agent-vault agent set-role <name> [flags]

Change an agent’s instance-level role. The last owner (across both users and agents) cannot be demoted.

Flag	Default	Description
--role		Instance role: owner or member (required)

Agents (vault-level)

agent-vault vault agent list

agent-vault vault agent list [flags]

List agents in a specific vault.

Flag	Default	Description
--vault	default	Target vault

agent-vault vault agent add

agent-vault vault agent add <name> [flags]

Add an existing instance agent to a vault.

Flag	Default	Description
--vault	default	Target vault
--role	proxy	Vault role: proxy, member, or admin

agent-vault vault agent remove

agent-vault vault agent remove <name> [flags]

Remove an agent from a vault.

Flag	Default	Description
--vault	default	Target vault

agent-vault vault agent set-role

agent-vault vault agent set-role <name> [flags]

Change an agent’s vault role.

Flag	Default	Description
--vault	default	Target vault
--role		Vault role: proxy, member, or admin (required)

Owner — users

agent-vault owner user list

agent-vault owner user list

List all users on the instance. Owner only.

agent-vault owner user info

agent-vault owner user info [email]

View user info and vault memberships. If no email is provided, shows your own info. Owner can view any user; members can only view themselves.

agent-vault owner user remove

agent-vault owner user remove <email>

Remove a user from the instance. Owner only.

agent-vault owner user set-role

agent-vault owner user set-role <email> [flags]

Change a user’s instance-level role. The last owner cannot be demoted. Owner only.

Flag	Default	Description
--role		Instance role: owner or member (required)

Owner — vaults

agent-vault owner vault list

agent-vault owner vault list

List all vaults on the instance. Owner only.

agent-vault owner vault join

agent-vault owner vault join <name>

Join a vault as admin. Useful for recovering orphaned vaults. Owner only. Returns 409 if already a member.

agent-vault owner vault delete

agent-vault owner vault delete <name>

Delete a vault. Owner only.

Owner — config

agent-vault owner config get

agent-vault owner config get

Show current instance settings including invite_only and allowed_email_domains. Owner only.

agent-vault owner config set

agent-vault owner config set [flags]

Update instance settings. Owner only.

Flag	Default	Description
--invite-only		Enable or disable invite-only registration (true or false)
--allowed-domains		Comma-separated list of allowed email domains (empty to clear)

Master password

Manage the master password that wraps the data encryption key (DEK). All commands require the server to be stopped.

agent-vault master-password set

agent-vault master-password set

Set a master password on a passwordless instance. Wraps the existing DEK under a new KEK derived from the password. No credentials are re-encrypted.

agent-vault master-password change

agent-vault master-password change

Change the master password. Re-wraps the DEK under a new KEK. No credentials are re-encrypted.

agent-vault master-password remove

agent-vault master-password remove

Remove the master password, switching to passwordless mode. The DEK is stored in plaintext — security depends on filesystem access controls.

Utilities

agent-vault catalog

agent-vault catalog [flags]

Browse built-in service templates. No authentication required.

Flag	Default	Description
--json	false	Output response as JSON
--address		Server address (default: auto-detect)

agent-vault owner email test

agent-vault owner email test [flags]

Send a test email to verify SMTP configuration. Owner only.

Flag	Default	Description
--to	Owner’s email	Recipient email address
--address		Server address override

agent-vault owner reset

agent-vault owner reset [flags]

Permanently delete all data and reset the instance to a fresh state. Requires a running server for role verification. Auto-stops the server before wiping data. Owner only.

Flag	Default	Description
--yes	false	Skip confirmation prompt

agent-vault version

agent-vault version

Print the version and build information.

Installer

The install.sh script (curl -fsSL https://get.agent-vault.dev | sh) is not part of the agent-vault binary but reads one environment variable:

Variable	Default	Description
AGENT_VAULT_NO_TELEMETRY	(unset)	When set to any non-empty value, skips the anonymous install/upgrade beacon (OS, architecture, version — nothing else). Must be placed in front of sh, not curl: curl -fsSL https://get.agent-vault.dev | AGENT_VAULT_NO_TELEMETRY=1 sh.