Reference · envault 0.5

The envault command

It ships inside EnVault.app and reads the same vault as the app. While EnVault is running, it gets the key from the app after you approve with Touch ID, so you never type the passphrase into a shell.

Install

In EnVault, open Settings › Command Line › Install envault Command and pick a folder on your PATH (Homebrew’s bin works). It adds a link into the app, so app updates update the command. Or in Terminal:

$ sudo ln -sf /Applications/EnVault.app/Contents/Helpers/envault /usr/local/bin/envault $ envault status

Unlocking

A command that needs the key tries, in order:

  1. the key cached by envault unlock
  2. $ENVAULT_PASSPHRASE, if set
  3. the running EnVault app: it shows a Touch ID prompt and hands over the key for that one command (it starts the app in the background if needed)
  4. a passphrase prompt
envault statusIs the app running, which vault is open, locked or not.
envault unlock [--passphrase]Cache the key in your login keychain, for shell hooks. Uses Touch ID through the app unless you pass --passphrase.
envault lockForget the cached key.

Everyday

envault lsList projects and their items.
envault get <project> <item>Print an item’s contents.
envault run <project> <item> -- CMDRun a command with the file’s variables set. Nothing is written to disk. --redact replaces secret values in its output with [redacted:KEY].
envault keys <project> <item>List the variable names in an env file, without values.
envault pull <project> <item> [-o PATH]Write the env file to disk, readable only by you.
envault push <project> <item> <FILE>Create or update an item from a file; creates the project if needed.
envault set <project> <item> KEY=VALUESet variables, creating the file if needed. KEY=- reads the value from stdin; --generate KEY stores a new random secret without printing it.
envault unset <project> <item> KEYRemove variables. Every change is a new revision.
envault history <project> <item>List revisions, with the Mac that made each.
envault example <project> <item>Print a .env.example: same keys and comments, secrets blanked.

AI agents

Claude Code, Cursor, Codex and other coding agents can use your secrets without reading them. Connect EnVault as an MCP server, or let the agent use the envault command directly. Either way it can run tests, migrations and scripts with an env file loaded, see variable names, and add or rotate keys. Secret values in command output are replaced with [redacted:KEY].

# Claude Code · Codex $ claude mcp add envault -- envault mcp $ codex mcp add envault -- envault mcp # Cursor and others: an MCP server with command "envault", args ["mcp"] # agents that only use the shell: add the guide to AGENTS.md or CLAUDE.md $ envault agent-guide >> AGENTS.md $ envault agent-guide --skill > ~/.claude/skills/envault/SKILL.md

The command knows it is talking to an agent from the environment the agent sets (CLAUDECODE, CURSOR_AGENT, GEMINI_CLI, CODEX_SANDBOX, or ENVAULT_AGENT=name for others). Then:

  • it never asks for the passphrase; it exits with code 4 when the user has to unlock or approve something
  • envault run redacts output unless the agent passes --no-redact
  • reading values (get, pull, env, run --no-redact, deploy) asks you with Touch ID, naming the agent and the file
  • it goes through the app, so Settings › AI Agents applies: whether agents may see values (ask, never, allow), change env files, and how long one approval lasts. The same tab lists recent requests.
envault mcpServe EnVault over MCP (stdio). Tools: status, list_items, list_keys, run_command, set_keys, unset_keys, get_values (asks you), scan.
envault agent-guide [--skill]Print instructions for agents, as Markdown or as a Claude Code skill.
--jsonMachine-readable output for ls, keys, status, history, links, scan and changes. Errors become {"error", "code"} on stderr.

These rules keep a well-meaning agent from pasting a key into a chat, a log or a commit. They are not a sandbox: an agent with a shell can do whatever your account can.

Shell integration Pro

Link a folder to an env file; the hook exports its variables when you cd in and unsets them when you leave. Run envault unlock once so the hook never has to ask.

# ~/.zshrc (bash: ~/.bashrc · fish: envault hook fish | source) eval "$(envault hook zsh)" $ cd ~/code/shop && envault link shop .env.local
envault link <project> <item> [DIR]Bind a folder (default: the current one) to an env file.
envault unlink [DIR] · envault linksRemove a binding, or list them.
envault env [--fish]Print export lines for the file linked to this folder.

Import

Bring secrets in from wherever they live now. An item with the same name is updated, not duplicated.

envault import <project> <item> <FILE|->A .env file, JSON (flat, Doppler or a 1Password item) or a .env.vault, decrypted with $DOTENV_KEY. - reads stdin.
… --doppler [-- doppler args]From doppler secrets download, e.g. -- --project shop --config prd.
… --1password <item> [-- op args]From op item get; each field becomes a variable.

GitHub Actions secrets can’t be imported: GitHub never returns their values.

Keeping secrets out of git

The pre-commit hook scans what you are about to commit for AWS, GitHub, Stripe, Slack, OpenAI and Google keys, private key blocks, JWTs, secret-looking assignments and real .env files. Add envault:allow to a line that is a false positive; git commit --no-verify skips the check once.

envault protect [DIR] [--remove]Install or remove the hook. Keeps any hook you already have and honours core.hooksPath.
envault scan --stagedWhat the hook runs: scan the staged files.
envault scan [DIR]Scan a whole source tree, skipping node_modules, build folders and binaries.

Deploy

Uses the vendors’ own CLIs and the logins you already have. --dry-run prints what would run.

envault deploy vercel <project> <item>--target production|preview|development
envault deploy cloudflare <project> <item>Worker secrets via wrangler secret bulk; pass wrangler options after --.
envault deploy github <project> <item>Actions secrets via gh secret set; --repo owner/name.

Options and variables

--vault DIR · $ENVAULT_DIRWhich vault. Default: the one open in the app, else the EnVault folder in iCloud Drive.
$ENVAULT_PASSPHRASEPassphrase for scripts and CI.
ENVAULT_NO_APP=1Never ask the EnVault app; use the cache or the passphrase.
ENVAULT_AGENT=name · =0Treat the caller as an AI agent with that name, or (0) as a person.
Exit codes1 error · 2 scan found secrets · 3 not found · 4 needs you (locked, approval) · 5 refused · 64 usage
$DOTENV_KEYDecrypts a .env.vault on import.