Automic Vault Automic Vault

Automic Vault CLI

Getting started with av

The av command installs developer tools under controlled roots, stores secrets outside agent-readable files, injects selected keys only into approved processes, and runs agent commands through an approval path for host tool execution.

macOS Local-first Last updated June 8, 2026
quick path 
av install ripgrep
printf '%s\n' "$GITHUB_TOKEN" | av save GITHUB_TOKEN
unset GITHUB_TOKEN
av inject +GITHUB_TOKEN /opt/homebrew/bin/gh repo view automic-vault/automic-vault
av contain codex

Install Automic Vault

Install the macOS app first, then use av from your terminal. The app owns approval UI and local state; the CLI is the scriptable interface for packages, secrets, dotenv files, tracing, and containment.

install one-liner 
curl -fsSL https://automicvault.com/install.sh | sh && av open
av  --version
av help

The installer downloads and mounts the DMG read-only, lets Gatekeeper inspect the app, verifies the signature and Team ID, copies Automic Vault.app into /Applications, and installs /usr/local/bin/av. If you do not want to pipe a script into sh, download the latest DMG from GitHub Releases instead.

Release and debug roots

Release builds install package payloads under /opt and command stubs under /usr/local/bin. Debug builds use /tmp/opt and /tmp/usr/local/bin so development runs do not collide with production installs.

First Run

A useful first session exercises the three boundaries: install one package, remove one plaintext credential from your shell, and run an agent command through containment.

  1. 1

    Install a package

    av install creates a self-contained package root and writes stubs for its commands.

  2. 2

    Move a token into the keychain

    av save stores the trimmed value. av inject exposes it only to the approved target process.

  3. 3

    Contain an agent

    av contain launches the agent with generated stubs so host tool execution can be mediated by Automic Vault.

Package Names

Package commands accept plain names for the default catalog and qualified names when the source matters. Use qualifiers in scripts so the requested ecosystem is explicit.

Default and Homebrew

ripgrep, brew:ffmpeg, brew:awscli

Casks

cask:visual-studio-code, cask:codex

Language registries

npm:@scope/name, npm:name@1.2.3, pip:httpie

Isotopes

isotope:gh, isotope:aws-cli

Guide: Stop Exporting Secrets From Your Shell

Do not put long-lived credentials in .zshrc, .zprofile, .zshenv, .bashrc, .bash_profile, .profile, .envrc, or project .env files that agents can read. Those files are convenient, but they make every shell and every local automation process an ambient credential carrier.

Save the value once:

save one key 
printf '%s\n' "$OPENAI_API_KEY" | av save OPENAI_API_KEY
unset OPENAI_API_KEY

Then inject it only into the tool that needs it:

inject into tools 
av inject +OPENAI_API_KEY /opt/homebrew/bin/opencode run
av inject +GITHUB_TOKEN /opt/homebrew/bin/gh repo view automic-vault/automic-vault
av inject +AWS_ACCESS_KEY_ID +AWS_SECRET_ACCESS_KEY \
  /opt/homebrew/bin/aws sts get-caller-identity

+KEY names a value stored in the Automic Vault keychain. The target must be an absolute executable or script path. By default, av inject refuses to overwrite an environment variable that is already set; use --replace-existing-env when you deliberately want the keychain value to win. Wrapper scripts can use --allow-missing-keys when a tool has optional credentials.

For repeatable workflows, make the script itself use av inject as its interpreter:

script interpreter 
#!/usr/local/bin/av inject +OPENAI_API_KEY /bin/sh
set -eu
exec /opt/homebrew/bin/opencode run "$@"

or for a tool with optional credentials:

optional key 
#!/usr/local/bin/av inject --allow-missing-keys +GITHUB_TOKEN /bin/sh
set -eu
exec /opt/homebrew/bin/gh "$@"

Make the script executable and run it normally. The kernel starts av, av asks Automic Vault to approve the named key for that script and interpreter, then /bin/sh receives the key only for that execution.

The boundary

