Managing Secrets

AgentSecrets manages your credentials using a secure hierarchy of Workspaces, Projects, and Environments (development, staging, production). Under the hood, secrets are stored in the local OS Keychain via keychain-auth and automatically synchronized to the cloud using end-to-end zero-knowledge encryption.

Core Principles

Zero Plaintext Disk Storage: Secrets are never written to project files or general configuration files on disk. They live securely inside the native OS Keychain.
Automatic Zero-Knowledge Cloud Sync: When you set a secret with agentsecrets secrets set, it is saved locally to your OS Keychain and automatically encrypted client-side and synchronized to the cloud. Teammates and your other machines receive updates seamlessly.
Scoping by Environment: Every secret is scoped to a specific project and environment. This ensures your AI agent in development cannot accidentally access staging or production credentials.
No Plaintext Retrieval (get): In accordance with the Zero-Knowledge principle, secret values are never displayed back in terminal plaintext. They are only injected into authenticated outbound proxy requests (agentsecrets call / Python SDK) or spawned process memory (agentsecrets env).

Basic CLI Operations

1Setting a Secret (Automatic Local + Cloud Sync)

When you set a secret, AgentSecrets writes it to the local OS Keychain and immediately encrypts and pushes the ciphertext blob to the cloud backend:

agentsecrets secrets set STRIPE_KEY=sk_test_51...

To set a secret across all environments simultaneously:

agentsecrets secrets set STRIPE_KEY=sk_test_51... --all-envs

Note: Modifying secrets in the production environment or using --all-envs requires local account password verification.

2Listing Secret Keys

To view all configured secret keys in the active project and environment:

agentsecrets secrets list
# Or shortcut alias:
agentsecrets list-secrets

This command lists key names and cross-environment coverage status, but never displays secret values.

3Deleting a Secret

To delete a secret from the active environment:

agentsecrets secrets delete STRIPE_KEY
# Or shortcut alias:
agentsecrets delete-secrets STRIPE_KEY

Bulk Synchronization & Migration

While individual secret changes via secrets set and secrets delete are synced automatically, bulk commands are available for initial project setup and multi-machine sync:

Bulk Pushing / Importing (secrets push): Bulk import an existing .env file or push all local keychain secrets to cloud sync.
Pulling to New Machines (secrets pull): Download and decrypt project credentials onto a new development machine or team member workstation.
Diffing Secrets (secrets diff): Compare local state against the cloud or trace drift between environments.
Importing from .env: Seamlessly migrate traditional dotenv setups to the secure keychain.