Run, env & config

Last updated at October 31, 2026

Run a command with your secrets injected, write dotenv files for frameworks that need them, and save the defaults these commands fall back on.

run — Inject secrets and run a command

Run with secretsShell

# 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

Setting	Order (first wins)
Environment	`--env` → a service token's environment pin → config `run.env` → error
Command	args after `--` → config `run.command` → error
Vault key	`--vault-key` → `APIVAULT_KEY` → config `vaultKey` → prompt

Config defaultsShell

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:

Dotenv exportShell

# 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

Option	Description
`--env`	Environment to export (or config `run.env`)
`-o, --output`	Output file (default: `.env`)
`-f, --force`	Replace file instead of merging
`--vault-key <vault-key>`	Custom vault key

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 env filesShell

# Restore in the current directory
apivault env restore

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

Option	Description
`-C, --directory`	Project directory for restore (default: cwd)

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).

Key	Description
`project`	The target project ID or slug for this directory/repository
`run.command`	The default command to execute for `apivault run` (e.g. `"npm start"`)
`run.env`	The default environment to pull secrets from (e.g. `Production`)
`vaultKey`	The custom vault key used to decrypt secrets for custom-mode accounts

Resolution Precedence

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

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

APIVAULT_TOKEN overrides your signed-in identity

Setting APIVAULT_TOKEN makes every command authenticate as that service token, ahead of the device token in ~/.apivault/token.json — which is what makes the CLI usable in CI, where neither a browser nor a stored token exists. While it is set, login and logout refuse to run rather than writing a device token the next command would ignore, and projects list and logs refuse because a project-scoped token cannot read them. A token pinned to an environment also supplies it to run and env export, ahead of any run.env left on the machine. Run apivault whoami to see which identity is actually in use. See CI/CD & service tokens.

config list

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

List configShell

# 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 configShell

# 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 configShell

# 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.

Delete configShell

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

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

Was this page helpful?