Secrets Setup Guide

The Doppler CLI determines which secrets to fetch when executes either based on a configuration you set from your project's directory or by the flags you pass in at the time of execution.

Setting up your Project

The most common way to configure your project is by running doppler setup in its directory. This will walk you through some prompts where you can choose which Doppler Project and Config to associate with that directory. You can get more information about this process from our Install CLI guide.

Specifying Project & Config with Flags

If you'd prefer not to go through an interactive doppler setup process, the --project (-p) and --config (-c) flags exist to specify which project and config to use. For example:

doppler run -p YOUR_PROJECT -c YOUR_CONFIG -- YOUR_COMMAND

Under the Hood

It can be helpful to understand what's going on under the hood when it comes to how Doppler handles project setup. Unlike other tools, Doppler doesn't rely on local files in the project to determine which project and config to use. Instead, it performs a lookup in your ~/.doppler/.doppler.yaml file based on the directory you're currently in. That file contains entries with a scope (the directory path) and the project and config that scope should use.

📘
You should never need to manually edit the ~/.doppler/.doppler.yaml file. If you want to manage or view entries, you can use the doppler configure command.

When performing the project and config lookup, it follows this precedence:

Use the project and config associated with the specified service token – either passed in via the DOPPLER_TOKEN environment variable or the --token flag (the project and config from a service token always takes precedence over other flags or anything previously setup via doppler setup).
Use the project and config flags that were specified (flags always take precedence over anything that was previous setup via doppler setup).
Use an exact match found in ~/.doppler/.doppler.yaml.
Use the next nearest match. For example, if you're currently in a directory named ~/dev/foo/bar and no entry exists for that directory, it will then look for an entry at ~/dev/foo. If one exists, it'll use that. If not, it'll move up another directory and look again. This will continue until it either finds a matching scope it can use or the process fails because no project or config were specified.

🚧
Due to how the CLI performs lookups, it's important to know that if you move a project directory, it will lose its Doppler configuration and you'll need to perform another doppler setup. This is because the action of moving a directory doesn't update the ~/.doppler/.doppler.yaml file.
Another side effect of this is that if you do that and don't remove the old entry, then creating a new directory at the old location will receive the previous directory's configuration.

Troubleshooting

In some situations, you may end up with Doppler configuration settings that result in different secrets than you expect being used (e.g., you performed a doppler setup in a subdirectory, but forgot you did that). To see what settings are currently being applied to the directory you're in, you can run this:

doppler configure --scope $(pwd)

If no project or config are listed, then it's using the base configuration and that means no setup has been performed and either a doppler setup needs to be run or the project and config need to be passed in via flag or service token.

If they are listed, the scope column will tell you where the project and config are being inherited from.

Cleanup

If you find that you want to delete a specific entry, you can accomplish this by running the following command:

doppler configure unset project config --scope /path/to/directory

If you ever want to completely clear all settings, you can accomplish this by running the following command:

doppler configure reset

🚧
This will remove all entries from ~/.doppler/.doppler.yaml, which means you'll need to run doppler login and then run doppler setup for all of your projects again. Typically, you'll only want to use this in a last-resort scenario.