Automic Vault is trying to keep the handoff narrow:

  • The secret value lives in the macOS Keychain, not in a shell startup file, project file, prompt, transcript, or agent-readable config.
  • Approval shows the key names, target executable, arguments, current directory, parent process, and script context before injection.
  • Always-allow decisions are scoped to the executable and, for user-controlled scripts, the script path and SHA-256 so changed scripts ask again.
  • av inject disables core dumps, validates the target path and parent directories, and on macOS verifies the opened executable still matches the path immediately before execve.
  • The value is placed in the child process environment only after approval; the model does not get the raw value unless the tool itself prints or leaks it.

That is not a substitute for central enterprise secret management. It is a local runtime handoff that keeps agent-readable files clean while still letting real command-line tools authenticate when they run.

Guide: av inject as a Shebang

A script can ask for the secrets it needs by using av inject as its interpreter. This keeps values out of the repository while preserving normal script ergonomics.

script interpreter 
printf '%s\n' "$APP_STORE_CONNECT_API_KEY" | av save APP_STORE_CONNECT_API_KEY

cat > scripts/notarize.sh <<'SCRIPT'
#!/usr/local/bin/av inject +APP_STORE_CONNECT_API_KEY /bin/sh
set -eu
exec /usr/bin/xcrun notarytool submit "$@"
SCRIPT

chmod +x scripts/notarize.sh
scripts/notarize.sh "Automic Vault.dmg"

The kernel starts /usr/local/bin/av, Automic Vault parses the shebang argument as inject +KEY /interpreter, requests approval, then runs the interpreter with only those requested variables set.

optional keys 
#!/usr/local/bin/av inject --allow-missing-keys +GITHUB_TOKEN /bin/sh
set -eu
exec /opt/homebrew/bin/gh "$@"

Guide: Encrypted .env Files

av dotenv gives dotenv workflows a safer shape. The .env file can stay in the project, secret values are stored as dotenvx-compatible encrypted: entries, and the matching private key lives in the macOS Keychain. Loading or running with decrypted values requires Automic Vault approval.

Start a new encrypted dotenv file

Use this when the project has no dotenvx keypair yet. The public key is written into the file; the private key is stored locally in the Automic Vault keychain service.

new project 
av dotenv init --file .env
printf '%s\n' "$STRIPE_SECRET_KEY" | av dotenv set --file .env STRIPE_SECRET_KEY
av dotenv encrypt --file .env --check

av dotenv set reads from stdin or an interactive hidden prompt, encrypts the value with DOTENV_PUBLIC_KEY, and writes an encrypted: value back to the file. av dotenv encrypt --check fails if secret-shaped plaintext remains.

Import an existing dotenvx key file

Use this when you already have a dotenvx-style .env and .env.keys. The .env file contains a DOTENV_PUBLIC_KEY line. The keys file contains the matching DOTENV_PRIVATE_KEY value.

existing dotenvx 
grep '^DOTENV_PUBLIC_KEY' .env
grep '^DOTENV_PRIVATE_KEY' .env.keys

av dotenv import --file .env --keys-file .env.keys
av dotenv encrypt --file .env --check
av dotenv run --file .env -- /bin/sh -c 'test -n "$STRIPE_SECRET_KEY"'

For files such as .env.production, import that file explicitly:

named environment 
av dotenv import --file .env.production --keys-file .env.keys

If the public key line is DOTENV_PUBLIC_KEY_PRODUCTION, the keys file must contain DOTENV_PRIVATE_KEY_PRODUCTION. av dotenv import validates the private key and stores it in the local Keychain so future av dotenv run and av dotenv export requests do not need .env.keys.

Move the private key to another machine

The clean path is to move a deliberate private-key file through a secret manager you already trust, then import it on the next Mac. Do not commit .env.keys.

second Mac 
# On the source machine, keep .env.keys out of git and move it through
# your password manager, MDM secret store, or production secret manager.

# On the destination Mac:
av dotenv import --file .env --keys-file .env.keys
rm .env.keys
av dotenv run --file .env -- /bin/sh -c 'test -n "$STRIPE_SECRET_KEY"'

If the key only exists in Automic Vault because you created it with av dotenv init, there is no public av dotenv command that prints it back out. You can deliberately read the Keychain item and create a one-time .env.keys file:

