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.

Installation

npm install -g @cyclecore/secretsage

Or use directly with npx:

npx @cyclecore/secretsage

Quick Start

# Initialize vault (one-time setup)
secretsage init

# Add a credential
secretsage add OPENAI_API_KEY

# Grant to .env for agent use
secretsage grant OPENAI_API_KEY

# Revoke when done
secretsage revoke --all

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 manager

SecretSage 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 done

Think of it as OAuth for LLM agents.

Commands

secretsage init

Initialize the vault and generate encryption keypair.

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

secretsage add <name>

Add a credential to the encrypted vault.

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

secretsage list

List credential names in the vault.

secretsage list          # Human-readable output
secretsage list --json   # Machine-readable for agents
secretsage list --all    # Include metadata

secretsage grant [names...]

Decrypt and write credentials to .env.

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)

secretsage revoke [names...]

Remove credentials from .env (vault remains intact).

secretsage revoke                    # Interactive selection
secretsage revoke OPENAI_API_KEY     # Specific credential
secretsage revoke --all              # All credentials

secretsage config

View or update configuration.

secretsage config                              # Show current config
secretsage config --path                       # Show config file path
secretsage config --set agent.autoGitignore=false

secretsage remove <name>

Permanently delete a credential from the vault.

secretsage remove OLD_API_KEY          # Interactive confirmation
secretsage remove OLD_API_KEY --yes    # Skip confirmation

secretsage rotate <name>

Update the value of an existing credential.

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

secretsage audit <name>

Show rotation history and audit trail for a credential.

secretsage audit STRIPE_SECRET_KEY        # Human-readable history
secretsage audit STRIPE_SECRET_KEY --json # Machine-readable for agents

secretsage wizard

Open interactive key entry wizard in new terminal (agent-human handoff).

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

secretsage deploy <project>

Deploy secrets to a remote server via rsync/SSH.

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

secretsage backup-codes

Securely store and manage 2FA backup/recovery codes.

# Add backup codes for a service (interactive)
secretsage backup-codes add github
secretsage backup-codes add google --account [email protected]

# List services with stored codes
secretsage backup-codes list

# Show codes when you need them
secretsage backup-codes show github

# Mark 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.

secretsage export

Export vault credentials for backup or transfer.

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

secretsage import

Import credentials from backup or external source.

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

secretsage status

Show vault status and health check.

secretsage status          # Human-readable status
secretsage status --json   # Machine-readable for agents

Agent Integration

Automatic Grant

Agents can request credentials programmatically:

# Agent runs this when it needs a credential
npx @cyclecore/secretsage grant OPENAI_API_KEY --yes
source .env

Shell Script Pattern

#!/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...

JSON Output for Agents

secretsage list --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 modifying

Vault 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 <dir>, or set vault.defaultLocation in config.

Configuration

Global config: ~/.secretsage/config.yaml Local config: .secretsage/config.yaml

version: "1"

vault:
  defaultLocation: global  # global | local

encryption:
  provider: age

agent:
  autoGitignore: true
  backupEnvOnGrant: true
  requireConfirmation: true

License

Apache 2.0 - CycleCore Technologies

Created by CycleCore Technologies