Handle Secrets

---
name: handle-secrets
description: >-
  Handle user-provided secrets in CLI tools: input methods, credential storage,
  and masking. Use when a CLI accepts API keys, tokens, or passwords.
---

# Handle Secrets

Best practices for handling secrets that **users pass to your CLI tool** (API keys, tokens, passwords), not secrets used during development.

## Core Principles

1. **Never accept secrets as command-line arguments** - Arguments are visible via `ps aux`, recorded in shell history, and captured by audit logs
1. **Make the secure path the default** - Users who do nothing special should get the safest behavior
1. **Separate config from credentials** - Non-sensitive settings and secret material belong in different files
1. **Mask secrets in all output** - Debug logs, error messages, HTTP traces, and verbose output must redact secret values
1. **Warn loudly about insecure behavior** - If users opt into something dangerous, tell them explicitly

## Security Hierarchy (Safest to Most Dangerous)

| Method                                  | Safety     | Use when                                 |
| --------------------------------------- | ---------- | ---------------------------------------- |
| OS keychain / credential helper         | Safest     | Persistent storage for interactive users |
| Secret references (`op://`, vault URIs) | Safe       | Storing pointers instead of secrets      |
| Stdin / pipes / file descriptors        | Safe       | Automation and scripting                 |
| Interactive TTY prompt                  | Safe       | Human users at a terminal                |
| Config files (0600 permissions)         | Acceptable | Persistent storage without keychain      |
| Environment variables                   | Acceptable | CI/CD pipelines and containers           |
| Command-line arguments                  | **Never**  | -                                        |

## Workflow

1. **Quick reviews:** Check against `references/checklist.md`
1. **Choosing an input method:** Read `references/security-hierarchy.md`
1. **Designing credential flows:** Read `references/design-patterns.md`
1. **Avoiding known pitfalls:** Read `references/anti-patterns.md`
1. **Language-specific code:** Read `references/language-libraries.md`

## Reference Navigation

**Quick reviews (default):**

- `references/checklist.md` - Condensed, actionable rules

**Deep dives by topic:**

- `references/security-hierarchy.md` - Ranked input methods with attack surfaces and mitigations
- `references/design-patterns.md` - Credential fallback chains, OAuth device flow, token hygiene, masking
- `references/anti-patterns.md` - Real CVEs and incidents from insecure secret handling
- `references/language-libraries.md` - Rust, Go, Python, Node.js, Ruby libraries and code patterns

## Credential Resolution Fallback Chain

Tools should resolve credentials in this order:

1. Environment variable (for CI/CD)
1. Credential helper / OS keychain (for persistent storage)
1. Config file with 0600 permissions (fallback)
1. Interactive TTY prompt (for humans)

Never fall through to accepting `--password <value>` as an argument.

## Sources

- [Building CLI tools that handle user secrets responsibly](https://www.macchaffee.com/blog/2025/cli-secret-handling/) - Mac Chaffee
- GitHub CLI, Docker, AWS CLI, kubectl, and 1Password CLI implementations