keychain handoff 
PUBLIC_KEY=$(
  awk -F= '/^DOTENV_PUBLIC_KEY(_[A-Z0-9_]+)?=/ {
    gsub(/^[[:space:]]+|[[:space:]]+$/, "", $2)
    gsub(/^"|"$/, "", $2)
    print $2
    exit
  }' .env
)
PRIVATE_KEY_NAME=$(
  awk -F= '/^DOTENV_PUBLIC_KEY(_[A-Z0-9_]+)?=/ {
    name=$1
    sub(/^DOTENV_PUBLIC_KEY/, "DOTENV_PRIVATE_KEY", name)
    print name
    exit
  }' .env
)
ACCOUNT="DOTENV_PRIVATE_KEY:$(printf '%s' "$PUBLIC_KEY" | shasum -a 256 | awk '{print $1}')"
PRIVATE_KEY=$(security find-generic-password \
  -s com.automicvault.dotenv \
  -a "$ACCOUNT" \
  -w)

umask 077
printf '%s=%s\n' "$PRIVATE_KEY_NAME" "$PRIVATE_KEY" > .env.keys

That command may ask Keychain for permission. Treat the resulting file as live secret material: move it through the intended secure channel, import it on the destination Mac, then remove the file.

Store the private key in AWS Secrets Manager

Store the private-key file content as a Secrets Manager secret when production, CI, or another Mac needs to retrieve it later. Prefer a file argument so the key is not placed directly in shell history.

create secret 
aws secretsmanager create-secret \
  --name automic-vault/dotenv/my-app \
  --secret-string file://.env.keys
rotate secret value 
aws secretsmanager put-secret-value \
  --secret-id automic-vault/dotenv/my-app \
  --secret-string file://.env.keys

To hydrate a new Mac from Secrets Manager, retrieve the stored string, import it, and delete the local file:

retrieve and import 
umask 077
aws secretsmanager get-secret-value \
  --secret-id automic-vault/dotenv/my-app \
  --query SecretString \
  --output text > .env.keys

av dotenv import --file .env --keys-file .env.keys
rm .env.keys
Commit the public key, protect the private key

The DOTENV_PUBLIC_KEY line is not a secret. The matching private key is stored in the Automic Vault keychain service under com.automicvault.dotenv. Production systems that do not run Automic Vault should receive the matching private key through their own secret manager and expose it only to the dotenvx-compatible loader that needs to decrypt the file.

Load values while working

Use the shell hook when you want encrypted values loaded as you enter a project. Use av dotenv run when one command should receive decrypted values and the rest of the shell should stay clean.

runtime use 
# Load encrypted keys when you cd into a project.
eval "$(av dotenv hook zsh)"

# Or run one command with decrypted values.
av dotenv run --file .env -- npm test

Guide: Contained Agents

Use containment when an agent should be allowed to attempt work but should not get invisible, ambient access to every host command. Automic Vault launches the command through sandbox-exec, creates a synthetic PATH, and routes tool execution back to the local approval path.

agent boundary 
av contain codex
av contain claude
av contain /opt/homebrew/bin/opencode run
  1. 1

    Initial command starts

    av contain <command> resolves the executable and creates launch state.

  2. 2

    Synthetic toolchain replaces PATH

    Generated stubs call av contain --proxy when the agent invokes host tools.

  3. 3

    Automic Vault mediates execution

    The local daemon receives tool execution requests and presents approval decisions.

Guide: Tracing Installers

av trace is for suspiciously small installer commands, especially curl-to-shell one-liners in READMEs or issue comments. It asks a local Codex or Claude command to summarize likely file-changing behavior before you run the installer.

preflight installer 
av trace 'curl -fsSL https://example.test/install.sh | sh'
av trace --agent codex 'curl https://example.test/install.sh | bash'
av trace --json 'curl https://example.test/install.sh | sh'

Reference

Package Commands

Package commands install and inspect self-contained tool roots. Use --json or --jsonl where listed when another program needs structured output.

av install alias av i

Installs one or more packages under the controlled package root. Use -f or --force to reinstall an existing package.

Usage: av install [-f | --force] <package|brew:formula|cask:cask|isotope:name|npm:package|pip:package>...
  • Requires a package name; accepts multiple packages in one invocation.
  • Release builds may require root for package mutation.
  • Use qualified names when installing from npm, pip, cask, or isotope sources.

av info

Shows package metadata, install status, update status, and package security state for one package.

Usage: av info <package|brew:formula|cask:cask|isotope:name|npm:package|pip:package>
  • Supports --json and --jsonl.
  • Accepts exactly one package.

