Keys & projects
Pick the project the CLI works in, then manage its encrypted keys — and, for projects in custom encryption mode, supply the vault key that unlocks them.
projects — Manage workspace context
Manage and switch between your ApiVault projects. Commands automatically resolve project context locally from your repository root (via .apivault.json) before falling back to global user defaults, unless explicitly overridden with -p, --project.
Role-Based Access Control (RBAC)
Your permissions within a project dictate what CLI actions you can perform:
- Owner/Admin: Full access to manage project settings and keys.
- Editor: Can manage and reveal keys (e.g.,
apivault keys add,apivault run). - Viewer: Can only view keys (e.g.,
apivault keys list, and reveal if permitted).
projects list
Lists all projects you are a member of, along with their roles and IDs.
apivault projects list
projects use & link
Set the active project for the current working directory (saves to .apivault.json). Pass --global (-g) to set the system-wide fallback project.
# Bind current directory to a project (saves .apivault.json) apivault projects use <id> # Dedicated linking shortcut apivault link <id> # Set global fallback project apivault projects use <id> --global
projects current
Display the currently active project and the source it was resolved from (CLI flag, environment variable, local .apivault.json, or global config).
apivault projects current
projects unlink
Remove the local project binding (.apivault.json) from the current directory.
apivault unlink
keys — Manage stored API keys
keys list
Lists all vault keys for the connected account. Key values are masked by default.
apivault keys list
keys add
Interactive by default. Fully non-interactive for scripting:
apivault keys add \ --name STRIPE_SECRET \ --service Stripe \ --environment Production \ --key "sk_live_..." \ --notes "Billing API"
Interactive defaults: service = Custom, environment = Production.
| Option | Description |
|---|---|
--name <name> | Key name |
--service <service> | Service name |
--environment <env> | Environment |
--key <value> | API key / secret value to store |
--vault-key <vault-key> | Custom vault key (for custom-mode accounts) |
--notes <notes> | Optional notes |
keys get
# View key details (value is masked) apivault keys get <id> # Decrypt and show the raw value apivault keys get <id> --reveal
| Option | Description |
|---|---|
--reveal | Decrypt and print the raw secret value |
--vault-key <vault-key> | Custom vault key (custom encryption mode) |
keys update
Interactive wizard to edit a key's name, service, environment, notes, or value.
apivault keys update <id>
keys delete
Deletes a key. You will be prompted to confirm before deletion.
# Interactive deletion apivault keys delete <id> # Force delete without prompt apivault keys delete <id> -f
| Option | Description |
|---|---|
-f, --force | Skip the confirmation prompt |
Custom vault key
If you set a custom encryption key on the website (Settings → Encryption Key), operations that encrypt or decrypt need that vault key. Resolution order:
--vault-keyflagAPIVAULT_KEYenvironment variable- Config value
vaultKey - Interactive hidden prompt
# 1. Pass explicitly via flag apivault keys get <id> --reveal --vault-key "your-vault-key" # 2. Use an environment variable APIVAULT_KEY="your-vault-key" apivault keys get <id> --reveal # 3. Store locally in config (prompts securely) apivault config set vaultKey
Attempt limits
Incorrect vault keys are rate limited server-side — 10 failures per 15 minutes, counted per user and per source address. When the limit is reached the CLI reports how long to wait (for example “try again in 7m”) and exits non-zero.
A correct vault key clears the counter, so run and env export stay unaffected no matter how many secrets they decrypt in one pass. Retry loops in scripts should honour the reported delay rather than re-submitting the same key immediately.