メインコンテンツまでスキップ

Managing Secrets

This guide covers the core secret management operations: storing, retrieving, listing, and deleting secrets.

Prerequisites​

Storing Secrets​

Use the set command to store a secret. The value is read from standard input for security (avoiding shell history).

Basic Usage​

# Store a secret (value from stdin)
echo "sk-your-api-key" | secretctl set OPENAI_API_KEY

With Metadata​

Add context to your secrets with metadata:

# Add notes and tags
echo "mypassword" | secretctl set DB_PASSWORD \
  --notes="Production database credentials" \
  --tags="prod,database"

# Add a URL reference
echo "sk-xxx" | secretctl set API_KEY \
  --url="https://console.example.com/api-keys"

# Set expiration (e.g., 30 days, 1 year)
echo "temp-token" | secretctl set TEMP_TOKEN --expires="30d"

Available Flags​

FlagDescriptionExample
--notesAdd descriptive notes--notes="Production DB"
--tagsComma-separated tags--tags="prod,api"
--urlReference URL--url="https://..."
--expiresExpiration duration--expires="30d" or --expires="1y"

Retrieving Secrets​

Use the get command to retrieve a secret value.

Basic Usage​

# Get secret value
secretctl get API_KEY

Output:

sk-abc123xyz789

With Metadata​

# Show metadata along with the value
secretctl get API_KEY --show-metadata

Output:

Key: API_KEY
Value: sk-abc123xyz789
Tags: api, prod
URL: https://console.example.com/api-keys
Notes: OpenAI API key for production
Created: 2025-01-15 10:30:00
Updated: 2025-01-15 10:30:00

Listing Secrets​

Use the list command to see all stored secrets.

Basic Usage​

# List all secret keys
secretctl list

Output:

API_KEY
DB_PASSWORD
AWS_ACCESS_KEY
AWS_SECRET_KEY

Filter by Tag​

# Show only secrets with specific tag
secretctl list --tag=prod

Find Expiring Secrets​

# Show secrets expiring within 7 days
secretctl list --expiring=7d

# Show secrets expiring within 30 days
secretctl list --expiring=30d

Deleting Secrets​

Use the delete command to remove a secret from the vault.

# Delete a secret
secretctl delete OLD_API_KEY
注意

Deletion is permanent. The secret cannot be recovered after deletion.

Updating Secrets​

To update a secret, use the set command with the same key. The existing secret will be overwritten.

# Update an existing secret
echo "new-password" | secretctl set DB_PASSWORD

# Update with new metadata
echo "new-password" | secretctl set DB_PASSWORD \
  --notes="Updated 2025-01" \
  --tags="prod,rotated"

Hierarchical Keys​

Organize secrets using forward slashes to create a hierarchy:

# Store secrets with hierarchical keys
echo "access-key" | secretctl set aws/access_key
echo "secret-key" | secretctl set aws/secret_key
echo "host" | secretctl set db/prod/host
echo "password" | secretctl set db/prod/password

This enables powerful wildcard patterns with the run and export commands:

# Inject all AWS secrets
secretctl run -k "aws/*" -- aws s3 ls

# Export all production database secrets
secretctl export -k "db/prod/*" -o .env

Best Practices​

Use Descriptive Keys​

# Good: Clear, hierarchical naming
echo "xxx" | secretctl set github/personal_access_token
echo "xxx" | secretctl set aws/production/access_key

# Avoid: Ambiguous names
echo "xxx" | secretctl set token1
echo "xxx" | secretctl set key

Add Metadata for Context​

# Include notes for future reference
echo "xxx" | secretctl set STRIPE_API_KEY \
  --notes="Live key for production. Test key is in STRIPE_TEST_KEY" \
  --tags="stripe,payments,prod" \
  --url="https://dashboard.stripe.com/apikeys"

Set Expiration for Temporary Secrets​

# Temporary tokens should have expiration
echo "xxx" | secretctl set DEPLOY_TOKEN --expires="7d"

# Regular rotation reminders
echo "xxx" | secretctl set DB_PASSWORD --expires="90d"

Use Tags for Organization​

# Tag by environment
echo "xxx" | secretctl set API_KEY --tags="prod"
echo "xxx" | secretctl set API_KEY_DEV --tags="dev"

# Tag by service
echo "xxx" | secretctl set STRIPE_KEY --tags="stripe,payments"
echo "xxx" | secretctl set SENDGRID_KEY --tags="sendgrid,email"

Troubleshooting​

"secret not found" Error​

The specified key does not exist in the vault.

# List all secrets to verify the key
secretctl list

# Check for typos in the key name
secretctl get API_KEY  # correct
secretctl get api_key  # keys are case-sensitive

"vault is locked" Error​

The vault needs to be unlocked with your master password.

# Any command will prompt for the password
secretctl list
Enter master password: ********

Input Not Being Read​

Ensure you're piping the value correctly:

# Correct: pipe the value
echo "myvalue" | secretctl set MY_KEY

# Wrong: no pipe (will wait for input)
secretctl set MY_KEY

Next Steps​