Secrets

Named bundles of credentials, stored in the OS keychain, injected into a single child process. The engine is the standalone secrets CLI — agi-cli does not ship it.

Install

Download the published package. No extra environment variables.

# after agi-cli is installed
agents clis install secrets

# or
npm i -g @phnx-labs/[email protected]

# or, onboarding
agents setup secrets

secrets --version    # 0.1.2

agents secrets is a passthrough to the same secrets binary. Either spelling works.

The rule

Use secrets exec (or agents secrets exec) when you can and the --secrets flag on agents run when you cannot. Do not export credentials into the shell. The shell is shared with every tool you run afterwards.

Bad: export into the shell

export OPENAI_API_KEY=$(secrets get openai)
agents run codex "draft the migration"
# OPENAI_API_KEY is now visible to every subsequent process in this shell.

Good: scope to one process

secrets exec openai -- agents run codex "draft the migration"

The bundle is resolved from Keychain, the env is set on the child process only, and the child exits with the env. Nothing leaks back to the parent shell.

secrets exec stripe-prod -- bun run scripts/refund.ts
agents run claude "charge a test card" --secrets stripe-prod

Create a bundle

secrets create stripe-prod
secrets add stripe-prod STRIPE_API_KEY --type api-key --expires 2027-01-15
secrets add stripe-prod STRIPE_WEBHOOK_SECRET --type api-key
secrets list

add prompts for the value and writes it to Keychain. The EXPIRING column on list flags any secret due in the next 30 days.

Rotate a secret

secrets rotate stripe-prod STRIPE_API_KEY --note "rotated after suspected leak"

Touch ID and the broker

On macOS, Keychain access is gated by Touch ID. Unlock once; later reads in the hold window are silent:

secrets unlock stripe-prod          # one Touch ID; held ~7 days (default)
secrets status                      # what's held, and when it locks
secrets lock                        # wipe; next read re-prompts
secrets start                       # bring the broker up ahead of a busy session
secrets stop                        # lock all bundles and stop the broker

The broker is not the agents daemon. It is a macOS-only process, secrets _agent-run, started on first unlock or by secrets start. Socket and pid live under $SECRETS_HOME/.cache/helpers/secrets-agent/ (~/.agents when you go through agents secrets, ~/.secrets for the bare CLI). Linux has no broker. There is no LaunchAgent.

An agent session never raises Touch ID. Unlock in a real terminal; then agents run --secrets is silent.

Instructing an agent

Run credential-needing commands via 'secrets exec <bundle> -- <command>'.
Do not 'export' secrets into the shell. Do not write secrets to .env files.
If a bundle is missing, stop and ask which bundle to use.

Across devices

secrets export --host <alias> lands a bundle on another machine after secrets hosts pin. See secrets across devices.

See browser profiles for attaching a bundle to a browser profile.