Load secrets into the environment
With 1Password CLI, you can provision secret references as environment variables to simplify the process of creating multiple configurations for different environments. Secret references allow you to edit your secrets in 1Password without having to make any changes to your configuration settings or put any plaintext secrets in code.
After you've set your environment variables to secret references, you can use op run
to provision an app with the secrets it requires.
Many applications that follow the popular 12-Factor App guidelines source their secrets from the environment.
We recommend using 1Password Service Accounts to follow the principle of least privilege. Service accounts support restricting 1Password CLI to specific vaults, so that processes in your authorized terminal session can only access items required for a given purpose.
You should assume that processes on your computer can access the environment of other processes run by the same user. Be aware of this when supplying secrets through environment variables.
Requirements
Before you can load secrets into the environment, you'll need to:
- Sign up for 1Password.
- Install 1Password CLI.
- Store the secrets you want to provision in your 1Password account.
Step 1: Copy secret references
- Open and unlock the 1Password desktop app.
- Open the item where the secret you want to reference is stored.
- Click next to the field that contains the secret you want to reference, then click Copy Secret Reference.
If a field doesn't have the Copy Secret Reference option, you can use the secret reference syntax to write your own.
Step 2: Pass the secrets to the application
To provision an app with the secrets it needs, map the secret references to the appropriate environment variables, then use op run
to pass the secrets to the application.
There are two ways to do this:
Export environment variables
You can individually export environment variables as secret references from the command line.
Export the necessary environment variables:
- Bash, Zsh, sh
- fish
- PowerShell
Run
op run --
with your command for starting the app:
Use environment (.env
) files
Environment files allow you to define multiple (secret) environment variables with KEY=VALUE
statements separated by a newline. These files have the .env
extension.
You can check environment files into source control and use the same environment everywhere. For example, if you use environment files for your test secrets, you can run your tests both locally and in CI without having to provision the secrets separately.
prod.env
To use environment files with op run
, specify the path to the environment file with the flag --env-file
:
Environment file syntax rules
The .env
file parsing engine follows the following rules:
Environment variables are defined as
KEY=VALUE
statements separated by a newline.Variables can span multiple lines if they are enclosed in either
'
or"
:Empty lines are skipped.
Lines beginning with
#
are treated as comments. Comments can also be placed inline afterKEY=VALUE
statements.Empty values become empty strings. For example,
EMPTY=
will set the environment variableEMPTY
to the empty string.If a value is surrounded by single or double quotes, these quotes do not end up in the evaluated value. So
KEY="VALUE"
andKEY='VALUE'
both evaluate toKEY
andVALUE
.Occurrences of
$VAR_NAME
or${VAR_NAME}
are replaced with their respective value from the environment.A variable defined in a .env file can be referred to later in the same file:
Special characters can be escaped with
\
. For example,MY_VAR = "\$SOME_VAR that is not actually replaced."
results in the following value for MY_VAR:$SOME_VAR that is not actually replaced.
.Inner quotes are maintained, so
JSON={"foo":"bar"}
evaluates toJSON
and{"foo":"bar"}
.Variables do not get replaced in values that are enclosed in single quotes. So
KEY='$SOME_VAR'
evaluates toKEY
and$SOME_VAR
.Template syntax can be used in the
VALUE
to inject secrets. TheKEY
can only contain template variables.Template parsing is performed after
.env
file parsing, so you cannot use the former to construct the latter.Leading and trailing whitespace of both
KEY
andVALUE
segments are ignored, soKEY = VALUE
is parsed the same asKEY=VALUE
.Single and double quoted values maintain both leading and trailing whitespace, so
KEY=" some value "
evaluates toKEY
andsome value
.These files should use UTF-8 character encoding.
Step 3: Differentiate between environments
If you have different sets of secrets for different environments, you can use a single environment file to pass the appropriate secrets to the application.
To do this, make sure you structure your 1Password secrets in the same way across all your environments. For example: dev/mysql/password
and prod/mysql/password
.
Then, include an externally set variable ($VARIABLE_NAME
) in place of the vault name for each secret in your environment file. This will allow you to specify which set of secrets you use with each environment.
For example, in the following .env
file, $APP_ENV
is the externally set environment variable:
app.env
To use the set of secrets from the dev
vault to deploy an app in the development environment:
- Bash, Zsh, sh, fish
- PowerShell
Set the
$APP_ENV
variable:Run
op run
with the environment file:
Next step: Run in production
Now that the application works with the right configuration locally, you can use 1Password CLI with a 1Password Connect Server to provision secrets in production environments. You can also set up 1Password CLI in CI, and define your secret references alongside other configurations.