secrets

Securely manage secrets and sensitive configuration data.

Synopsis

xec secrets [subcommand] [args...] [options]
xec secret [subcommand] [args...] [options]  # Alias
xec s [subcommand] [args...] [options]       # Short alias

Description

The secrets command provides secure storage and management of sensitive data like passwords, API keys, tokens, and certificates. Secrets are encrypted at rest and can be referenced in configuration files and scripts.

Subcommands

set

Set a secret value.

xec secrets set <key> [options]

Options:

-v, --value <value> - Secret value (prompts securely if not provided)

Examples:

# Interactive mode (recommended - secure prompt)
xec secrets set DATABASE_PASSWORD

# Set with value (not recommended - visible in shell history)
xec secrets set API_KEY -v "sk-1234567890abcdef"

# Set complex secret
xec secrets set JWT_PRIVATE_KEY -v "$(cat private.key)"

get

Retrieve a secret value.

xec secrets get <key>

Examples:

# Get secret value (outputs to stdout)
xec secrets get DATABASE_PASSWORD

# Use in scripts
DB_PASS=$(xec secrets get DATABASE_PASSWORD)

# Use in other commands
curl -H "Authorization: Bearer $(xec secrets get API_TOKEN)" https://api.example.com

list

List all secret keys (values are never shown).

xec secrets list
xec secrets ls  # Alias

Examples:

# List all secrets
xec secrets list

# Output:
# Found 3 secrets:
#   • DATABASE_PASSWORD
#   • API_KEY  
#   • JWT_PRIVATE_KEY

delete

Delete a secret.

xec secrets delete <key> [options]
xec secrets rm <key> [options]  # Alias

Options:

-f, --force - Skip confirmation prompt

Examples:

# Delete with confirmation
xec secrets delete OLD_API_KEY

# Force delete without confirmation
xec secrets delete OLD_API_KEY --force

generate

Generate a random secret.

xec secrets generate <key> [options]

Options:

-l, --length <length> - Secret length (default: 32)
-f, --force - Overwrite existing secret without confirmation

Examples:

# Generate 32-character secret
xec secrets generate SESSION_SECRET

# Generate custom length
xec secrets generate API_SECRET -l 64

# Force overwrite existing
xec secrets generate TEMP_TOKEN -l 16 --force

export

Export secrets (WARNING: outputs plain text).

xec secrets export [options]

Options:

-f, --format <format> - Output format: json, env (default: json)
--force - Skip confirmation warning

Examples:

# Export as JSON (with warning prompt)
xec secrets export

# Export as environment variables
xec secrets export -f env

# Skip confirmation (dangerous!)
xec secrets export --force

import

Import secrets from file or stdin.

xec secrets import [options]

Options:

-f, --file <file> - Input file (uses stdin if not provided)
--format <format> - Input format: json, env (default: json)

Examples:

# Import from JSON file
xec secrets import -f secrets.json

# Import from environment format
xec secrets import -f .env --format env

# Import from stdin
cat secrets.json | xec secrets import

# Import environment variables from stdin
echo "SECRET_API_KEY=value123" | xec secrets import --format env

Interactive Mode

When called without arguments, the secrets command enters interactive mode:

xec secrets

Interactive mode provides a menu-driven interface for all secret operations with enhanced security prompts and validation.

Secret Storage

Encryption

Secrets are encrypted using industry-standard encryption:

Algorithm: AES-256-GCM
Key derivation: PBKDF2 with 100,000 iterations
Salt: Unique per secret store
IV: Unique per secret

Storage Location

Secrets are stored in the user's home directory:

~/.xec/secrets/
├── keyring.enc      # Encrypted secret store
├── salt             # Cryptographic salt
└── config           # Storage configuration

Provider Support

The secrets system supports multiple storage providers:

File (default): Encrypted files in ~/.xec/secrets/
System Keyring: OS-native keyring (macOS Keychain, Windows Credential Store, Linux Secret Service)
External: HashiCorp Vault, AWS Secrets Manager, etc.

Using Secrets in Configuration

Variable Interpolation

Reference secrets in configuration files:

# .xec/config.yaml
vars:
  DATABASE_URL: "postgresql://user:${secret:DATABASE_PASSWORD}@localhost/myapp"
  API_ENDPOINT: "https://api.example.com"
  
targets:
  hosts:
    production:
      host: prod.example.com
      username: deployer
      privateKey: ~/.ssh/id_rsa
      passphrase: "${secret:SSH_PASSPHRASE}"

Task Parameters

Use secrets in task definitions:

tasks:
  deploy:
    description: Deploy to production
    steps:
      - name: Deploy
        command: |
          docker run --rm \
            -e DATABASE_PASSWORD="${secret:DATABASE_PASSWORD}" \
            -e API_KEY="${secret:API_KEY}" \
            myapp:latest

Script Access

Access secrets in scripts:

// JavaScript/TypeScript scripts
const dbPassword = await secrets.get('DATABASE_PASSWORD');
const apiKey = await secrets.get('API_KEY');

// Connection string with secret
const connectionString = `postgresql://user:${dbPassword}@localhost/myapp`;

// HTTP request with secret
const response = await fetch('https://api.example.com/data', {
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
});

Secret Validation

Key Format

