Skip to main content

CLI Reference

The env-secrets command-line interface provides a simple way to inject secrets as environment variables into your applications.

Basic Syntax​

env-secrets <provider> [options] -- <program-to-run>

Providers​

Currently supported provider: aws

AWS Secrets Manager Options​

Required Parameters​

  • -s, --secret <secret-name> - The name or ARN of the secret in AWS Secrets Manager

Optional Parameters​

  • -r, --region <region> - AWS region where the secret is stored (defaults to AWS_DEFAULT_REGION)
  • -p, --profile <profile> - AWS profile to use (defaults to environment variables or IAM role)
  • -o, --output <file> - Output secrets to a file instead of injecting into environment variables. File will be created with 0400 permissions and will not overwrite existing files

AWS Secret Management Commands​

Use env-secrets aws secret <command> to manage AWS Secrets Manager secrets directly.

Use env-secrets aws -s <secret-name> together with either -- <program-to-run> to inject secret values into a spawned child process, or with -o <file> to write exports to a file.
env-secrets aws secret <command> is the lifecycle-management path and does not inject values by itself.

Commands​

  • create - Create a new secret
  • update - Update secret value or metadata
  • append - Add or overwrite one key in an existing JSON secret
  • remove - Remove one or more keys from an existing JSON secret
  • upsert (import) - Create or update one JSON secret from an env file
  • list - List secrets
  • get - Get secret metadata/version info
  • delete - Delete a secret

Shared Options​

  • -r, --region <region> - AWS region
  • -p, --profile <profile> - AWS profile
  • --output <format> - Output format: json or table (default: table)

Command-Specific Options​

  • create
    • -n, --name <name> (required)
    • -v, --value <value> or --value-stdin or -f, --file <path>
    • -d, --description <description>
    • -k, --kms-key-id <kmsKeyId>
    • -t, --tag <key=value...>
  • update
    • -n, --name <name> (required)
    • -v, --value <value> or --value-stdin or -f, --file <path>
    • -d, --description <description>
    • -k, --kms-key-id <kmsKeyId>
  • upsert / import
    • -f, --file <path> (required)
    • -n, --name <name> (required)
    • -d, --description <description>
    • -k, --kms-key-id <kmsKeyId>
    • -t, --tag <key=value...> (applies on create)
  • append
    • -n, --name <name> (required)
    • --key <key> (required)
    • -v, --value <value> or --value-stdin or -f, --file <path>
  • remove
    • -n, --name <name> (required)
    • --key <key...> (required, repeatable)
  • list
    • --prefix <prefix>
    • -t, --tag <key=value...>
  • get
    • -n, --name <name> (required)
  • delete
    • -n, --name <name> (required)
    • -y, --yes (required for delete)
    • --recovery-days <7-30>
    • --force-delete-without-recovery

Global Options​

  • --help - Show help information
  • --version - Show version information

Examples​

Basic Usage​

# Run a Node.js application with secrets
env-secrets aws -s my-app-secrets -r us-east-1 -- node app.js

# Run a Python application
env-secrets aws -s my-app-secrets -r us-east-1 -- python app.py

# Run a shell command
env-secrets aws -s my-app-secrets -r us-east-1 -- echo "Hello, $USER_NAME!"

# Output secrets to a file
env-secrets aws -s my-app-secrets -r us-east-1 -o secrets.env

Environment Variable Inspection​

# Check what environment variables are injected
env-secrets aws -s my-app-secrets -r us-east-1 -- env | grep -E "(DATABASE|API|SECRET)"

# List all environment variables
env-secrets aws -s my-app-secrets -r us-east-1 -- env

# Check specific variables
env-secrets aws -s my-app-secrets -r us-east-1 -- bash -c 'echo "DB: $DATABASE_URL, API: $API_KEY"'

Docker Integration​

# Run Docker container with secrets
env-secrets aws -s docker-secrets -r us-east-1 -- docker run \
  -e DATABASE_URL \
  -e API_KEY \
  -e REDIS_URL \
  my-app:latest

# Use with docker-compose
env-secrets aws -s docker-secrets -r us-east-1 -- docker-compose up

Kubernetes Integration​

# Run in Kubernetes pod
env-secrets aws -s k8s-secrets -r us-east-1 -- node app.js

# Use with kubectl exec
kubectl exec -it my-pod -- env-secrets aws -s k8s-secrets -r us-east-1 -- node app.js

CI/CD Pipelines​

# GitHub Actions
env-secrets aws -s prod/app -r us-east-1 -- npm run deploy