av list alias av ls

Lists installed packages with their installed versions.

Usage: av list [package|brew:formula|cask:cask|isotope:name|npm:package|pip:package]...
  • With no arguments, lists everything installed by Automic Vault.
  • With package arguments, limits output to those installed package records.
  • Supports --json and --jsonl.

av outdated

Lists installed packages with newer versions available.

Usage: av outdated [package|brew:formula|cask:cask|isotope:name|npm:package|pip:package]...
  • With no arguments, checks all installed packages.
  • Supports --json and --jsonl.
  • Human output prints installed -> latest version pairs.

av update alias av up

Reinstalls packages with updates available. With no package arguments, it selects all installed packages.

Usage: av update [package|brew:formula|cask:cask|isotope:name|npm:package|pip:package]...
  • Requires root for package mutation in release builds.
  • Accepts optional package names to limit the update set.
  • Accepts the internal --no-self-update flag used by updater flows.

av uninstall alias av rm

Removes installed packages from the controlled package root.

Usage: av uninstall <package|brew:formula|cask:cask|isotope:name|npm:package|pip:package>...
  • Requires at least one package.
  • Checks that requested packages are installed before removal.
  • May require root in release builds.

Reference

Access Control Commands

av scan alias av secret-scanner

Scans isotope detectors and likely local secret files for plaintext credentials visible to agents.

Usage: av scan [--path <path>] [--skip <path>]... [--isotopes-only] [--json | --jsonl]
  • --path chooses the scan root; a positional path is also accepted.
  • --skip excludes one path and can be repeated.
  • --isotopes-only skips file probes and only runs isotope-oriented checks.
  • --json prints one report; --jsonl streams findings and errors.

av save

Stores a trimmed secret in the Automic Vault keychain service.

Usage: av save KEY
  • Reads the value from stdin, or prompts without echo in an interactive terminal.
  • Rejects empty trimmed keys or values.
  • Use with av inject +KEY /absolute/tool to expose the value only after approval.

av inject

Asks Automic Vault to approve injecting named keychain values into one target process.

Usage: av inject [--replace-existing-env] [--allow-missing-keys] +KEY [+KEY...] /absolute/path/to/executable-or-script [args...]
  • +KEY names a saved keychain item. Names must be shell-safe environment variable names.
  • The target must be an absolute executable or script path.
  • By default, existing environment variables are not overwritten; use --replace-existing-env when the keychain value should win.
  • --allow-missing-keys lets wrappers continue when optional keys have not been saved.

av credential-helper

Runs an approved credential helper protocol adapter for package-specific integrations.

Usage: av credential-helper <protocol>
  • Currently exposes the protocols compiled into isotope integrations, including aws when available.
  • Intended for trusted helper flows rather than direct shell use.
  • Unknown protocols fail before any credential lookup.

Reference

Dotenv Commands

av dotenv loads encrypted dotenvx-compatible .env files with Automic Vault approval. The command family manages the file, the keychain-backed private key, shell hooks, and one-shot command execution.

av dotenv

Dispatches to dotenv file and runtime subcommands.

Usage: av dotenv <init|set|encrypt|import|hook|export|run> [options]

av dotenv init

Creates or updates a dotenv file with a public key and stores the matching private key in the Automic Vault keychain.

Usage: av dotenv init [--file .env]
  • Defaults to .env.
  • Fails if the file already has a DOTENV_PUBLIC_KEY.

av dotenv set

Encrypts one value and writes it into the dotenv file.

Usage: av dotenv set [--file .env] KEY
  • Reads the secret from stdin or an interactive hidden prompt.
  • Creates a public/private keypair if needed.
  • Writes the value as an encrypted: dotenv entry.

av dotenv encrypt

Encrypts secret-shaped plaintext values already present in a dotenv file.

Usage: av dotenv encrypt [--file .env] [--key KEY...] [--exclude-key KEY...] [--check]
  • --key limits encryption to named keys and can collect multiple key names.
  • --exclude-key leaves named keys untouched.
  • --check exits with an error when secret-shaped plaintext remains.
  • Already encrypted values and public browser config keys are left alone.

av dotenv import

Imports the private key for an existing dotenvx-compatible file into the Automic Vault keychain.