Secret keys must follow specific rules:

Start with a letter (A-Z, a-z)
Contain only letters, numbers, hyphens, dots, and underscores
Examples: API_KEY, database.password, jwt-secret

Value Constraints

Minimum length: 1 character
Maximum length: 64KB
Support for binary data (base64 encoded)
UTF-8 text encoding

Export Formats

JSON Format

{
  "DATABASE_PASSWORD": "secret123",
  "API_KEY": "sk-1234567890abcdef",
  "JWT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n..."
}

Environment Format

export SECRET_DATABASE_PASSWORD="secret123"
export SECRET_API_KEY="sk-1234567890abcdef"
export SECRET_JWT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
..."

Note: Environment format prefixes keys with SECRET_ and converts to uppercase with underscores.

Import Formats

JSON Import

# Create secrets.json
{
  "database-password": "secret123",
  "api.key": "sk-1234567890abcdef"
}

# Import
xec secrets import -f secrets.json

Environment Import

# Create .env file
SECRET_DATABASE_PASSWORD=secret123
SECRET_API_KEY=sk-1234567890abcdef

# Import (strips SECRET_ prefix)
xec secrets import -f .env --format env

Security Best Practices

Secret Creation

Use interactive mode for secret input (avoids shell history)
Generate random secrets when possible
Use meaningful names that indicate purpose
Rotate secrets regularly

# Good: Interactive input
xec secrets set DATABASE_PASSWORD

# Bad: Visible in shell history
xec secrets set DATABASE_PASSWORD -v "secret123"

Secret Usage

Never log secret values
Use environment variables in processes
Limit secret scope to necessary components
Audit secret access

Storage Security

Regular backups of encrypted secret store
Secure backup storage
Key rotation for long-lived secrets
Access monitoring

Backup and Recovery

Manual Backup

# Backup encrypted secrets
cp -r ~/.xec/secrets/ ~/backups/xec-secrets-$(date +%Y%m%d)

# Export for migration (WARNING: plain text)
xec secrets export > secrets-backup.json

Recovery

# Restore from backup
cp -r ~/backups/xec-secrets-20231201/ ~/.xec/secrets/

# Import from export
xec secrets import -f secrets-backup.json

Migration Between Systems

Export from Source

# On source system
xec secrets export -f json > secrets.json

Import to Target

# On target system
xec secrets import -f secrets.json

# Or via stdin
cat secrets.json | xec secrets import

Troubleshooting

Common Issues

"Permission denied" errors:

# Fix permissions
chmod 700 ~/.xec/secrets/
chmod 600 ~/.xec/secrets/*

"Secret not found" errors:

# List available secrets
xec secrets list

# Check secret name spelling
xec secrets list | grep -i "partial_name"

"Decryption failed" errors:

Indicates corrupted secret store or wrong encryption key
Restore from backup if available
Re-create secrets if necessary

Debug Mode

# Enable debug logging
export XEC_DEBUG=secrets
xec secrets list

Performance Considerations

Caching: Secrets are not cached by default for security
Batch operations: Import/export for multiple secrets
Network storage: Avoid network filesystems for secret storage
Key derivation: First access may be slower due to PBKDF2

config - Manage configuration with secret references
run - Execute scripts with secret access
inspect - Inspect configuration (secrets are masked)

Configuration

Secret behavior can be configured in .xec/config.yaml:

secrets:
  provider: file  # file, keyring, vault
  
  # File provider settings
  file:
    directory: ~/.xec/secrets
    
  # Keyring provider settings
  keyring:
    service: xec
    
  # Vault provider settings
  vault:
    address: https://vault.example.com
    path: secret/xec

Exit Codes

0 - Success
1 - General error
2 - Invalid arguments
3 - Secret not found
4 - Encryption/decryption error
5 - Permission error

Synopsis​

Description​

Subcommands​

set​

get​

list​

delete​

generate​

export​

import​

Interactive Mode​

Secret Storage​

Encryption​

Storage Location​

Provider Support​

Using Secrets in Configuration​

Variable Interpolation​

Task Parameters​

Script Access​

Secret Validation​

Key Format​

Value Constraints​

Export Formats​

JSON Format​

Environment Format​

Import Formats​

JSON Import​

Environment Import​

Security Best Practices​

Secret Creation​

Secret Usage​

Storage Security​

Backup and Recovery​

Manual Backup​

Recovery​

Migration Between Systems​

Export from Source​

Import to Target​

Troubleshooting​

Common Issues​

Debug Mode​

Performance Considerations​

Related Commands​

Configuration​

Exit Codes​

Synopsis

Description

Subcommands

set

get

list

delete

generate

export

import

Interactive Mode

Secret Storage

Encryption

Storage Location

Provider Support

Using Secrets in Configuration

Variable Interpolation

Task Parameters

Script Access

Secret Validation

Key Format

Value Constraints

Export Formats

JSON Format

Environment Format

Import Formats

JSON Import

Environment Import

Security Best Practices

Secret Creation

Secret Usage

Storage Security

Backup and Recovery

Manual Backup

Recovery

Migration Between Systems

Export from Source

Import to Target

Troubleshooting

Common Issues

Debug Mode

Performance Considerations

Related Commands

Configuration

Exit Codes