khamel83/secrets

/secrets — SOPS/Age Secret Management

Manage encrypted secrets between the master vault and projects.

Master Vault

Location: ~/github/oneshot/secrets/ Encryption: SOPS + Age (config in ~/github/oneshot/.sops.yaml)

CLI Commands

The secrets CLI (at ~/.local/bin/secrets) works from any directory.

# Read a single key
secrets get EXA_API_KEY

# List all vault files and their keys
secrets list

# Decrypt a full file to stdout
secrets decrypt research_keys

# Add/update a key (non-interactive, no commit)
secrets set research_keys 'NEW_KEY=value'

# Add/update + commit + push
secrets set research_keys 'NEW_KEY=value' --commit

# Bootstrap .env in a project from the vault
cd ~/github/myproject && secrets init services

Pull Secrets into a Project

1. Identify which secrets the project needs (check .env.example or imports)
2. Run secrets init <namespace> to write .env from the vault
3. Verify the app can start with the new secrets

Push New Secrets to the Vault

1. Add/update: secrets set <namespace> 'KEY=value'
2. Commit when ready: secrets set <namespace> 'KEY=value' --commit

Common Patterns

# Find which vault file contains a key
secrets list | grep -i brave

# Extract a key for use in a script
BRAVE_KEY=$(secrets get BRAVE_API_KEY)

# View all keys in a namespace
secrets decrypt research_keys

How It Works

• Vault files are SOPS-encrypted dotenv at ~/github/oneshot/secrets/*.encrypted
• secrets get searches all vault files for the key
• secrets set decrypts the file, merges the new key, re-encrypts
• secrets init decrypts a vault file to .env in the current directory
• Age key lives at ~/.age/key.txt

Safety Rules

• Never display secret values in output
• Always verify .env is in .gitignore before writing
• Namespace secrets by project in the vault
• Never commit plaintext secrets
• Never suggest .env files without encryption

Troubleshooting

| Problem | Fix | |---------|-----| | no matching creation rules found | Input file must end in .encrypted (handled by the CLI automatically) | | key not found in any vault file | Key doesn't exist in any vault — add it with secrets set | | file not found | Check secrets list for available namespaces |