# GitLab CI
env-secrets aws -s prod/app -r us-east-1 -- npm run deploy

Debug Mode​

# Enable debug logging
DEBUG=env-secrets env-secrets aws -s my-secret -r us-east-1 -- node app.js

# Detailed debug logging
DEBUG=env-secrets,env-secrets:secretsmanager env-secrets aws -s my-secret -r us-east-1 -- node app.js

File Output Mode​

# Output secrets to a file with secure permissions
env-secrets aws -s my-app-secrets -r us-east-1 -o secrets.env

# Output with specific profile
env-secrets aws -s my-secret -r us-east-1 -p my-profile -o /tmp/secrets.env

# File content example (secrets.env):
# export DATABASE_URL=postgres://user:pass@localhost:5432/db
# export API_KEY=abc123
# export REDIS_URL=redis://localhost:6379

# Source the file in your application
source secrets.env
node app.js

# Or use with Docker
env-secrets aws -s docker-secrets -r us-east-1 -o .env
docker run --env-file .env my-app:latest

This is also the supported way to load values into your current shell session. env-secrets aws -s ... -- <command> only affects the spawned child process.

Secret Management​

# Create
env-secrets aws secret create -n app/dev/api -v '{"API_KEY":"abc123"}' --output json

# Create from stdin (recommended for sensitive values)
echo -n 'super-secret-value' | env-secrets aws secret create -n app/dev/raw --value-stdin

# Update value
env-secrets aws secret update -n app/dev/api -v '{"API_KEY":"xyz789"}'

# Update from stdin
echo -n 'rotated-value' | env-secrets aws secret update -n app/dev/raw --value-stdin

# Upsert/import from env file
env-secrets aws secret upsert --file .env --name app/dev --output json
# alias
env-secrets aws secret import --file .env --name app/dev --output json

# Result: one secret named app/dev with SecretString like:
# {"API_KEY":"abc123","DATABASE_URL":"postgres://..."}

# Append/remove keys (JSON secret only)
env-secrets aws secret append -n app/dev --key JIRA_EMAIL_TOKEN -v blah --output json
env-secrets aws secret remove -n app/dev --key OLD_TOKEN --output json

# List
env-secrets aws secret list --prefix app/dev --output table

# Get metadata (does not print secret value)
env-secrets aws secret get -n app/dev/api --output json

# Delete with confirmation
env-secrets aws secret delete -n app/dev/raw --recovery-days 7 --yes

Environment Variable Behavior​

JSON Secret Parsing​

Secrets stored as JSON are automatically parsed and converted to environment variables:

# Secret content: {"DATABASE_URL":"postgres://...","API_KEY":"abc123"}
# Results in: DATABASE_URL=postgres://..., API_KEY=abc123

Nested Object Handling​

Nested JSON objects are flattened:

# Secret: {"database":{"url":"postgres://...","port":5432}}
# Results in: DATABASE_URL=postgres://..., DATABASE_PORT=5432

Array Handling​

Arrays are converted to comma-separated values:

# Secret: {"allowed_ips":["192.168.1.1","10.0.0.1"]}
# Results in: ALLOWED_IPS=192.168.1.1,10.0.0.1

Special Character Handling​

Special characters in keys are converted to underscores:

# Secret: {"api-key":"abc123","db_url":"postgres://..."}
# Results in: API_KEY=abc123, DB_URL=postgres://...

Error Handling​

Common Error Messages​

ErrorDescriptionSolution
ConfigErrorAWS credentials not configuredSet up AWS credentials or profile
ResourceNotFoundExceptionSecret doesn't existVerify secret name and region
AccessDeniedExceptionInsufficient permissionsCheck IAM policies
ValidationExceptionInvalid secret nameUse valid secret name format

Exit Codes​

  • 0 - Success
  • 1 - General error
  • 2 - Configuration error
  • 3 - Secret not found
  • 4 - Permission denied

Security Notes​

  • No Local Storage: Secrets are never stored locally (unless using -o flag)
  • Process Isolation: Secrets are only injected into the child process
  • No Logging: Secret values are never logged
  • Clean Exit: Environment variables are cleaned up when the process exits
  • File Security: When using -o flag, files are created with 0400 permissions (read-only for owner) and existing files are never overwritten

Performance Considerations​

  • Network Latency: First secret retrieval may take longer due to AWS API calls
  • Region Proximity: Use secrets in the same region as your application
  • Secret Size: Keep secrets small for better performance
  • Connection Reuse: AWS SDK connections are reused automatically