Terminal-based credential wizard for agent-driven development. The missing OAuth for LLM agents.
npm install @cyclecore/secretsage`` | / _
___ _ ___
/ __| ___ __ _ _ ___ | |_ / __| __ _ __ _ ___
\__ \ / -_)/ _|| '_|/ -_)| _|\__ \ / _ | / -_)`
|___/ \___|\___|_| \___| \__||___/ \__,_| \__, | \___|
|___/
The missing OAuth for LLM agents.
Terminal-based credential wizard for agent-driven development. Store credentials securely with age encryption, grant them to agents on demand, revoke when done.
`bash`
npm install -g @cyclecore/secretsage
Or use directly with npx:
`bash`
npx @cyclecore/secretsage
`bashInitialize vault (one-time setup)
secretsage init
Why SecretSage?
Agents need credentials. But you don't want to:
- Paste keys into agent prompts
- Hardcode them in
.env files committed to git
- Teach agents how to use your password managerSecretSage provides a simple flow:
1. Store credentials once in an encrypted vault
2. Grant them to
.env when an agent needs them
3. Revoke them when the agent is doneThink of it as OAuth for LLM agents.
Commands
$3
Initialize the vault and generate encryption keypair.
`bash
secretsage init # Interactive, prompts for location
secretsage init --local # Create vault in current directory
secretsage init --path ~/my-vault # Create vault at custom path
secretsage init --yes # Skip prompts, use defaults
`$3
Add a credential to the encrypted vault.
`bash
secretsage add OPENAI_API_KEY # Prompts for value
secretsage add API_KEY --value "sk-..." # Provide value directly
secretsage add DATABASE_URL --from-env # Import from existing .env
echo "secret" | secretsage add KEY --value - # Read from stdin
`$3
List credential names in the vault.
`bash
secretsage list # Human-readable output
secretsage list --json # Machine-readable for agents
secretsage list --all # Include metadata
`$3
Decrypt and write credentials to
.env.`bash
secretsage grant # Interactive selection
secretsage grant OPENAI_API_KEY # Specific credential
secretsage grant --all # All credentials
secretsage grant API_KEY --yes # Non-interactive (for agents)
`$3
Remove credentials from
.env (vault remains intact).`bash
secretsage revoke # Interactive selection
secretsage revoke OPENAI_API_KEY # Specific credential
secretsage revoke --all # All credentials
`$3
View or update configuration.
`bash
secretsage config # Show current config
secretsage config --path # Show config file path
secretsage config --set agent.autoGitignore=false
`$3
Permanently delete a credential from the vault.
`bash
secretsage remove OLD_API_KEY # Interactive confirmation
secretsage remove OLD_API_KEY --yes # Skip confirmation
`$3
Update the value of an existing credential.
`bash
secretsage rotate OPENAI_API_KEY # Prompts for new value
secretsage rotate API_KEY --value "new-sk-..." # Provide new value directly
echo "new-secret" | secretsage rotate KEY --value - # Read from stdin
secretsage rotate OAUTH_KEY --generate 32 # Generate random 32-byte key
secretsage rotate KEY --reason "quarterly rotation" # Add reason to audit trail
`$3
Show rotation history and audit trail for a credential.
`bash
secretsage audit STRIPE_SECRET_KEY # Human-readable history
secretsage audit STRIPE_SECRET_KEY --json # Machine-readable for agents
`$3
Open interactive key entry wizard in new terminal (agent-human handoff).
`bash
secretsage wizard --keys STRIPE_SECRET_KEY,STRIPE_WEBHOOK_SECRET --reason "key rotation"
secretsage wizard -k API_KEY,SECRET_KEY -r "quarterly rotation" --timeout 600
`The wizard:
1. Opens a new terminal window
2. Prompts for each key with validation
3. Encrypts and stores keys in vault
4. Signals completion to calling agent
$3
Deploy secrets to a remote server via rsync/SSH.
`bash
secretsage deploy myapp --remote root@host:/var/www/app/
secretsage deploy mcpbodega --remote user@host:/path --restart "pm2 restart app"
secretsage deploy app --remote host:/path -f .env.production --yes
`$3
Securely store and manage 2FA backup/recovery codes.
`bash
Add backup codes for a service (interactive)
secretsage backup-codes add github
secretsage backup-codes add google --account work@company.comList services with stored codes
secretsage backup-codes listShow codes when you need them
secretsage backup-codes show githubMark a code as used (tracks remaining codes)
secretsage backup-codes use github
secretsage backup-codes use github --index 3
`The command tracks which codes you've used and warns when running low.
$3
Export vault credentials for backup or transfer.
`bash
secretsage export # Decrypted JSON to stdout
secretsage export --encrypted # Encrypted backup
secretsage export --format env # Export as .env format
secretsage export -o backup.json # Write to file
`$3
Import credentials from backup or external source.
`bash
secretsage import -i backup.json # Import from JSON file
secretsage import --format env -i .env # Import from .env file
cat backup.json | secretsage import # Import from stdin
secretsage import --merge -i new.json # Merge with existing vault
`$3
Show vault status and health check.
`bash
secretsage status # Human-readable status
secretsage status --json # Machine-readable for agents
`Agent Integration
$3
Agents can request credentials programmatically:
`bash
Agent runs this when it needs a credential
npx @cyclecore/secretsage grant OPENAI_API_KEY --yes
source .env
`$3
`bash
#!/bin/bash
if [ -z "$OPENAI_API_KEY" ]; then
echo "Need OPENAI_API_KEY - launching SecretSage..."
npx @cyclecore/secretsage grant OPENAI_API_KEY --yes
source .env
fi
Continue with agent work...
`$3
`bash
secretsage list --json
``json
{
"credentials": [
{ "name": "OPENAI_API_KEY" },
{ "name": "DATABASE_URL" }
],
"count": 2
}
`Security
- age encryption: Modern, audited cryptography (age-encryption.org)
- Local storage: Credentials never leave your machine
- File permissions: Identity files are stored with 0600 permissions
- Auto-gitignore: Automatically adds
.env and .secretsage/ to .gitignore
- Backup on grant: Creates .env.backup.* before modifyingVault Locations
| Location | Path | Use Case |
|----------|------|----------|
| Global |
~/.secretsage/ | Share credentials across projects |
| Local | .secretsage/ | Project-specific credentials |
| Custom | Any path | Shared drives, team locations |The global vault is used by default. Use
--local flag, --path , or set vault.defaultLocation in config.Configuration
Global config:
~/.secretsage/config.yaml
Local config: .secretsage/config.yaml`yaml
version: "1"vault:
defaultLocation: global # global | local
encryption:
provider: age
agent:
autoGitignore: true
backupEnvOnGrant: true
requireConfirmation: true
``Apache 2.0 - CycleCore Technologies
---
Created by CycleCore Technologies