Doppler

---
name: doppler
description: >-
  Manage secrets and environment variables using the Doppler CLI. Use when the
  user wants to set up Doppler, inject secrets into processes, manage projects
  and configs, upload or download secrets, create service tokens, use secret
  templates, or integrate Doppler with Docker, Kubernetes, or CI/CD pipelines.
  Trigger words: doppler, secrets manager, env vars, secret injection, doppler run,
  doppler setup, service token, secret rotation.
license: Apache-2.0
compatibility: "Requires Doppler CLI installed (brew, apt, yum, scoop, or shell installer)"
metadata:
  author: terminal-skills
  version: "1.0.0"
  category: devops
  tags: ["doppler", "secrets", "environment-variables", "devops", "security"]
---

# 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

```bash
# 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:

```bash
doppler login
doppler me
```

### 2. Set up a project directory

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

```bash
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:

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

Override the project/config per command:

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

Run multiple chained commands:

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

### 4. Read and manage secrets

List all secrets:

```bash
doppler secrets
doppler secrets --only-names
```

Get a single secret value:

```bash
doppler secrets get DATABASE_URL --plain
```

Get multiple secrets as JSON:

```bash
doppler secrets get DATABASE_URL REDIS_URL API_KEY --json
```

### 5. Set and update secrets

```bash
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:

```bash
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:

```bash
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):

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

Limit file reads for extra security:

```bash
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:

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

Pipe directly to kubectl:

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

### 9. Create service tokens for CI/CD

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

Use in CI via env var or inline flag:

```bash
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:

```bash
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:

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

Create a Kubernetes secret:

```bash
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:**
```bash
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:**
```bash
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:
```bash
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.