secrets

name: secrets description: Manage secrets stored in OS-native credential storage (Keychain, libsecret, Credential Manager). Use when the user needs to store, retrieve, or delete sensitive credentials like API keys, tokens, or passwords securely. allowed-tools: Bash(secrets *)

Secrets Management

The secrets CLI stores credentials in the operating system's native credential storage:

• macOS: Keychain Services
• Linux: libsecret (GNOME Keyring, KWallet)
• Windows: Windows Credential Manager

All credentials are encrypted at rest by the OS and scoped to the current user.

Commands

Store a secret

# Via stdin (recommended - avoids shell history exposure)
echo "sk-proj-xxxxx" | secrets set --service openai --name api-key

# Via --value flag (visible in shell history)
secrets set --service openai --name api-key --value "sk-proj-xxxxx"

Retrieve a secret

# Human-readable (value only)
secrets get --service openai --name api-key

# JSON output
secrets get --service openai --name api-key --json
# Output: {"service":"openai","name":"api-key","value":"sk-proj-xxxxx"}

Delete a secret

secrets delete --service openai --name api-key

Exit codes

Service naming convention

Use consistent, descriptive service names:

• openai for OpenAI API keys
• anthropic for Anthropic API keys
• github for GitHub tokens
• Use reverse domain notation for organization tools (e.g., com.example.my-app)

Security guidelines

• Always prefer stdin over --value flag to avoid shell history exposure
• Never log or display secret values in output unless explicitly requested by the user
• Use secrets get output in variable assignments: API_KEY=$(secrets get --service openai --name api-key)
• Check if a credential exists before prompting the user: use exit code to determine existence