Doppler Secrets Management

Triggers

Quick Start

Install CLI

# macOS
brew install gnupg && brew install dopplerhq/cli/doppler

# Linux (Debian/Ubuntu)
apt-get update && apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -sLf --retry 3 --tlsv1.2 --proto "=https" \
  'https://packages.doppler.com/public/cli/gpg.DE2A7741A397C129.key' | \
  gpg --dearmor -o /usr/share/keyrings/doppler-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/doppler-archive-keyring.gpg] https://packages.doppler.com/public/cli/deb/debian any-version main" | \
  tee /etc/apt/sources.list.d/doppler-cli.list
apt-get update && apt-get install doppler

# Shell script (any OS)
curl -sLf --retry 3 --tlsv1.2 --proto "=https" https://get.doppler.com | sh

Authenticate & Setup

# Login (opens browser for auth)
doppler login

# Setup project in current directory (interactive)
doppler setup

# Non-interactive setup
doppler setup --project my-app --config dev --no-interactive

Common Tasks by Intent

doppler secrets -p <project> -c <config>

doppler secrets get SECRET_NAME -p <project> -c <config>

doppler secrets set KEY=value -p <project> -c <config>

doppler secrets set KEY1=val1 KEY2=val2

doppler secrets delete SECRET_NAME

doppler run -- your-command --flags

doppler run -p backend -c dev -- npm start

doppler secrets download --format env --no-file

doppler projects

doppler configs -p <project>

doppler environments -p <project>

doppler configs clone -p <project> -c <source> --name <new>

doppler activity

doppler configure debug

doppler open

doppler me

Secrets Injection Patterns

Environment Variable Injection

# Inject secrets as env vars for any command
doppler run -- node server.js
doppler run -- docker compose up
doppler run -- terraform apply

# Run a shell command string
doppler run --command "echo $DATABASE_URL && npm start"

# Only inject specific secrets
doppler run --only-secrets DATABASE_URL,API_KEY -- node server.js

Mount Secrets to File

# Mount as JSON file (ephemeral, cleaned up after process exits)
doppler run --mount secrets.json -- cat secrets.json

# Mount as .env file
doppler run --mount .env --mount-format env -- your-command

# Mount with template
doppler run --mount config.yaml --mount-template template.yaml -- your-command

Template Substitution

# Substitute secrets into a template file
doppler secrets substitute template.env.tpl > .env

Fallback for Offline/Resilience

# Run with fallback file (writes encrypted secrets on success, reads on failure)
doppler run --fallback ./fallback.encrypted -- npm start

# Read-only fallback (never update the fallback file)
doppler run --fallback ./fallback.encrypted --fallback-readonly -- npm start

# Offline mode (read directly from fallback, no API contact)
doppler run --fallback-only --fallback ./fallback.encrypted -- npm start

Project & Config Hierarchy

Workplace
 └── Project (e.g. "backend", "frontend")
      └── Environment (e.g. "development", "staging", "production")
           └── Config (e.g. "dev", "stg", "prd")
                └── Branch Config (e.g. "dev_feature-x")

Config Inheritance

• Root configs (dev, stg, prd) inherit from their environment
• Branch configs inherit from their parent config
• Overrides cascade: Environment → Config → Branch Config
• Personal configs allow individual developer overrides without affecting the team

Integration Syncs

Service Tokens

# Generate a service token via dashboard or API
# Use in CI/CD:
DOPPLER_TOKEN=dp.st.xxx doppler run -- your-command

# Or set as environment variable
export DOPPLER_TOKEN=dp.st.xxx
doppler secrets

Security Best Practices

• Never commit secrets to version control — use Doppler as the single source of truth
• Use service tokens in production (read-only, config-scoped)
• Use personal configs for local development overrides
• Enable change requests for production configs (requires approval before changes)
• Rotate secrets regularly — use Doppler's rotation reminders
• Use OIDC authentication where possible for short-lived tokens
• Audit access via

  doppler activity

  and dashboard audit logs
• Use branch configs to isolate feature branch secrets
• Never use

  --no-verify-tls

  in production

Reference Documents

Troubleshooting

Authentication Issues

1. Run

   doppler me

   to check current auth status
2. Run

   doppler configure debug

   to see active configuration
3. Re-authenticate with

   doppler login

4. Check scope:

   doppler configure get token --scope /path/to/project

Wrong Secrets Loaded

1. Check which project/config is active:

   doppler configure debug

2. Verify scope:

   doppler setup

   in the project directory
3. Use explicit flags:

   doppler secrets -p project -c config

4. Check for environment variable overrides:

   doppler run --preserve-env=false

Fallback File Issues

1. Ensure fallback path is writable
2. Check passphrase hasn't changed (config-dependent by default)
3. Use

   doppler run clean

   to remove old fallback files
4. Regenerate with a fresh

   doppler run --fallback ./path -- echo ok

Service Token Not Working

1. Verify token is for the correct project and config
2. Service tokens are read-only — cannot set/delete secrets
3. Check token hasn't been revoked in the dashboard
4. Ensure

   DOPPLER_TOKEN

   env var is set correctly

Workflow

1. Identify the task: Setup, secret management, injection, integration, or debugging
2. Check prerequisites: Is

   doppler

   CLI installed? Is user authenticated?
3. Determine scope: Which project and config are we working with?
4. Consult references: Use reference docs for detailed CLI flags and integration patterns
5. Security first: Never output secret values in logs; use

   --only-names

   for listing