Skip to main content
abadge run resolves a secret and injects it into a subprocess. The CLI exits with the child process exit code, so it composes naturally with shell scripts and CI pipelines. The CLI uses the provisioned local_cli runtime agent (written to ~/.abadge/config.json by abadge agent add --kind local_cli) to mint or refresh a short-lived abs_... agent session, calls POST /v1/access/{itemId}/use with delivery: env, and spawns the subprocess with the secret in its environment.

​
Single-value items

​
Multi-field items

Use --field to pick a single named field, paired with --env-var for the target variable name:
abadge run injects one secret per invocation (one --field + --env-var pair). To inject more than one field from the same item, use --expand-env.

​
Expand every field

--expand-env injects every field of a multi-field item as a separate environment variable. The field name becomes the variable name (pass names in the casing you want).
--expand-env requires the local daemon — start it with abadge daemon start if needed.

​
Bulk mode (--all)

--all fetches every item in the active profile that the runtime agent has use on, normalizes each item’s label into a POSIX env-var name (openai-api-key → OPENAI_API_KEY), and spawns the command with all of them.
Profile is the trust boundary: items in other profiles are NEVER injected, even if the agent has grants on them. --all is mutually exclusive with --item. Eligibility (structural filter). Only items with exactly one string field participate — the env-var-shaped subset that abadge import .env produces. Multi-field items (login, certificate, ssh_key) are silently skipped; use single-item mode with --field for those. Hard-fails (refuses to silently misbehave).
  • A label normalizing to a name in the reserved env-var blocklist (PATH, LD_PRELOAD, NODE_OPTIONS, HTTPS_PROXY, …) → error with the offending item’s id.
  • Two items normalizing to the same env var → error listing both ids.
  • More than 256 items match → error with meta.limit = 256. Scope further or use --item per-secret.
--all requires the local daemon and an unlocked vault for any ZK items in the profile (server-managed items don’t need an unlocked vault but still require the daemon for env injection).

​
Flags

Everything after -- is the subprocess command and arguments.

​
Behavior

1

Ensure a runtime session

The CLI mints or refreshes a fresh abs_... session for localAgents.cli. If no local runtime agent is registered, the command fails with a clear hint.
2

Resolve the item

Fetches the item from the API. Server-managed items come back decrypted; zero-knowledge items come back as ciphertext that the daemon decrypts locally.
3

Resolve the field

resolveFieldValue picks the right field based on --field or the item’s shape. Multi-field items without --field error with MULTI_FIELD_ITEM.
4

Spawn the subprocess

The CLI (or daemon, for --expand-env) spawns the command with the secret(s) in env vars. The secret lives only in the child’s process memory.
5

Wait for the child

The CLI exits with the child’s exit code so caller scripts see the right status.
6

Audit

An access.mount_env audit row is appended — allowed or denied.

​
Errors