Usage: av dotenv import [--file .env] [--keys-file .env.keys]
  • Reads the public key from the dotenv file.
  • Reads the matching private key from the keys file.
  • Stores the private key locally so future loads do not need .env.keys.

av dotenv hook

Prints shell hook code that loads or unloads encrypted dotenv values as the current directory changes.

Usage: av dotenv hook zsh|bash|fish
  • Use eval "$(av dotenv hook zsh)" for zsh.
  • The hook delegates to av dotenv export.
  • Unsupported shells fail explicitly.

av dotenv export

Prints shell commands to load the nearest approved encrypted dotenv file for a shell.

Usage: av dotenv export --shell zsh|bash|fish [--cwd <path>]
  • Searches from --cwd, or from the current directory when omitted.
  • Prints unload commands when leaving a project or when no dotenv file is found.
  • Tracks loaded file path, digest, and keys through AV_DOTENV_* environment variables.

av dotenv run

Runs one command with decrypted dotenv values in its environment after approval.

Usage: av dotenv run [--file .env] [--] <command> [args...]
  • Disables core dumps before loading secrets.
  • Does not overwrite environment variables that are already set.
  • Streams child output and redacts loaded secret values if the child prints them.

Reference

Execution Control Commands

av contain

Runs a command inside a vaulted sandbox with a synthetic PATH. Generated stubs request approved host execution through Automic Vault.

Usage: av contain <command> [args...]
       av contain --proxy <stub-path> [args...]
       av contain internal-exec <tool> [args...]
       av contain toolchain [--socket <path>] [--vault-bin <path>] [--json]
       av contain sandbox-profile [--allow <path>]
  • av contain <command> is the normal user-facing form.
  • toolchain prints a generated interception toolchain root, or a JSON manifest with --json.
  • sandbox-profile prints a sandbox-exec profile that only permits execution of the allowed vault binary.
  • --proxy and internal-exec are internal containment paths for generated stubs and trusted callers.

av trace

Asks a local Codex or Claude command to statically trace likely file-changing steps in a shell one-liner.

Usage: av trace [--agent codex|claude] [--json] <shell-one-liner>
  • Auto mode prefers codex on PATH and falls back to claude.
  • Recognizes simple curl-to-shell commands and downloads the script for inspection.
  • --json returns command, agent, safety rating, and traced steps.
  • --jsonl is intentionally not supported.

av gate

Creates a manual approval checkpoint and blocks until Automic Vault records a decision.

Usage: av gate <message>
  • Requires one non-empty message.
  • Useful in scripts when a human checkpoint should exist outside the agent prompt.
  • Approval support is macOS-only.

Reference

Local System Commands

av open

Opens Automic Vault.app.

Usage: av open
  • Looks for the app bundle in conventional macOS application locations.
  • Useful after installing the DMG or when approval UI is not already running.

av serve

Starts the local Nucleus protocol daemon used by Automic Vault integrations.

Usage: av serve
  • Primarily a local system integration entrypoint.
  • Supports --help and --version.

av help and av --version

Prints CLI help, command-specific help, and the compiled package version.

Usage: av help [command]
       av <command> --help
       av --version
  • av help prints the grouped command map.
  • av help inject, av help dotenv, and other command topics print usage for that surface.
  • Subcommands also accept --version.

Operational Notes

Protected tool credentials over SSH

The macOS login keychain may not be unlocked or trusted inside a fresh SSH session. Unlock it before commands that need injected secrets: security unlock-keychain ~/Library/Keychains/login.keychain-db.

SSH passphrases

Use the macOS keychain support SSH already provides. Automic Vault focuses on package tools, approved environment injection, dotenv files, and command execution gates rather than replacing SSH's passphrase integration.

iCloud Keychain

Automic Vault uses local keychain-backed storage for CLI secrets. Syncing agent-facing credentials through iCloud would be convenient in some cases, but it expands where those credentials can appear.

Can a tool still leak a secret after approval?

Yes. Automic Vault keeps the stored secret out of prompts, transcripts, and ambient files, but an approved tool receives the requested values for that execution. Treat approvals as capability grants to a specific executable and command path.

Production and Linux support

Automic Vault is macOS-focused today. Linux support is planned at 20,000 GitHub stars.