Secrets Setup Guide
Learn how to setup your project to access secrets for a specific config
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
-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.yamlfile. If you want to manage or view entries, you can use the
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_TOKENenvironment variable or the
--tokenflag (the project and config from a service token always takes precedence over other flags or anything previously setup via
- Use the project and config flags that were specified (flags always take precedence over anything that was previous setup via
- Use an exact match found in
- Use the next nearest match. For example, if you're currently in a directory named
~/dev/foo/barand 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
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.
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.
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 loginand then run
doppler setupfor all of your projects again. Typically, you'll only want to use this in a last-resort scenario.
Updated 6 months ago