Automic Vault CLI Docs

Q: Why does Codex.app not need to be installed as root?

Codex.app is code-signed. A future Automic Vault release will check code-signing identities for critical GUI apps that are not installed as root. Reinstalling Codex as root would make the app less conventional: macOS apps do not generally expect that layout, and some can break when forced into it.

Quick start

Install a tool, inspect it, then run agents through a gate.

av is designed around three terminal surfaces. Package commands manage trusted tool installs. av save and av inject keep credentials out of readable files and process environments until an approved executable needs them. av contain runs an agent or command with a synthetic toolchain where host tool execution is mediated.

Download .dmg

Command map

The CLI is split by runtime boundary.

Package system install, info, search, list, outdated, update, uninstall Installs and reports on self-contained packages. Access control save, inject Stores secrets in the keychain and injects selected keys only when an approved executable runs. Execution control contain Runs commands inside a sandbox with approval gates for host tool execution. Local system serve, help, --version Local protocol daemon and built-in help surfaces.

Agent security guides

Turn the CLI primitives into agent security patterns.

The reference explains each command. These guides show when to use them for agent secrets, API keys, and tool-layer approval.

Secrets Secrets Manager for AI Agents Store secrets locally and inject them only when an approved tool runs. API keys API Key Management for AI Agents Keep tokens out of chat while CLIs, SDKs, and scripts still work. Approval gates AI Agent Approval Gates Put the human checkpoint beneath the agent, where commands execute. Installer trace av trace Summarize curl pipe shell installers before they write files.

Package commands

Install under controlled roots.

Release builds install packages under /opt and place command stubs in /usr/local/bin. Debug builds use /tmp/opt and /tmp/usr/local/bin, which keeps development runs separate from production installs.

package workflow

av install ripgrep
av install brew:ffmpeg npm:@anthropic-ai/claude-code pip:httpie
av info --json ripgrep
av list --jsonl
av outdated
sudo av update
sudo av uninstall ripgrep

av install or av i: Installs one or more packages. Use -f or --force to reinstall an existing package.
av search <query>: Searches available packages. Supports --json and --jsonl for machine-readable output.
av info <package>: Shows metadata, install status, update status, and security state for one package.
av list or av ls: Lists installed packages. With no package arguments it lists everything installed through Automic Vault.
av outdated: Lists installed packages with newer versions available.
av update or av up: Reinstalls packages with updates available. With no package arguments it selects all installed packages.
av uninstall or av rm: Removes one or more installed packages.

Secret injection

Store credentials once. Inject only the keys requested.

av save writes a key to the Automic Vault keychain service. av inject loads named keys and executes an absolute target path with those values in its environment after approval. Key names must start with a letter or underscore and may contain only ASCII letters, digits, and underscores. Secret values are read from stdin, or from a hidden prompt when run interactively.

keychain flow

printf '%s\n' 'example_value' | av save GITHUB_TOKEN
av inject +GITHUB_TOKEN /usr/local/bin/gh auth status
av inject --replace-existing-env +AWS_ACCESS_KEY_ID \
  +AWS_SECRET_ACCESS_KEY /usr/local/bin/aws sts get-caller-identity

Approval scope

Always-allow is intentionally narrow. The target must resolve to a root-owned executable that is not writable by group or others, and parent directories must not be group- or world-writable. Interpreter approvals are tied to a root-owned script path.

Shebang injection

Use `av inject` as the script interpreter.

Occasionally used scripts can ask Automic Vault for just the secrets they need by putting av inject in the shebang. This keeps the secret out of the repository and out of shell startup files while still making the script easy to run.

script shebang

printf '%s\n' 'app-specific-password' | av save APPLE_PASSWORD

head -n 1 scripts/build-dmg.sh
#!/usr/local/bin/av inject +APPLE_PASSWORD /usr/local/bin/bash

scripts/build-dmg.sh --notarize

Approval behavior

