Guides
GuidesAPISupportStatusCommunitySign Up

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 running doppler-scope reset when you're done and/or closing the shell session you're using to prevent the DOPPLER_TOKEN environment variable from persisting with that token value.

Updated 3 months ago