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.
--max-response-bytes	0 (unlimited)	Maximum response body bytes the MITM proxy streams back to agents. 0 means unlimited — responses are streamed with a small buffer so there is no memory risk. When a limit is set and the upstream response exceeds it, the proxy returns 502 (if the size is known upfront) or aborts the connection mid-stream (if chunked). Also respects AGENT_VAULT_MAX_RESPONSE_BYTES; the flag takes precedence.
--max-request-bytes	1073741824 (1 GiB)	Maximum request body bytes the MITM proxy forwards to upstreams. Requests exceeding this receive HTTP 413. Also respects AGENT_VAULT_MAX_REQUEST_BYTES; the flag takes precedence.
--database-url	(empty, SQLite)	PostgreSQL connection URL for production deployments. When set, Agent Vault uses Postgres instead of the built-in SQLite database. Also respects DATABASE_URL; the flag takes precedence.
--telemetry	true	Enable or disable anonymous usage telemetry. Also respects the AGENT_VAULT_TELEMETRY env var; the env var takes precedence.

Environment variables:

Variable	Description
PORT	Server listen port (default 14321). The --port flag takes precedence.
DATABASE_URL	PostgreSQL connection URL (e.g. postgres://user:pass@host:5432/agentvault). When set, Agent Vault uses Postgres instead of SQLite. The --database-url flag takes precedence. See PostgreSQL.
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_MAX_RESPONSE_BYTES	Maximum response body bytes streamed to agents (default 0 = unlimited). The --max-response-bytes flag takes precedence.
AGENT_VAULT_MAX_REQUEST_BYTES	Maximum request body bytes forwarded to upstreams (default 1073741824 = 1 GiB). The --max-request-bytes flag takes precedence.
AGENT_VAULT_ADDR	Externally-reachable base URL (e.g. https://agent-vault.example.com). Used for links in emails, invites, and discovery, and the hostname is added as a SubjectAltName on every MITM leaf cert so clients that TLS-verify against the proxy’s own hostname succeed without a shim. Falls back to https://<FLY_APP_NAME>.fly.dev on Fly.io, then http://{host}:{port}. The Connect Your Agent modal pre-fills the agent address from this value when set; when unset, the modal renders a literal <AGENT_VAULT_ADDR> placeholder.
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_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.
INFISICAL_URL	Base URL of an Infisical instance. When set, the server constructs a machine-identity client from one of the auth-method groups below and enables --credential-store=infisical on vault create. See Credential stores for the conceptual overview and Environment variables: Infisical credential store for the priority order when multiple groups are configured.
INFISICAL_UNIVERSAL_AUTH_CLIENT_ID	Universal Auth client ID. Set together with INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET.
INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET	Universal Auth client secret. Set together with INFISICAL_UNIVERSAL_AUTH_CLIENT_ID.
INFISICAL_KUBERNETES_IDENTITY_ID	Kubernetes Auth identity ID. Service-account token is read from INFISICAL_KUBERNETES_SERVICE_ACCOUNT_TOKEN_PATH if set, else the SDK’s default projected-token path.
INFISICAL_KUBERNETES_SERVICE_ACCOUNT_TOKEN_PATH	Override for the projected SA-token path (default /var/run/secrets/kubernetes.io/serviceaccount/token).
INFISICAL_AWS_IAM_AUTH_IDENTITY_ID	AWS IAM Auth identity ID. Credentials come from the standard AWS resolver chain.
INFISICAL_GCP_AUTH_IDENTITY_ID	GCP Auth identity ID. Shared by both GCP IAM and GCP ID Token; IAM wins when both methods are otherwise complete.
INFISICAL_GCP_IAM_SERVICE_ACCOUNT_KEY_FILE_PATH	Path to a GCP service-account key file. Required to select GCP IAM; absent means GCP ID Token.
INFISICAL_LDAP_AUTH_IDENTITY_ID	LDAP Auth identity ID. All three LDAP vars are required together.
INFISICAL_LDAP_AUTH_USERNAME	LDAP bind username.
INFISICAL_LDAP_AUTH_PASSWORD	LDAP bind password.
AGENT_VAULT_TELEMETRY	Set to false to disable anonymous usage telemetry. No credential values or request payloads are ever included.

agent-vault server stop

agent-vault server stop

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

Database migration

agent-vault migrate-db

agent-vault migrate-db [flags]

Copy all data from the current SQLite database to a PostgreSQL instance. The server must be stopped before running this command. The source SQLite database is not modified.

After a successful migration, set DATABASE_URL (or --database-url on the server) and restart. See PostgreSQL for the full guide.

Flag	Default	Description
--to		Destination PostgreSQL connection URL (required). Example: postgres://user:pass@host:5432/agentvault.
--from	~/.agent-vault/agent-vault.db	Source SQLite database path. Override only if using a non-default data directory.
--dry-run	false	Validate connectivity and print a row-count summary without writing any data.
--yes, -y	false	Skip the interactive confirmation prompt. Useful for scripted or CI usage.

# Preview what would be migrated
agent-vault migrate-db --to postgres://user:pass@db:5432/agentvault --dry-run

# Run the migration
agent-vault migrate-db --to postgres://user:pass@db:5432/agentvault

# Run without confirmation (scripted/CI)
agent-vault migrate-db --to postgres://user:pass@db:5432/agentvault --yes

# Migrate from a non-default SQLite path
agent-vault migrate-db --from /data/.agent-vault/agent-vault.db \
  --to postgres://user:pass@db:5432/agentvault

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.

Sessions are long-lived: 1 year absolute, 30 days idle. Active operators effectively never have to log in again. A session that goes 30 days without making a request is automatically expired.

Flag	Default	Description
--address		Server URL
--email		Email address
--password-stdin	false	Read password from stdin
--device-label	hostname	Label shown in auth sessions list

agent-vault auth sessions list

agent-vault auth sessions list

List active sessions for your account, with the device label, last IP, last activity, and expiry. The session being used for this request is marked with a checkmark in the Current column.

agent-vault auth sessions revoke

agent-vault auth sessions revoke <id>

Revoke a specific session by id (from auth sessions list). Use this to invalidate a stolen ~/.agent-vault/session.json or to log out a forgotten device. Revoking your current session forces you to log in again on this device.

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> [flags]

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

Without flags the vault is “built-in”: credentials are stored locally and managed through Agent Vault. With --credential-store=infisical, Agent Vault probes Infisical with the supplied config, encrypts the snapshot, and commits the vault, credentials, and your admin grant atomically. If the probe fails nothing is persisted. See Credential stores.

External-store vault creation requires instance-owner role. Non-owners receive 403 Owner role required to create external-store vaults because the broker’s configured machine identity, not the caller’s, authorizes the upstream fetch.

Flag	Default	Description
--credential-store	builtin	Credential store kind: builtin or infisical. Switchable later with vault credential-store set.
--infisical-project-id		Infisical project ID. Required when --credential-store=infisical.
--infisical-environment		Infisical environment slug (e.g., dev, prod). Required when --credential-store=infisical.
--infisical-path	/	Infisical secret path (must start with /).
--poll-interval-seconds	60	Refresh cadence floor for the cached secrets. Minimum 10s. The server wakes every 10s and refreshes any vault past its interval, so actual cadence rounds up to the next 10s boundary.

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 credential-store show

agent-vault vault credential-store show <name>

Print the vault’s credential-store kind, full config, poll interval, and last sync health. Prints Credential store: builtin for vaults with no external source; otherwise the kind name plus the Infisical project, environment, path, poll cadence, and last_sync_status / last_synced_at / last_sync_error. This command is read-only; use credential-store set to change the kind.

agent-vault vault credential-store set

agent-vault vault credential-store set <name> --kind=<builtin|infisical> [flags]

Switch the credential store backing an existing vault. Switching to builtin requires vault admin or instance owner role; switching to infisical requires instance-owner role (the broker’s machine identity authorizes the upstream fetch). Prompts for the vault name to confirm unless --yes is passed.

Switching to infisical probes the source (same validation as create), then overwrites the vault’s built-in credentials with the fetched snapshot and starts polling. Switching to builtin disconnects the external source (polling stops) but keeps the last synced secrets in place as editable built-in credentials. See Credential stores.

Flag	Default	Description
--kind		Target credential store kind: builtin or infisical. Required.
--infisical-project-id		Infisical project ID. Required when --kind=infisical.
--infisical-environment		Infisical environment slug (e.g., dev, prod). Required when --kind=infisical.
--infisical-path	/	Infisical secret path (must start with /).
--poll-interval-seconds	60	Refresh cadence floor for the cached secrets. Minimum 10s.
--yes	false	Skip confirmation prompt

agent-vault vault credential-store sync

agent-vault vault credential-store sync <name>

Force an immediate refresh of an external-store vault and print the post-refresh credential-store summary. Available to any vault member. Returns an error if the vault is built-in (no external source), if Infisical is not configured on the server, or if another refresh is already in flight (409). The periodic syncer keeps the vault fresh on its own; use this when a secret has just been rotated upstream and you don’t want to wait for the next tick.

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 token or long-lived agent token (via agent-vault run or AGENT_VAULT_TOKEN + AGENT_VAULT_ADDR env vars). In agent mode (AGENT_VAULT_TOKEN set), AGENT_VAULT_VAULT (or --vault) is required — there is no project-file or interactive-picker fallback.

Flag	Default	Description
--json	false	Output response as JSON

agent-vault run (alias: agent-vault vault run)

agent-vault run [flags] -- <command>
# Long form — identical behavior:
agent-vault vault run [flags] -- <command>

Wrap a process with Agent Vault environment variables. agent-vault run is the shorthand; agent-vault vault run is the long form. Both are identical in behavior and flags.

The child process receives AGENT_VAULT_ADDR, AGENT_VAULT_TOKEN, and AGENT_VAULT_VAULT, plus HTTPS_PROXY / HTTP_PROXY / NO_PROXY / NODE_USE_ENV_PROXY / OPENCLAW_PROXY_URL and 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 HTTP and HTTPS clients transparently route through the broker. OPENCLAW_PROXY_URL feeds OpenClaw’s Proxyline managed proxy (OpenClaw requires this plus proxy.enabled: true in its config). HTTPS_PROXY and HTTP_PROXY both point at the same plain HTTP proxy URL — the listener handles CONNECT for https:// upstreams and absolute-form forward-proxy requests for http:// upstreams on the same port. If the server’s MITM proxy is unreachable, vault run aborts.

Agent mode (containerized / unattended deployments). When AGENT_VAULT_TOKEN and AGENT_VAULT_ADDR are pre-set on the environment, vault run skips the admin-session login and uses the env-supplied token as the credential — --ttl is rejected in this mode since the token’s lifetime is fixed at mint time. The token is validated against the broker once at startup so bad/expired tokens fail fast with a clear error rather than producing 401s on every proxied call. See Deploy your agent in a container.

Flag	Default	Description
--address		Server address override
--ttl	0	Session TTL in seconds (300–604800). Default: server default (24h).
--isolation	host	Isolation mode for the child: host (default, cooperative — runs on the host with HTTPS_PROXY/HTTP_PROXY) or container (non-cooperative Docker container; see Container isolation). Also read from AGENT_VAULT_ISOLATION.
--image		Override the bundled container image (--isolation=container only).
--mount		Extra bind mount src:dst[:ro]; repeatable (--isolation=container only). Host paths are EvalSymlinks-resolved; reserved paths rejected.
--keep	false	Omit --rm from docker run (--isolation=container only; useful for debugging).
--no-firewall	false	Skip the iptables egress lockdown (--isolation=container only; debug, prints a warning).
--home-volume-shared	false	Share /home/claude/.claude across invocations via a persistent docker volume (--isolation=container only). Default is a per-invocation volume — auth doesn’t persist but concurrent runs can’t corrupt each other.
--share-agent-dir	false	Bind-mount the host’s agent state dir (~/.claude) at /home/claude/.claude so the container reuses your host login (--isolation=container only). On Linux the container’s claude user is remapped to your host uid/gid so writes land owned by you. Mutually exclusive with --home-volume-shared.
--telemetry	true	Enable or disable anonymous usage telemetry. Also respects the AGENT_VAULT_TELEMETRY env var; the env var takes precedence.

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 agent-vault run. Tokens are minted with vault role proxy.

Flag	Default	Description
--address		Server address override
--ttl	0	Session TTL in seconds (300–604800). Default: server default (24h).

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

# Mint a short-lived token (1 hour TTL)
agent-vault vault token --vault myproject --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, member, or no-access
--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 name). 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)
--name		Service name (slug, 3–64 lowercase alphanumeric/hyphen chars). Required for new services. May be omitted when --host uniquely matches an existing service — the server adopts that service’s name (same pattern as service remove by host).
--host		Target host with optional port and path glob (e.g. api.stripe.com, internal.corp.com:3000, slack.com/api/*). When a port is included, the service matches only traffic to that port. The server splits the host, port, and path on ingest.
--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 but does not store or inject a credential. See Header forwarding for the rules that apply across every auth type — passthrough simply has no auth slot to override.

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

To layer two credentials on the same host, give them different inline paths in --host (e.g. Slack with slack.com/api/* for the Bot token and slack.com/api/apps.connections.* for Socket Mode). The matcher resolves overlapping rules deterministically — see Matching priority.

URL substitutions are file-only — there are no flags. Configure them under the substitutions: block of a service entry in a YAML file passed via -f.

agent-vault vault service enable

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

Enable a service so proxy traffic resumes. The argument is matched against service names first, then host. When more than one service shares the host, the server returns 409 with the candidate names — retry with the specific name. Idempotent.

Flag	Default	Description
--vault	default	Target vault

agent-vault vault service disable

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

Disable a service while preserving its configuration. Agents proxying to it receive 403 with error code service_disabled until re-enabled. The argument is matched against service names first, then host (with the same 409-on-ambiguity behavior as enable). Idempotent.

Flag	Default	Description
--vault	default	Target vault

agent-vault vault service remove

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

Remove a specific service. The argument is matched against service names first, then host (409 on ambiguity). 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. In agent mode (AGENT_VAULT_TOKEN set), AGENT_VAULT_VAULT (or --vault) is required — there is no project-file or interactive-picker fallback.

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. In agent mode (AGENT_VAULT_TOKEN set), AGENT_VAULT_VAULT (or --vault) is required — there is no project-file or interactive-picker fallback.

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. In agent mode (AGENT_VAULT_TOKEN set), AGENT_VAULT_VAULT (or --vault) is required — there is no project-file or interactive-picker fallback.

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. In agent mode (AGENT_VAULT_TOKEN set), AGENT_VAULT_VAULT (or --vault) is required — there is no project-file or interactive-picker fallback.

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). In agent mode (AGENT_VAULT_TOKEN set), AGENT_VAULT_VAULT (or --vault) is required — there is no project-file or interactive-picker fallback.

Flag	Default	Description
--vault	default	Target vault
-f, --file		Path to JSON proposal file (use - for stdin)
--name		Service name (slug, 3–64 lowercase alphanumeric/hyphen chars). Required for new services. May be omitted when --host uniquely matches an existing service — the server adopts that service’s name (same pattern as host-based delete).
--host		Target host with optional port and path glob (e.g. api.stripe.com, internal.corp.com:3000, slack.com/api/*). When a port is included, the service matches only traffic to that port.
--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 \
  --name stripe \
  --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

URL substitutions are JSON-only — there are no flags. Add a substitutions array under the relevant services[] entry in the file passed via -f.

OAuth credentials are JSON-only. Set type: "oauth" on the credential slot and include an oauth config object:

{
  "credentials": [{
    "action": "set",
    "key": "GITHUB",
    "type": "oauth",
    "oauth": {
      "authorization_url": "https://github.com/login/oauth/authorize",
      "token_url": "https://github.com/login/oauth/access_token",
      "scopes": "repo user"
    },
    "description": "GitHub OAuth"
  }]
}

See OAuth credentials for field details.

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 create

agent-vault agent create <name> [flags]

Create a new instance-level agent and print its token (copies to clipboard). Supply the token to the agent’s runtime via AGENT_VAULT_TOKEN.

Flag	Default	Description
--role	no-access	Instance-level role: owner, member, or no-access
--vault		Vault pre-assignment in name:role format (repeatable). Role defaults to proxy.
--token-only	false	Output only the raw agent token (for programmatic use)
--address		Agent Vault server address (defaults to session address)

# Create with vault pre-assignments
agent-vault agent create my-agent --vault default:proxy --vault payments:member

# Create as an instance owner
agent-vault agent create my-agent --role owner --vault default:admin

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 revoke

agent-vault agent revoke <name>

Revoke an agent and invalidate all its tokens. The agent remains visible with a “revoked” status but can no longer authenticate. Rotate its token to reactivate it.

agent-vault agent delete

agent-vault agent delete <name>

Permanently delete an agent, its tokens, and all vault grants. Works on both active and revoked agents.

agent-vault agent rotate

agent-vault agent rotate <name> [flags]

Invalidate the agent’s existing token and print a new one. If the agent is revoked, rotation also reactivates it. Update AGENT_VAULT_TOKEN wherever the agent runs.

Flag	Default	Description
--token-only	false	Output only the raw agent token (for programmatic use)

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, member, or no-access (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, member, or no-access (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. When DATABASE_URL is set, these commands require --force because multiple instances may share the database — stop all instances first.

Password changes only re-wrap the encryption key (one database row). No credentials are re-encrypted and no data is lost. If an instance restarts before the secret store is updated, it will fail to start with “wrong password” — update the secret and restart to resolve.

agent-vault master-password set

agent-vault master-password set [--force]

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.

Flag	Description
--force	Proceed when DATABASE_URL is set. Requires all instances to be stopped.

agent-vault master-password change

agent-vault master-password change [--force]

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

Flag	Description
--force	Proceed when DATABASE_URL is set. Requires all instances to be stopped.

agent-vault master-password remove

agent-vault master-password remove [--force]

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

Flag	Description
--force	Proceed when DATABASE_URL is set. Requires all instances to be stopped.

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 --proto '=https' --proto-redir '=https' --tlsv1.2 -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 --proto '=https' --proto-redir '=https' --tlsv1.2 -fsSL https://get.agent-vault.dev | AGENT_VAULT_NO_TELEMETRY=1 sh.