ak secrets

Use ak secrets for the operation described below. The command help records its arguments, effects, and options.

Choose the backend with --backend, then the AGENTKIT_SECRETS_BACKEND environment variable, then the secrets section of the user-level config.yaml in your AgentKit home, in that order. With none set, the OS keychain is used. Project config is never read for this choice. The environment variable and config.yaml accept only keychain or file; the throwaway memory backend must be requested with --backend memory on the command line.

The file backend reads its vault passphrase only from an interactive terminal. No flag or environment variable supplies it, so an unattended run against the file backend cannot open the vault, and a secret resolve that an agent hook triggers exits with status 7. Use the keychain backend for scripted runs.

Command contract

Manage named secret values (API keys, tokens)

Synopsis

Store, read, list, delete, and rotate small named secret values behind the OS keychain, an age-encrypted vault (--backend=file, for a host with no usable keychain; see ak secrets recovery), or an in-memory --backend=memory dev backend. Values are written only to the active backend; ~/.agentkit/secrets/index.json holds metadata (ref, creator, timestamps) and never a value. Use it for an API key, token, or certificate AgentKit or an adapter needs at runtime, instead of an unmanaged .env file or shell export.

Examples

  ak secrets set ${REF}                                  # interactive prompt
  echo -n "${VALUE}" | ak secrets set ${REF} --value=-  # pipe from stdin
  ak secrets get ${REF}                                  # prints [redacted]
  ak secrets list --json                                 # machine-readable metadata

Options

  -h, --help             help for secrets
      --json             Emit machine-readable JSON (implies --no-interactive)
      --no-interactive   Disable interactive prompts (CI-safe)
  -q, --quiet            Suppress non-error output on stderr
  -V, --verbose          Extra diagnostic output on stderr (loses to --quiet)
  -y, --yes              Assume yes for all prompts

SEE ALSO

• ak - AgentKit CLI
• ak secrets approve - Answer the secret requests agents left waiting
• ak secrets audit - Show the secrets access ledger and matching grants
• ak secrets delete - Delete a stored secret
• ak secrets export - Emit a versioned inventory of every stored secret
• ak secrets get - Show a secret's metadata, redacted by default
• ak secrets grant - Let a fingerprinted agent binary read a secret
• ak secrets grants - List recorded agent grants
• ak secrets import-env - Bulk-import secrets from a dotenv file
• ak secrets list - List stored secret refs and metadata
• ak secrets recovery - Manage the file backend's vault and its recovery keys
• ak secrets revoke - Remove an agent's grants on a secret, or all of them
• ak secrets rotate - Replace an existing secret's value
• ak secrets set - Store a secret value
• ak secrets trust - Show or re-pin a coding agent's trusted binary