pact secret

Manage secrets (API keys, tokens) securely in your OS keychain.

Secrets are never stored in your pact repo. They live only in your OS keychain.

Commands

Set a secret

pact secret set <name>

Prompts for the secret value (input is hidden):

$ pact secret set ANTHROPIC_API_KEY
Enter value: ****************************
✓ Secret stored in keychain

List secrets

pact secret list

Shows all secrets configured in pact.json and their status:

$ pact secret list

Configured secrets:
  ANTHROPIC_API_KEY    ● set
  OPENAI_API_KEY       ○ not set
  GITHUB_TOKEN         ● set

Remove a secret

pact secret remove <name>

$ pact secret remove OPENAI_API_KEY
✓ Secret removed from keychain

Configuration

Secrets are declared in pact.json:

{
  "version": "1.0.0",
  "user": "cloudboy-jh",
  "modules": { ... },
  "secrets": [
    "ANTHROPIC_API_KEY",
    "OPENAI_API_KEY",
    "GITHUB_TOKEN",
    "NPM_TOKEN"
  ]
}

This tells Pact which secrets your configuration expects.

Keychain Storage

Secrets are stored in your OS's native keychain:

Viewing in Keychain (macOS)

1. Open "Keychain Access" app
2. Search for "pact"
3. You'll see entries like pact:ANTHROPIC_API_KEY

Using Secrets

Secrets are available as environment variables when you need them. You can reference them in your shell config:

# In your .zshrc
export ANTHROPIC_API_KEY=$(security find-generic-password -s "pact" -a "ANTHROPIC_API_KEY" -w 2>/dev/null)

Or use tools that read from the keychain directly.

Example Workflow

# 1. Add secret to pact.json
pact edit
# Add "ANTHROPIC_API_KEY" to the secrets array

# 2. Set the secret value
pact secret set ANTHROPIC_API_KEY
# Enter your API key

# 3. Verify it's set
pact secret list

# 4. On a new machine after pact init
pact secret list
# Shows ANTHROPIC_API_KEY as "not set"

pact secret set ANTHROPIC_API_KEY
# Enter your API key for this machine

Security Best Practices

Never commit secrets to your pact repo. The secrets array in pact.json only declares what secrets exist — the values are stored locally.

1. Use unique keys per service: Don't reuse API keys across services
2. Rotate keys regularly: Update your secrets periodically
3. Use minimal permissions: API keys should have only needed scopes
4. Monitor usage: Check your API provider dashboards for unusual activity

Supported Secret Types

You can store any string as a secret:

• API keys (Anthropic, OpenAI, etc.)
• Access tokens (GitHub, NPM, etc.)
• Passwords
• Private keys (though files might be better)
• Any sensitive configuration value

Troubleshooting

"Keychain access denied" (macOS)

Grant terminal access to Keychain:

1. Open Keychain Access
2. Preferences > General
3. Allow apps to access Keychain

"No keyring daemon" (Linux)

Install and start gnome-keyring:

# Ubuntu/Debian
sudo apt install gnome-keyring

# Start the daemon
gnome-keyring-daemon --start

Secret not found after machine restart

The keyring daemon may need to be unlocked. On Linux, this usually happens automatically at login.