CLI reference

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 [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 [email protected] --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`.

Getting Started

Quickstart

Guides

Learn

Resources

Server

Database migration

CA

Authentication

Account

Vaults

Vault users

Users

Services

Credentials

Proposals

Agents (instance-level)

Agents (vault-level)

Owner — users

Owner — vaults

Owner — config

Master password

Utilities

Installer

​Server

​Database migration

​CA

​Authentication

​Account

​Vaults

​Vault users

​Users

​Services

​Credentials

​Proposals

​Agents (instance-level)

​Agents (vault-level)

​Owner — users

​Owner — vaults

​Owner — config

​Master password

​Utilities

​Installer

Server

Database migration

CA

Authentication

Account

Vaults

Vault users

Users

Services

Credentials

Proposals

Agents (instance-level)

Agents (vault-level)

Owner — users

Owner — vaults

Owner — config

Master password

Utilities

Installer