Automic Vault

Automic Vault 4.18.0 · macOS

Command reference

The supported CLI surface, machine-readable catalogs, and exit behavior.

Command reference

av scan [--show-all|--json]
av doctor [<tool>] [--json]
av detectors --json
av hardeners --json
av bless [--endorse-launcher] <path>
av inject +KEY... [--] <command>
av inject -- <command>
av inject --mode=fd +KEY:FD... -- <command>
av proxy +KEY... [--] <command>
av list
av history [--json] [--since <duration>]
av git <clone|fetch|pull|push> <URL> [DIRECTORY]
av save [--multiline | --stdin] [--project-directory=DIR] KEY
av harden <tool> [-y|--yes]
av unharden brew [-y|--yes]
av gpg-sign [GPG options]
av open [--secret-gate <id>]
av help
av --version

Old v1 commands install, contain, dotenv, credential-helper, gate, and trace are not part of the current CLI.

av scan

av scan
av scan --show-all
av scan --json
av scan --json --detector aws-cli-credentials-file

The human report omits medium and low severity unless --show-all is set. JSON contains findings and gui_path. A completed scan exits 0 even with Findings; consume the report, not status, as the audit result. Repeat --detector NAME with JSON to limit automation.

av doctor

av doctor
av doctor gh
av doctor gh --json
av doctor codex

Without a selector it checks applicable hardeners. A selector can be a hardener, one of its commands, or a supported signed agent CLI. JSON contains results. Exit 0 means healthy, 1 means attention needed, and 2 means invalid or unknown selection.

Machine-readable catalogs

av detectors --json |
  jq '.detectors[] | {name, docs_url, documentation}'

av hardeners --json |
  jq '.hardeners[] | {
    name, applicable, hardened, commands, stub_path, target_path, secret_gate
  }'

These are authoritative for the installed build. The documentation field contains the source-checked behavior and security model. Generated environment wrappers warn that the Target can read injected credentials; dedicated/native routes may provide narrower boundaries.

See the hardener reference for the rendered documentation.

av save and av list

av save [--multiline | --stdin] [--project-directory DIR] KEY
av save [--multiline | --stdin] [--project-directory=DIR] KEY
av list
av ls

list shows names, never Values, and accepts no arguments. save defaults to a hidden single line; select --multiline for hidden multiline entry or --stdin for exact redirected input. Both modes require import Approval:

av save --multiline DEPLOY_PRIVATE_KEY
av save --stdin --project-directory=. API_TOKEN <&3

The second example assumes a trusted producer has supplied readable FD 3. Input is nonempty UTF-8 without NUL bytes, at most 1 MiB. See saving safely for EOF and replacement behavior.

av history

The menu bar app must be running; use av open before reading history.

av history
av history --since 7d --json

The default table shows the newest 50 Authorization Records. --since accepts a positive whole number followed by s, m, h, d, or w, up to 30 days; --json emits machine-readable records with display-safe commands. The Mac filters the window before disclosure. A reply over 1 MiB fails instead of dropping records, so request a narrower window. The successful read appears in its own result.

Each invocation requires Approval unless the exact Verified Launcher has Authorization History Access in Settings. This grant is independent of av list's Secret Name Access. An unverifiable Launcher needs Approval. History contains request metadata and Secret Names, never Secret Values; it is not a tamper-proof audit trail.

av git

av git clone https://github.com/OWNER/REPO.git DIRECTORY
av git fetch https://github.com/OWNER/REPO.git
av git pull https://github.com/OWNER/REPO.git
av git push https://github.com/OWNER/REPO.git

This constrained transport accepts exact GitHub HTTPS URLs ending in .git and operates on main. Only clone takes a destination argument; extra options and refspecs are rejected. It requires the protected Git runtime and hardened GitHub credential route. Its credential-bearing network phase uses protected configuration and the existing gh Secret Gate, separately from local repository work. Registration alone grants no credential authority.

The architecture marks this transport as under validation. It is not a general replacement for Git. See the Git transport design and workflow validation for the separate native remote-helper path and its supported surface.

av inject

av inject [--replace-existing-env] [--allow-missing-keys] \
  +KEY [+KEY...] [--] COMMAND [args...]
av inject -- COMMAND [args...]
av inject --mode=fd +KEY:FD [+KEY:FD...] -- COMMAND [args...]

