# Doppler > Store, read, and wire up env-style secrets in Doppler — resolve the real project/config, emit copy-ready command templates, and keep plaintext values out of the transcript. TRIGGER when: a task touches secrets, API keys, tokens, passwords, or `.env` files; before suggesting where a key should live, handing the user a command that carries a secret value, or running any `doppler` command; or the user has a secret on their clipboard. DO NOT TRIGGER when: the secret is a whole document to commit encrypted (use `/transcrypt`), or the project already uses a different secret manager (Vault, a cloud secret manager) — respect it. - Skill: `anothersava/doppler` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add anothersava/doppler` - Raw SKILL.md: https://api.skillmd.com/api/skills/anothersava/doppler/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: AnotherSava (https://skillmd.com/u/anothersava) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/anothersava/doppler --- # Doppler (env-style secrets) Doppler is the default store for every env-style secret — API keys, tokens, passwords, connection strings — in place of a plaintext `.env`. One source of truth, synced across the user's Windows and macOS machines, with nothing secret committed. The account's workplace is `sava`. ## Context - Doppler CLI: !`command -v doppler >/dev/null 2>&1 && echo INSTALLED || echo MISSING` - Existing projects: !`doppler projects --json 2>&1 | tr ',' '\n' | grep -o '"name":"[^"]*"' || echo UNAVAILABLE` - Configs in this repo's project: !`doppler configs --json 2>&1 | tr ',' '\n' | grep -o '"name":"[^"]*"' || echo "UNBOUND — list with doppler configs -p "` - This repo's doppler.yaml: !`test -f doppler.yaml && cat doppler.yaml || echo NONE` - This directory's binding: !`doppler configure get project --plain 2>/dev/null | grep . || echo UNBOUND` ## 1. Resolve project and config — never guess them Read the coordinates off **Existing projects** and **Configs in this repo's project** (Context) — a coordinate is a project *and* a config, and under the shard rule the config carries the app's identity: - The workplace name `sava` is **not** a project. Never `-p sava`. - Doppler's sample project `example-project` is not one of the user's. Never write to it. - **A new app gets a config, not a project.** The workplace is capped at **10 projects**, all ten are in use, and `doppler projects create` now fails with `Your workplace has reached its limit of 10 projects`. Apps share a project — a *shard*, chosen by trust boundary — and take one config each: `dev_` and `prd_`. Reach for `prd_` only when the task is genuinely production-facing, and say out loud that you did. - **`dev`, `stg` and `prd` are root configs, and they stay permanently empty.** A branch config inherits its root's secrets *including values*, so anything left in `local/prd` is readable by every app sharing that environment, and a `-c prd` typed where `-c prd_` was meant writes into the root and silently propagates that value to every co-resident app. Always name the full config. - The nine projects that predate the shard rule — `claude-code-dashboard`, `greenmur`, `landlord`, `printlab`, `scheduler`, `tools`, `travel-map`, `trips`, `whats-next` — keep their existing `dev`/`prd` layout; live systems read those values and migrating them would be risk for no benefit. The shard rule governs new apps, and apps that move for some other reason. - Two stores, and they don't mix: - **The app's own config inside a shard project** — `dev_` / `prd_`, the app name kebab-case after the env-slug prefix — secrets the app consumes at runtime. Shards are divided by trust boundary, by where the secret is materialized. `local` (workstation-only apps) is the only shard so far, because every app on the shared box predates the shard rule and keeps its own project — so **a new box-hosted app has no shard to join yet**. Creating one spends a project slot; raise it with the user rather than picking a home for it. - **`tools` / `prd`** — credentials *Claude* uses ad hoc across projects (Porkbun, Resend, Tailscale, Backblaze, `TRANSCRYPT_KEY`). The inventory lives in the `refs-private` memory. Read from it when a task needs a third-party credential; never copy one into an app's own config. - If the repo has no config yet, see `references/project-setup.md` — it covers picking the shard and creating the branch config. Do not run `doppler projects create`; the cap is reached. When **Existing projects** reads `UNAVAILABLE`, run `doppler projects` directly. An auth error there means the user must run `doppler login` themselves in a real terminal — it is interactive, needs a TTY, and fails under Claude Code's `!` prefix with "Incorrect function". If **Doppler CLI** is `MISSING`, see `references/project-setup.md` for the per-OS install. ## 2. Always emit the command, never just describe it Whenever you ask for, suggest, or explain storing a key, output the exact command in a fenced code block — never prose alone, and never a blockquote (the terminal renders its `|` gutter into the paste and corrupts it). Fill in every part you already know (the key name, `-p`, `-c`); mark only what the user must supply with a `{{kebab-case-hint}}` placeholder, never a plausible-looking fake value. The templates below write `-c `. Substitute the app's own config — `dev_` / `prd_` in a shard, or the legacy `dev` / `prd` in one of the nine pre-shard projects. Never leave a bare `dev`, `stg` or `prd` in a shard command: those are root configs, every branch config inherits their values, and the write is visible to every co-resident app. Pick the template by who holds the value. ### Store a value only the user has A dashboard-generated API key, a password they chose. There are two routes, and **both get offered, every time** — never the template on its own. **Lead with the clipboard, which Claude runs:** "copy the value and I'll pipe it into Doppler straight from your clipboard — it never reaches the transcript." It costs the user a `Ctrl+C` instead of a second terminal, and no plaintext ever occupies a command line. The command is in the next section. **When they would rather do it themselves**, hand them: ``` doppler secrets set ="{{the-value}}" -p -c --silent ``` Tell them to run it **in a terminal outside Claude Code** — not via the `!` prefix, which records the full command text, secret included, in the session transcript. The `--silent` flag suppresses the command's *output*, not a `!`-recorded input. Doppler's dashboard is an equally good alternative. Always quote the value. An unquoted `&`, `$`, `!`, backtick, or space is eaten by the shell and silently stores nothing, a truncation, or an empty string. Double quotes cover `& % ( )` and spaces; switch to single quotes when the value may contain `$`, a backtick, `!`, or `"`. ### Store a value from the clipboard Claude runs this. The value travels clipboard → pipe → Doppler, so it appears in no command line, no transcript, and no shell history — the file route's guarantee, minus the file. Read the clipboard with the platform's native reader: | OS | Reader | |---|---| | Windows (Git Bash) | `cat /dev/clipboard` | | macOS | `pbpaste` | | Linux | `wl-paste -n` (Wayland) or `xclip -selection clipboard -o` (X11) | Guard the write and pipe it in one command, which prints a length and nothing else: ```bash V=$(cat /dev/clipboard | tr -d '\r') case "$V" in "") echo "clipboard is empty — nothing stored" ;; {{expected-prefix}}*) printf '%s' "$V" | doppler secrets set -p -c --silent && echo "stored — ${#V} chars" ;; *) echo "clipboard does not look like (${#V} chars) — nothing stored" ;; esac unset V ``` **Never look at the clipboard to check it.** A bare `cat /dev/clipboard` puts the secret straight into the transcript, which is the whole leak this route exists to avoid. The clipboard may flow only into a pipe or into a variable that is never printed; everything you report is derived from it — a length, a line count, a prefix match — never the value. The guard is what stops the wrong clipboard (a password, a URL, yesterday's token) from reaching Doppler, where a delete does not erase it from version history. Merge the last two arms when the key has no recognizable prefix, but keep the empty check either way: an empty clipboard otherwise stores an empty string with no error at all, and the app fails much later with a blank credential. Two Windows traps that the `tr` and the choice of reader exist to dodge: - The `$( )` wrapper strips a trailing `\n` but not a trailing `\r`, and anything copied out of a Windows app arrives CRLF-terminated — so without `tr -d '\r'` the stored secret carries an invisible trailing carriage return. Stripping also normalizes inner CRLF to LF, which is what a multi-line value such as a PEM key wants. - Never read the clipboard through PowerShell. Piping `Get-Clipboard` appends a CRLF of its own *and* transliterates non-ASCII through the console codepage — `é` arrives as `e`. Git Bash's `/dev/clipboard` is byte-exact UTF-8. ### Store a value already on disk, or one you generated Claude runs this. Pipe it, so the plaintext never reaches the command line, the transcript, or shell history — Doppler documents stdin as its own recommended method: ``` printf '%s' "$(cat )" | doppler secrets set -p -c --silent ``` The `$( )` wrapper strips the trailing newline a file almost always carries; a bare `< file` redirect would store that newline as part of the value. To confirm the round trip without printing anything, use the digest check in `references/project-setup.md`. ### Import an existing `.env` ``` doppler secrets upload .env -p -c ``` Then delete the `.env` and confirm `.gitignore` covers it. Full wiring in `references/project-setup.md`. ### Reuse one value across configs (secret reference) When the same value belongs in more than one config (or project), store it **once** and point the others at it — one source of truth, no drift, editing the origin propagates. One config holds the real secret; the others hold a `${...}` reference Doppler resolves on read. **Which config holds the real value: the production one** — `prd_` in a shard, `prd` in one of the nine pre-shard projects. Production is the source of truth; the dev config holds a `${prd_.}` reference. A value that already lives in the dev config and is later needed in production gets **moved**, not copied — write it to the production config, then replace the dev value with a reference. Copying leaves two originals free to drift, and the one you'd edit by habit is the wrong one. (This is only for values that are genuinely the same everywhere — third-party API keys. Anything that must differ per environment, above all `SESSION_SECRET` and any admin password, gets its own value in each config and is never referenced across: a shared session secret makes a dev-minted cookie valid in production.) Migrating one key, without the value touching a command line: ```bash printf '%s' "$(doppler secrets get -p -c --plain)" | doppler secrets set -p -c --silent doppler secrets set '${.}' -p -c --silent ``` Verify by digest at each step rather than trusting the round trip — compare a hash prefix and a length before and after, so a truncated or empty write can't pass as success. Syntax, inside the value: - Same project, another config: `${.}` — e.g. `${prd_.GOOGLE_MAPS_EMBED_API_KEY}` in a shard, `${prd.GOOGLE_MAPS_EMBED_API_KEY}` in a pre-shard project. - Another project: `${..}`. **Single-quote** the value so the shell doesn't expand `${...}` to empty: ``` doppler secrets set ='${.}' -p -c --silent ``` `doppler secrets get` / `doppler run` return the **resolved** value, so the consuming app is unchanged (whoever fetches the referencing config must also have access to the referenced one). Confirm it resolved without printing it — a literal `${...}` back means it did not: ``` V="$(doppler secrets get -p -c --plain)"; case "$V" in '${'*) echo UNRESOLVED;; *) echo "resolved (len ${#V})";; esac; unset V ``` To share a *whole* config rather than one value, Doppler's named **Config Inheritance** does it in one step, but it's Team/Enterprise-only — a per-value reference works without it. Root-to-branch inheritance is *not* that feature and is always on: every branch config already inherits its root's secrets **and their values** on every plan, which is why roots are kept empty rather than used to share. ### Run something with the secrets injected ``` doppler run -p -c -- ``` This is the normal consumption path — the app reads `process.env` / `os.environ` and never sees a file. Drop `-p`/`-c` only when **This repo's doppler.yaml** (Context) shows a `setup:` block *and* **This directory's binding** is not `UNBOUND`. When the binding is `UNBOUND`, bind it once with `doppler setup --no-interactive` rather than carrying explicit flags forever — a committed `doppler.yaml` on its own does not bind anything. ### Check a value without printing it Auto-mode's safety classifier blocks echoing a secret to stdout ("Credential Materialization"), and it is right to. Derive a non-secret answer instead — the command prints only a boolean: ``` doppler run -p -c -- node -e 'console.log((process.env.||"").startsWith("{{expected-prefix}}"))' ``` To see which keys exist, with no values at all: `doppler secrets --only-names -p -c `. ### Materialize a raw value Only when a command genuinely needs the value as an argument — and then pipe it straight into the consumer rather than echoing it: ``` doppler secrets get -p -c --plain ``` The `--visibility masked` flag does **not** redact CLI output: at set time the confirmation table still prints the plaintext, and later reads still return it in the clear to an authorized CLI user. Masked is a dashboard access attribute. Use `--silent` for no echo; combine both for no echo *and* a dashboard-masked secret. ### Put a stored value on the clipboard — and leave a `cb` behind The mirror image of the clipboard write, for when the user has to paste a secret into a web form or a vendor dashboard. It reaches their clipboard without passing through the transcript. Use the helper rather than redirecting by hand: it picks the right sink per OS and reports a label, a length and a digest instead of the value. ``` V=$(doppler secrets get -p -c --plain) bash ~/.claude/skills/doppler/scripts/to-clipboard.sh "" "$V" ``` **Then write `scripts/cb.sh`, every single time.** A clipboard does not survive a session: the user comes back to paste hours later, having copied three other things since, and the value is gone — which has already cost a round trip. `cb` is the fix, the same shape as `deploy` and `publish`: ```bash #!/bin/bash # Re-copy the value Claude last put on the clipboard. Run it as `cb`, from anywhere in this repo. # # Regenerated on every copy, so it always carries the most recent one — per-machine, gitignored, never committed. # The value is fetched rather than stored here: a secret must not sit in plaintext on disk, and re-reading its # source also means this keeps working after the secret is rotated. # # WHAT: set -euo pipefail value=$(doppler secrets get -p -c --plain) bash ~/.claude/skills/doppler/scripts/to-clipboard.sh "