Doppler

Overview

Manage application secrets and environment variables through the Doppler CLI. Covers authentication, project/config setup, secret injection into processes, secret CRUD operations, bulk import/export, service tokens for CI/CD, template-based secret substitution, and integrations with Docker and Kubernetes.

Instructions

1. Install and authenticate

# macOS
brew install dopplerhq/cli/doppler
# Debian/Ubuntu — see https://docs.doppler.com/docs/install-cli for full apt setup
# Windows
winget install doppler.doppler

Authenticate and verify:

doppler login
doppler me

2. Set up a project directory

Link the current directory to a Doppler project and config (creates doppler.yaml):

doppler setup
doppler setup --project my-api --config dev --no-interactive

3. Inject secrets into processes

Run any command with secrets injected as environment variables:

doppler run -- npm start
doppler run -- python manage.py runserver
doppler run -- docker compose up

Override the project/config per command:

doppler run -p payments-api -c stg -- ./run-tests.sh

Run multiple chained commands:

doppler run --command="./configure && ./process-jobs; ./cleanup"

4. Read and manage secrets

List all secrets:

doppler secrets
doppler secrets --only-names

Get a single secret value:

doppler secrets get DATABASE_URL --plain

Get multiple secrets as JSON:

doppler secrets get DATABASE_URL REDIS_URL API_KEY --json

5. Set and update secrets

doppler secrets set API_KEY="sk-live-abc123def456"
doppler secrets set DB_HOST="db.prod.internal" DB_PORT="5432"
cat tls-cert.pem | doppler secrets set TLS_CERT              # from file/stdin
doppler secrets set PORT="8080" --type integer
doppler secrets set STRIPE_KEY="sk_live_..." --visibility restricted
doppler secrets delete DEPRECATED_KEY

6. Download and upload secrets in bulk

Download in various formats:

doppler secrets download --no-file --format=json
doppler secrets download --no-file --format=env > .env
doppler secrets download --no-file --format=yaml > config.yaml

Supported formats: json, yaml, env, env-no-quotes, docker, dotnet-json.

Upload from a file:

doppler secrets upload .env
doppler secrets upload secrets.json

7. Mount secrets as ephemeral files

Mount secrets as a named pipe (most secure file-based method):

doppler run --mount .env -- npm start
doppler run --mount config.json --mount-format json -- ./app

Limit file reads for extra security:

doppler run --mount .env --mount-max-reads 1 -- php artisan config:cache

8. Use secret templates

Create a template file (e.g., config.tmpl):

db_host: {{.DB_HOST}}
db_port: {{.DB_PORT}}
{{with .LOG_FILE}}
log_file: {{.}}
{{end}}

Substitute and output:

doppler secrets substitute config.tmpl --output config.yaml

Pipe directly to kubectl:

kubectl apply -f <(doppler secrets substitute k8s-secret.yaml.tmpl)

9. Create service tokens for CI/CD

doppler configs tokens create ci-deploy -p payments-api -c prd --max-age 24h --plain

Use in CI via env var or inline flag:

export DOPPLER_TOKEN="dp.st.prd.xxxx"
doppler run -- ./deploy.sh
doppler run --token="dp.st.prd.xxxx" -- ./deploy.sh

10. Name transformers

Transform secret names for framework compatibility:

doppler run --name-transformer camel -- node app.js        # API_KEY → apiKey
doppler run --name-transformer tf-var -- terraform apply    # API_KEY → TF_VAR_api_key
doppler run --name-transformer lower-snake -- python app.py # API_KEY → api_key

Available transformers: camel, upper-camel, lower-snake, tf-var, dotnet-env, lower-kebab.

11. Docker and Kubernetes integration

Pass secrets to Docker containers:

docker run --env-file <(doppler secrets download --no-file --format docker) my-app:latest

Create a Kubernetes secret:

kubectl create secret generic app-secrets \
  --from-env-file <(doppler secrets download --no-file --format docker)

Examples

Example 1: Setting up a new microservice with Doppler

User request: "Set up Doppler for our Node.js order-service with dev and production configs"

Actions:

cd ~/projects/order-service
doppler setup --project order-service --config dev --no-interactive

# Set dev secrets
doppler secrets set \
  DATABASE_URL="postgresql://localhost:5432/orders_dev" \
  REDIS_URL="redis://localhost:6379/0" \
  STRIPE_KEY="sk_test_your_stripe_test_key_here" \
  LOG_LEVEL="debug" \
  -p order-service -c dev

# Set production secrets
doppler secrets set \
  DATABASE_URL="postgresql://db.prod.internal:5432/orders" \
  REDIS_URL="redis://redis.prod.internal:6379/0" \
  STRIPE_KEY="sk_live_51HG4..." \
  LOG_LEVEL="warn" \
  -p order-service -c prd

# Run locally with dev secrets
doppler run -- npm run dev

# Generate a production service token for CI/CD
doppler configs tokens create railway-deploy -p order-service -c prd --max-age 720h --plain

Example 2: Migrating secrets from .env files to Doppler

User request: "Migrate our auth-service .env secrets to Doppler"

Actions:

doppler login
doppler secrets upload .env -p auth-service -c dev
doppler secrets -p auth-service -c dev               # verify import

# Update start command: replace "source .env && node server.js" with:
doppler run -p auth-service -c dev -- node server.js

# Remove .env from repo
echo ".env" >> .gitignore

Team members onboard with:

doppler login && doppler setup && doppler run -- node server.js

Guidelines

• Always use doppler run to inject secrets rather than downloading to plain-text files. The --mount flag with named pipes is the most secure file-based option.
• Use doppler setup in project directories so subsequent commands inherit the project/config context automatically.
• Create service tokens with --max-age for CI/CD pipelines instead of using personal auth tokens.
• Use --visibility restricted for highly sensitive secrets like private keys and API credentials.
• When piping secret values into files (e.g., doppler secrets get KEY --plain > file), set file permissions immediately: chmod 600 file.
• Add HISTIGNORE='*doppler secrets set*' to your shell profile to prevent secrets from appearing in shell history.
• Use name transformers (--name-transformer) when frameworks expect specific variable naming conventions.
• For Kubernetes, prefer process substitution <(doppler secrets download ...) over writing files to disk.
• Use --no-file --format flags to pipe secret downloads directly to stdout without writing temporary files.
• Run doppler update periodically to keep the CLI current.