Bare commands resolve through PATH; a Target containing / must be absolute. In the default environment mode (--mode=env), existing environment values win with a warning unless --replace-existing-env is used. Missing requested Secrets fail unless --allow-missing-keys leaves them unset. Duplicate/invalid names and root are rejected. On success, exec replaces av with the Target. Legacy --allow-existing-env, --force, --import, and --migrate are rejected.

File descriptor delivery

Available since 4.6.0:

av inject --mode=fd +FOO:3 +BAR:4 -- /path/to/consumer

The consumer must read the indicated descriptors. Each Secret arrives through its own read-only anonymous pipe as exact stored UTF-8 bytes, then EOF. There is no bundle format, trimming, or added newline. Consumed bytes are not replayed. Automic Vault removes the requested Secret Names from the Target's environment, including existing values, and preserves stdin/stdout/stderr and unrelated environment entries.

Every invocation requires fresh human Approval. Direct Access Rules, Blessings, Tool-specific policies, and Temporary Access Grants do not authorize FD delivery. Approval shows the mappings and selected Value sources; Authorization History records them before release. Update the app and CLI together: older apps reject this operation.

Descriptors must be distinct, unused decimal integers of 3 or higher, without leading zeros. Every Secret requires a mapping. Duplicate names, missing Secrets, --allow-missing-keys, --replace-existing-env, and FD shebangs are rejected. If a Value exceeds available pipe capacity, the command fails before starting the Target; this ceiling can be smaller than the 1 MiB save limit.

The Target can copy the bytes or pass descriptors to its children. FD delivery does not provide encrypted backup/recovery or restore whitespace lost during an earlier import. See the repository guide.

Shebang and Blessing workflow

#!/usr/local/bin/av inject +GH_TOKEN /bin/sh
# --- automic-vault
# capabilities:
#   gh: write
# ---
set -eu
gh release create "$1"

A blessable script is a regular UTF-8 file up to 1 MiB with absolute av and interpreter paths. The optional manifest immediately follows the shebang. Capabilities are ceilings, not grants. Execution normally uses a verified /dev/fd/N snapshot; a separately reviewed canonical-path exception is described in the Blessed Scripts guide. AV_SCRIPT_PATH and AV_SCRIPT_DIR identify the canonical source.

FD mode in an av inject shebang is currently unsupported. A Blessed Script can invoke av inject --mode=fd as a command, but each invocation still needs fresh human Approval.

av proxy

av proxy [--replace-existing-env] +KEY [+KEY...] [--] COMMAND [args...]

Every session needs Approval. The Target receives random session Secret References and a Proxy Credential, not raw Values. Automic Vault replaces common uppercase/lowercase proxy variables, empties NO_PROXY, and sets standard CA variables. Conflicts fail unless --replace-existing-env is used.

Destination rules are memory-only and scoped per session and origin. A Target can bypass configured proxies; bearer credentials remain bearer credentials at the destination. Proxying is narrower delivery, not containment. Root is denied.

av bless

av bless ./release.sh
av bless --endorse-launcher ./release.sh

Approval binds the complete reviewed script. An endorsement allows only that Verified Launcher to use the Blessing's automic authority. Without an endorsement, the Blessing itself grants that Launcher no automic authority; any applicable inherited authority still follows the script's declaration. --endorse-caller is a compatibility alias. The UI inspects, narrows, replaces, and revokes Blessings.

av harden and av unharden brew

av harden gh
av harden aws --yes
av unharden brew --yes

A hardener may move a credential, install or replace a launcher, protect ownership, install a signed Tool, or enable a native route. Read its embedded documentation; some operations require sudo, but do not run all hardeners as root. -y/--yes skips supported confirmations. Aliases include homebrew, gh-cli, stripe-cli, supabase-cli, and fly. unharden is Homebrew-only.

av gpg-sign and av open

av gpg-sign is Git plumbing, not an interactive interface. It accepts forwarded GnuPG options, reads at most 16 MiB, binds to payload SHA-256, and returns a detached signature and GnuPG status. Configure it in Settings.

av open
av open --secret-gate gh

Gate IDs use only ASCII letters, digits, hyphens, underscores, and periods.

Global behavior and exit status

av help
av --version
av inject --help
av proxy --help

Not every subcommand has dedicated --help. Color is disabled by NO_COLOR or TERM=dumb. Exit 0 is completion/approved execution; 1 operational failure, denial, or unhealthy Doctor; 2 top-level usage or invalid Doctor selection.

Read this page as Markdown