secrets

Manage encrypted secrets for your deployments.

Synopsis

odysseus secrets <command> [options]

Commands for managing encrypted secrets files.

Commands

generate-key

Generate a new master key for encrypting secrets.

odysseus secrets generate-key

Output:

Generated master key:
a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd

Store this key securely. You will need it to encrypt/decrypt secrets.
Set it as ODYSSEUS_MASTER_KEY environment variable.

The key is a 64-character hex string (256 bits).

encrypt

Encrypt a plaintext secrets file.

odysseus secrets encrypt --input <file> --file <output>

Options

--input FILE

Source plaintext YAML file.

--file FILE

Output encrypted file.

Example

# Create plaintext secrets
cat > secrets.yml << EOF
DATABASE_URL: postgres://user:pass@localhost/myapp
RAILS_MASTER_KEY: abc123def456
REDIS_URL: redis://localhost:6379
EOF

# Encrypt
ODYSSEUS_MASTER_KEY=your-key odysseus secrets encrypt \
  --input secrets.yml \
  --file secrets.yml.enc

# Clean up plaintext
rm secrets.yml

decrypt

Decrypt and display a secrets file.

odysseus secrets decrypt --file <file>

Options

--file FILE

Encrypted file to decrypt.

Example

ODYSSEUS_MASTER_KEY=your-key odysseus secrets decrypt --file secrets.yml.enc

Output:

DATABASE_URL: postgres://user:pass@localhost/myapp
RAILS_MASTER_KEY: abc123def456
REDIS_URL: redis://localhost:6379

To save to a file:

ODYSSEUS_MASTER_KEY=your-key odysseus secrets decrypt \
  --file secrets.yml.enc > secrets.yml

edit

Edit secrets in your default editor.

odysseus secrets edit --file <file>

Options

--file FILE

Encrypted file to edit.

Example

ODYSSEUS_MASTER_KEY=your-key odysseus secrets edit --file secrets.yml.enc

This:

1. Decrypts to a temporary file
2. Opens in $EDITOR (or vi if not set)
3. Re-encrypts when you save and close
4. Removes the temporary file

export EDITOR=vim
export EDITOR="code --wait"  # VS Code
export EDITOR=nano

Environment variables

ODYSSEUS_MASTER_KEY

The encryption key. Required for all secrets operations.

export ODYSSEUS_MASTER_KEY=your-key
odysseus secrets decrypt --file secrets.yml.enc

Or inline:

ODYSSEUS_MASTER_KEY=your-key odysseus secrets decrypt --file secrets.yml.enc

Secrets file format

Plaintext format

Standard YAML key-value pairs:

DATABASE_URL: postgres://user:pass@localhost/myapp
RAILS_MASTER_KEY: abc123def456
REDIS_URL: redis://localhost:6379
AWS_ACCESS_KEY_ID: AKIA...
AWS_SECRET_ACCESS_KEY: secret...

In deploy.yml

Reference secrets in your configuration:

env:
  clear:
    RAILS_ENV: production
  secret:
    - DATABASE_URL
    - RAILS_MASTER_KEY
    - REDIS_URL

secrets_file: secrets.yml.enc

Workflows

Initial setup

# 1. Generate key (once)
odysseus secrets generate-key
# Save the output key securely

# 2. Create secrets file
cat > secrets.yml << EOF
DATABASE_URL: postgres://...
RAILS_MASTER_KEY: ...
EOF

# 3. Encrypt
ODYSSEUS_MASTER_KEY=your-key odysseus secrets encrypt \
  --input secrets.yml \
  --file secrets.yml.enc

# 4. Clean up and commit
rm secrets.yml
git add secrets.yml.enc
git commit -m "Add encrypted secrets"

Adding a secret

ODYSSEUS_MASTER_KEY=your-key odysseus secrets edit --file secrets.yml.enc
# Add new line: NEW_SECRET: value
# Save and close

Rotating secrets

# Edit and change values
ODYSSEUS_MASTER_KEY=your-key odysseus secrets edit --file secrets.yml.enc

# Deploy with new secrets
ODYSSEUS_MASTER_KEY=your-key odysseus deploy --image v1.0.0

Multiple environments

# Production secrets
odysseus secrets encrypt --input prod-secrets.yml --file secrets.prod.yml.enc

# Staging secrets
odysseus secrets encrypt --input staging-secrets.yml --file secrets.staging.yml.enc

Exit codes