Multiple Workplaces
Learn how to use the CLI across multiple workplaces
It's possible to be a member of multiple Workplaces in Doppler. You might have one for work, one for an open source project you're a contributor for, and another personal workplace for your own side projects. In some situations, your work may have several workplaces spread across different departments. In all of the scenarios, it's important that you're able to easily access your secrets via the CLI.
Understanding CLI Scopes
All Doppler CLI interactions have an inherent scope associated with them. That scope always defaults to the current directory you're in, but it can also be specified explicitly using the --scope
flag. This scope is used to determine which project, config, and access token should be used for the command. When you login initially, this creates a new configuration entry with a scope of /
that applies to all sub-directories on your filesystem. This means, after the initial doppler login
, all commands you run from any directory on your machine will use the configuration with the /
scope.
You can view the currently active configuration by using the doppler configure
command, which will print something like this:
~/dev
β― doppler configure
ββββββββββββββββββ¬ββββββββββββββββββββββββββββββββ¬ββββββββ
β NAME β VALUE β SCOPE β
ββββββββββββββββββΌββββββββββββββββββββββββββββββββΌββββββββ€
β api-host β https://api.doppler.com β / β
β dashboard-host β https://dashboard.doppler.com β / β
β token β dp.ct.8abcβ¦ASDFG β / β
ββββββββββββββββββ΄ββββββββββββββββββββββββββββββββ΄ββββββββ
When you use the doppler setup
command in a sub-directory, you expand this configuration with project and config entries for a specific scope, which allow you to omit the --project
and --config
flag when executing commands (because the global config knows them from the configuration for the scope you're in).
~/dev/example
β― doppler configure
ββββββββββββββββββ¬ββββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββ
β NAME β VALUE β SCOPE β
ββββββββββββββββββΌββββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββ€
β api-host β https://api.doppler.com β / β
β config β dev_personal β /Users/janedoe/dev/example β
β dashboard-host β https://dashboard.doppler.com β / β
β project β example β /Users/janedoe/dev/example β
β token β dp.ct.8abcβ¦ASDFG β / β
ββββββββββββββββββ΄ββββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββ
The above command was executed from the /Users/janedoe/dev/example
directory after having run doppler setup
(which configured the project to example
and the config to dev_personal
). As you can see above, the api-host
, dashboard-host
, and token
are all inherited from the /
scope. The project
and config
are picked up because we're currently in the right scope.
Running doppler configure
will always show you the scopes being applied at the location you're currently at. You can use the --all
to view all the Doppler configurations that exist. You can also run doppler configure reset
if you'd like to clear all those settings and start fresh as if you'd just installed the CLI.
Multiple CLI Logins
If you need interact with projects in more than one workplace, then this can be accommodated with additional CLI logins. The first doppler login
that occurs will set an access token for a particular workplace that's valid at /
, which will then apply across you're entire filesystem. You should always set this to the workplace you use the most. From there, the easiest way to organize your Doppler login scopes is to structure your development projects such that they're all stored inside containing directories that correlate with the Doppler workplace they're in.
dev
βββ opensource-workplace
βΒ Β βββ opensource-framework
βΒ Β βββ opensource-library
βββ personal-workplace
βΒ Β βββ framework-test
βΒ Β βββ side-project
βββ work-workplace
βββ backend
βββ frontend
βββ worker
Once you've structured your projects like this locally, you can perform additional CLI logins scoped to the workplace directory like this:
~/
β― doppler login --scope ~/dev/doppler/opensource-workplace/
? Open the authorization page in your browser? Yes
Complete authorization at https://dashboard.doppler.com/workplace/auth/cli
Your auth code is:
xxxxxxxx_xxxxxxxxx_xxxxxxxx_xxxxxxx
Waiting...
Welcome, Joel
When you go through browser login step, you can choose which workplace you'd like to login to β just choose the one you'd like associated with the scope you specify. After doing this, all sub-directories of the workplace directory will inherit the new scope you just setup.
~/dev/doppler/opensource-workplace
β― doppler configure
ββββββββββββββββββ¬ββββββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββ
β NAME β VALUE β SCOPE β
ββββββββββββββββββΌββββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββ-ββββββββββ€
β api-host β https://api.doppler.com β /Users/janedoe/dev/opensource-workplace β
β dashboard-host β https://dashboard.doppler.com β /Users/janedoe/dev/opensource-workplace β
β token β dp.ct.z5cvβ¦pAjf8 β /Users/janedoe/dev/opensource-workplace β
ββββββββββββββββββ΄ββββββββββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββ
You can double-check this by changing to a sub-directory and running doppler configure
. Notice that now the token
configuration setting has the scope for your workplace directory rather than your global /
scope. You can also run doppler me
or doppler projects
inside this workplace directory to verify which workplace is currently in scope. Now simply repeat this process for each workplace directory, choosing the appropriate Doppler workplace for each directory when going through the login process.
Now, so long as any project you create on-disk is under the appropriate workplace directory, your Doppler CLI will be scoped appropriately to access its secrets in that workplace.
Advanced CLI Scope Usage
This section assumes a bit more knowledge around using command line shells and scripting.
In some scenarios it might be beneficial to be able to switch between Doppler workplaces in the CLI on the fly without having to setup permanent scoping. A useful pattern for accomplishing this involves setting up some "scope" directories somewhere on your machine. For example, you might have some directories like this:
~/doppler/scopes/workplace-1
~/doppler/scopes/workplace-2
~/doppler/scopes/workplace-3
You would then login to the appropriate workplace at each of these locations like this:
doppler login --scope ~/doppler/scopes/workplace-1
doppler login --scope ~/doppler/scopes/workplace-2
doppler login --scope ~/doppler/scopes/workplace-3
Once those logins are setup, you'll want to add a new shell function to your shell profile. That function relies on a CLI tool called fzf
which is a command-line fuzzy finder, so you'll want to install that tool. Once you've installed that, you'll want to add a new function to you shell profile (typically in either your .bashrc
or .zshrc
file) that looks like this:
doppler-scope () {
perform_reset=$1
if [ "$perform_reset" = "reset" ]; then
unset D_SCOPE
unset DOPPLER_TOKEN
else
export D_SCOPE="$(find ~/doppler/scopes -maxdepth 2 | fzf)"
export DOPPLER_TOKEN=$(doppler --scope "$D_SCOPE" configure get token --plain)
fi
}
Once this has been added to your profile, then close your current shell and open a new one (to ensure the updated profile is loaded) and type doppler-scope
. You'll be presented with something that looks like this:
> /tmp/doppler/scopes/workplace-3
/tmp/doppler/scopes/workplace-2
/tmp/doppler/scopes/workplace-1
/tmp/doppler/scopes
4/4 ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
>
Simply start typing any unique string in one of your workplace names until it's the highlighted option and then hit enter. That will load the CLI token associated with that scope into the DOPPLER_TOKEN
environment variable, which the Doppler CLI will use for authentication. You can then use either doppler me
or doppler projects
to verify that the new workplace has been selected. When running doppler
commands using this method, you should explicitly pass in the project and config with the --project
/-p
and --config
/-c
flags.
After doing that, you can run that command again and choose a different scope if you'd like to switch or run doppler-scope reset
to unset the DOPPLER_TOKEN
environment variable so the CLI will switch back to the default scope specified for the directory you're in.
By default, when you use
doppler login
on MacOS or Windows, the CLI token that's received is stored in the OS keychain and when commands are run, it's fetched from that keychain directly. The above method is temporarily storing one of these CLI tokens in your shell environment. A CLI token is highly privileged (it has all permissions your Doppler user has), so if you use this method we recommend runningdoppler-scope reset
when you're done and/or closing the shell session you're using to prevent theDOPPLER_TOKEN
environment variable from persisting with that token value.
Updated 3 months ago