Secrets Management

AgentSecrets securely stores, syncs, and scopes secrets in the local OS Keychain via keychain-auth.

The No Plaintext Retrieval (get) Principle: In accordance with the Zero-Knowledge architecture, AgentSecrets does not provide a get command or API method to read secrets back in terminal plaintext. Secret values are only injected into authenticated outbound proxy requests (agentsecrets call / Python SDK) or spawned process memory (agentsecrets env).

---

Command Reference

agentsecrets secrets set

agentsecrets secrets set KEY=value
# Shortcut alias:
agentsecrets set-secrets KEY=value

Stores a secret in the OS Keychain for the active project and environment. The value is passed directly to the keychain-auth daemon and encrypted — never written to disk or sent across networks in plaintext.

agentsecrets secrets set KEY=value --all-envs

Sets the same value in all three environments (development, staging, production) simultaneously. Prompts for confirmation before proceeding.

---

agentsecrets secrets list

agentsecrets secrets list
# Shortcut alias:
agentsecrets list-secrets

Lists all secret key names for the current project and environment. Displays cross-environment coverage so you can see which keys are missing in which environments. Never displays plaintext values.

---

agentsecrets secrets delete

agentsecrets secrets delete KEY
# Shortcut alias:
agentsecrets delete-secrets KEY

Removes a secret from the active environment in the OS Keychain. Before prompting for authentication, the CLI verifies that the secret entity actually exists, returning structured error SEC-404 if not found.

---

agentsecrets secrets push

agentsecrets secrets push
# Shortcut alias:
agentsecrets push-secrets

Uploads encrypted secret blobs to cloud sync. All encryption is performed client-side using project keys before upload.

• Storage mode 1 (Default): Reads from the OS Keychain and pushes encrypted blobs to cloud.
• Storage mode 2 (.env mode): Reads from .env.{environment} and pushes encrypted blobs to cloud.

---

agentsecrets secrets pull

agentsecrets secrets pull
# Shortcut alias:
agentsecrets pull-secrets

Downloads encrypted secrets from cloud sync and decrypts them directly into the local OS Keychain.

• Generates .env.example containing key names and environment annotations with zero secret values.

---

agentsecrets secrets diff

agentsecrets secrets diff
# Shortcut alias:
agentsecrets diff-secrets

Compares local Keychain state against cloud sync for the active environment.

agentsecrets secrets diff --from <env> --to <env>

Shows which keys exist in one environment but are missing in another. Compares key name coverage only — never values.

---

Secret Policies (agentsecrets secrets policy)

Configure and inspect domain and HTTP method restriction policies for individual secret keys.

agentsecrets secrets policy set

# Domain and method constraints:
agentsecrets secrets policy set STRIPE_KEY --domains api.stripe.com,api.github.com --methods GET,POST
# Method action constraints:
agentsecrets secrets policy set STRIPE_KEY --methods GET --action request_permission
# Granular domain:METHOD=ACTION rules:
agentsecrets secrets policy set STRIPE_KEY --rule api.stripe.com:GET=allow,POST=request_permission --rule api.github.com:GET=allow

Configures domain and method constraints on a secret key.

• --domains: A comma-separated list of allowed domains.
• --methods: A comma-separated list of allowed HTTP methods and actions (e.g. POST=request_permission). Any unlisted methods default to allow unless explicitly constrained.
• --action: The outcome if global method constraint matches. Values: allow, deny, request_permission. Default is allow.
• --rule: A repeatable flag specifying domain-specific constraints in the format domain:METHOD=ACTION (e.g. --rule api.stripe.com:POST=request_permission). Rules take precedence over global flags.

agentsecrets secrets policy get

agentsecrets secrets policy get KEY

Retrieves and displays the policy rules configured for the given secret key.

agentsecrets secrets policy delete

agentsecrets secrets policy delete KEY

Clears and deletes all policy rules configured for the given secret key.

agentsecrets secrets policy list

agentsecrets secrets policy list

Lists all secret-level policies configured in the current project and active environment.