A project script such as ./scripts/build-dmg.sh requires approval every time because it is not root-owned. That is useful for occasional workflows like notarizing a DMG. If a script needs the same secret often, move it to a root-owned location and make the script itself root-owned so approval can be recorded for that trusted path.

Contained execution

Run an agent with a synthetic PATH and mediated host tools.

av contain launches a command through sandbox-exec, replaces PATH with generated stubs, and routes stub execution back to the local vault daemon for approval. This is the CLI surface for letting an agent attempt tool use while keeping host execution visible and interruptible.

contained execution

av contain codex
av contain toolchain --json
av contain sandbox-profile --allow /usr/local/bin/av

1 Agent command starts

av contain <command> resolves the initial executable.

2 Synthetic toolchain replaces PATH

Generated stubs call av contain --proxy for host tools.

3 Daemon approves execution

The local vault daemon streams approval and output events.

Reference

Command forms.

av help [command]

Prints the top-level help or a command topic.

av --version

Prints the CLI version from Cargo.toml.

av install [-f] <package>...

Installs packages. Alias: av i.

av info [--json|--jsonl] <package>

Shows one package.

av search [--json|--jsonl] <query>

Searches package metadata.

av list [--json|--jsonl] [package...]

Lists installed packages. Alias: av ls.

av outdated [--json|--jsonl] [package...]

Lists packages with newer versions.

av update [package...]

Reinstalls outdated packages. Alias: av up.

av uninstall <package>...

Removes packages. Alias: av rm.

av save KEY

Stores a secret read from stdin or a hidden prompt.

av inject [+KEY...] /abs/tool [args...]

Executes an absolute target with approved keys.

av contain <command> [args...]

Runs a command inside the vaulted sandbox.

av serve

Starts the local read-only protocol daemon.

Names and output

Use qualifiers when the package source matters.

Package names

ripgrep, brew:ffmpeg, cask:visual-studio-code

Agent-oriented packages

isotope:gh, isotope:aws-cli

Language registries

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

Machine output

--json prints one JSON value. --jsonl prints one JSON object per line where supported.

FAQ

Operational trust notes.

These answers cover package installs, keychain-backed injection, vaulted execution, and the trust boundaries around the Mac apps Automic Vault works with.

Why does Codex.app not need to be installed as root?

Codex.app is code-signed. A future Automic Vault release will check code-signing identities for critical GUI apps that are not installed as root. Reinstalling Codex as root would make the app less conventional: macOS apps do not generally expect that layout, and some can break when forced into it.

Why does Automic Vault.app not need to be installed as root?

Automic Vault does not need the app bundle itself to be root-owned. It needs a safe installation path. A future .pkg release will install through the macOS installer system, which verifies code signing end to end. If malware or an agent resigned Automic Vault, including with an ad hoc signature, the installation system would stop working because of the way Automic Vault verifies itself internally.

Why are isotope credentials unavailable over SSH?

The macOS login keychain may not be unlocked or trusted inside a fresh SSH session. Unlock the login keychain in that session before running commands that need injected secrets: security unlock-keychain ~/Library/Keychains/login.keychain-db. macOS will ask for your login password when it unlocks the keychain.

Should Automic Vault manage SSH passphrases?

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

Is this iCloud Keychain?

No. 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 use a secret after approval?

Yes. Automic Vault keeps agents from reading the stored secret directly, but an approved tool receives the requested values for that execution. Treat approvals as capability grants: approve the specific executable and command path you intend to trust.

Can approvals last for a terminal session?

The design allows narrow always-allow records for root-owned, non-writable executables and root-owned interpreter scripts. Session-style approval is a natural fit for tools such as aws or gh, but the scope still needs to stay tied to the executable or script that receives the injected keys.

Can this replace dotenv files for scripts?

That is the intended direction for sensitive scripts: keep secrets out of project files, approve the root-owned interpreter or script path, then inject only the keys the script needs. For agent runs, av contain can add a second execution gate around the tool invocation itself.

What about prod?

Automic Vault will support Linux at 20,000 GitHub stars. Star the project at github.com/automic-vault/automic-vault.