apivault CLI

Requirements

• Node.js 18.17.0 or newer

Installation

npm install -g apivault

Or run on-demand without a global install:

npx apivault <command>

Quick start

The most common workflow is using apivault run to securely inject secrets into your local development server without ever writing them to disk:

1. Authorize your terminal

   Connect the CLI to your ApiVault account via browser approval:

   TerminalShell

   apivault login

2. Set default environment (optional)

   Optionally set your default active environment so you don't have to specify --env on every run:

   TerminalShell

   Run in shell

   apivault config set run.env Development

3. Inject secrets and start your app

   Launch your application with decrypted environment variables injected into memory:

   TerminalShell

   apivault run -- npm run dev

Global options

Available on every command:

Running apivault with no arguments prints sign-in status and exits. It distinguishes never having signed in from a token that has since expired.

Authentication

Sign-in happens in your browser, not the terminal. CLI tokens are separate from MCP OAuth tokens — revoking one does not affect the other.

login

Opens a browser to approve the CLI's connection to your account.

apivault login

The token this creates expires 90 days after approval, and login prints the expiry date once it succeeds. Once expired, commands report the date the token lapsed and apivault login issues a fresh one. Expiry dates for every connected CLI are listed under Settings → Sessions & Devices, where a token can also be revoked early.

whoami

Show the currently signed-in user and when this device's token expires. With fewer than 14 days left, the expiry line is highlighted as a reminder to re-run apivault login. In --json mode the expiry is returned as tokenExpiresAt (null for tokens issued before expiry existed), which is the field to check from a scheduled job.

apivault whoami

apivault --json whoami | jq -r ".tokenExpiresAt"

logout

Revoke this device's token and sign out.

apivault logout

The CLI manages the following local data files:

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.

keys get

# View key details (value is masked)
apivault keys get <id>

# Decrypt and show the raw value
apivault keys get <id> --reveal

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

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:

1. --vault-key flag
2. APIVAULT_KEY environment variable
3. Config value vaultKey
4. 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.

run — Inject secrets and run a command

# Run with the Production environment
apivault run --env Production -- npm start

# Run with Staging
apivault run --env Staging -- node server.js

# Run with configured defaults
apivault run

Loads all keys for an environment, decrypts them, and injects each key's name as an environment variable into the child process. Local dotenv files (.env, .env.local, etc.) are temporarily renamed to *.apivault-run-hidden while the command runs, then restored on exit. Nothing is written to disk.

Resolution precedence

apivault config set run.env Production
apivault config set run.command "npm start"

env — Export and restore dotenv files

env export

Decrypt keys for an environment and write them to a local .env file:

# Export to .env (merges with existing variables)
apivault env export --env Production

# Export to a custom file
apivault env export --env Staging -o .env.local

# Replace the file entirely instead of merging
apivault env export --env Production --force

By default, existing variables in the target file are preserved — vault keys are updated in place and new keys appended. Always add .env to .gitignore.

env restore

Restore hidden dotenv backups created by apivault run:

# Restore in the current directory
apivault env restore

# Restore in a specific directory
apivault env restore -C /path/to/project

config — Local & Global CLI defaults

The CLI supports hierarchical configuration. Settings configured locally in your project directory (.apivault.json) automatically take precedence over global user defaults (~/.apivault/config.json).

Resolution Precedence

When executing CLI commands, settings are resolved in the following priority order:

1. Command-line flags (e.g., -p, --env, --vault-key)
2. Environment variables (APIVAULT_TOKEN, APIVAULT_PROJECT, APIVAULT_KEY)
3. Local project configuration (.apivault.json in project directory)
4. Global user configuration (~/.apivault/config.json)

config list

Show all active config values, indicating whether each setting is resolved from (local) or (global). Secrets like vaultKey are masked.

# Show active merged config with sources
apivault config list

# Show only local directory config
apivault config list --local

# Show only global user config
apivault config list --global

config get

Print a specific config value (e.g. run.command, project).

# Get resolved value (local takes precedence)
apivault config get run.command

# Get explicitly from global config
apivault config get project --global

config set

Set a config value. By default, writes to local .apivault.json if a local config already exists, or to global user config. Pass --local (-l) or --global (-g) to explicitly choose the target scope.

# Set local project default environment
apivault config set --local run.env Development

# Set local project default command
apivault config set --local run.command "npm run dev"

# Set global user default environment
apivault config set --global run.env Production

# Prompt securely for vault key
apivault config set vaultKey

config delete

Remove a config value from local or global configuration.

# Remove from local project config
apivault config delete --local run.env

# Remove from global config
apivault config delete --global run.env

logs — Project Audit & Request Logs

Inspect audit activity, access events, and HTTP request logs for your project directly from the command line. You can paginate, filter by status, method, or source, and live stream incoming logs in real time.

logs list

Fetch and display recent logs in a formatted table. Filter by HTTP status code, method, origin source (CLI, MCP, Web, API), or free-text search.

# View recent logs for the active project
apivault logs

# Filter by status and source
apivault logs --status error --source mcp

# Search endpoints, methods, IPs, or actors
apivault logs --search "/api/keys" --limit 25

# Paginate through historical logs
apivault logs --page 2 --limit 50

logs tail (live streaming)

Stream logs continuously to your terminal as requests and audit events happen:

# Stream all incoming logs in real time
apivault logs tail

# Stream with specific filters
apivault logs tail --source mcp --status error

logs get / inspect

Inspect the full details of a specific log entry, including duration, IP address, user agent, caller info, and raw payload details:

# Inspect by log ID
apivault logs get <log-id>

# Output raw JSON payload
apivault --json logs get <log-id>

Scripting with --json

Pass the --json flag to any command to emit machine-readable JSON output to stdout instead of styled text. This makes it easy to integrate the CLI into automated scripts, CI/CD pipelines, and tools like jq.

When --json is enabled, standard success messages and UI formatting are disabled. Errors are also emitted to stdout as a JSON object containing an error key (e.g. {"error": "message"}) so your script can reliably parse the output. In the interactive shell, formatted JSON outputs include an instant copy button for copying payloads directly to your clipboard.

# Extract just the IDs of all keys
apivault --json keys list | jq '.[] | .id'

# Decrypt a specific key and output raw text
apivault --json keys get <id> --reveal | jq -r .rawKey

# Export an environment programmatically
apivault --json env export --env Production

Security

Troubleshooting