secret-box

A macOS CLI tool for secure secret storage with Touch ID authentication.

Features

• Touch ID protection — reading a secret requires biometric confirmation
• Per-app authorization — access is granted per-app per-secret and cached for 10 minutes
• AES-256-GCM encryption — all secrets encrypted at rest
• macOS Keychain integration — master key stored in the system keychain
• Binary data support — store any data via stdin
• Environment variable injection — run commands with secrets as env vars

Installation

curl -fsSL https://github.com/tkukushkin/secret-box/releases/latest/download/secret-box -o ~/.local/bin/secret-box
chmod +x ~/.local/bin/secret-box

Install with Go

go install github.com/tkukushkin/secret-box@latest

Build from source

go build -o secret-box
cp secret-box ~/.local/bin/

Usage

Save a secret

secret-box write my-secret "some value"

From stdin (text or binary):

echo -n "some value" | secret-box write my-secret
cat cert.pem | secret-box write my-cert

Read a secret

# Touch ID required
secret-box read my-secret

# Authenticate but don't cache the session
secret-box read --once my-secret

# Output to a file
secret-box read my-cert > cert.pem

List secrets

secret-box list

Delete secrets

secret-box delete my-secret my-cert

Reset all data

# Delete all secrets, auth cache, and the master key
secret-box reset

# Skip confirmation
secret-box reset --yes

Run a command with secrets

Environment variables and command arguments containing $(secret-name) references are resolved and replaced with actual secret values.

DB_PASSWORD='$(db-pass)' secret-box exec -- psql
DB_PASSWORD='$(db-pass)' secret-box exec -- psql '--password=$(db-pass)'
DB_PASSWORD='$(db-pass)' API_KEY='$(api-key)' secret-box exec -- myapp
DATABASE_URL='postgres://$(db-user):$(db-pass)@localhost/mydb' secret-box exec -- myapp

Data storage

• Master key is stored in macOS Keychain
• Secrets and auth cache are stored in ~/Library/Application Support/secret-box/db.sqlite3
• secret-box reset removes all data including the master key

Requirements

• macOS 13+
• Touch ID
• Go 1.23+

License

MIT