Skip to main content
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:
  1. Sign up for 1Password.
  2. Install 1Password CLI.
  3. Store the secrets you want to provision in your 1Password account.

​
Step 1: Get secret references

You can get secret references in several ways:

​
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.
  1. Export the necessary environment variables: 
    export GITHUB_TOKEN=op://development/GitHub/credentials/personal_token
  2. Run op run -- with your command for starting the app: 
    op run -- gh

​
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
AWS_ACCESS_KEY_ID="op://development/aws/Access Keys/access_key_id"
AWS_SECRET_ACCESS_KEY="op://development/aws/Access Keys/secret_access_key"
To use environment files with op run, specify the path to the environment file with the flag --env-file: 
op run --env-file="./prod.env" -- aws
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 ": 
    MY_VAR = "this is on the first line
and this is on the second line"
  • Empty lines are skipped.
  • Lines beginning with # are treated as comments. Comments can also be placed inline after KEY=VALUE statements.
  • Empty values become empty strings. For example, EMPTY= will set the environment variable EMPTY 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" and KEY='VALUE' both evaluate to KEY and VALUE.
  • 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: 
    SOME_VAR = value
OTHER_VAR = ${SOME_VAR}
  • 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 to JSON and {"foo":"bar"}.
  • Variables do not get replaced in values that are enclosed in single quotes. So KEY='$SOME_VAR' evaluates to KEY and $SOME_VAR.
  • Template syntax can be used in the VALUE to inject secrets. The KEY 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 and VALUE segments are ignored, so KEY = VALUE is parsed the same as KEY=VALUE.
  • Single and double quoted values maintain both leading and trailing whitespace, so KEY=" some value " evaluates to KEY and  some value .
  • These files should use UTF-8 character encoding.

​
Expand variables in a subshell

When you reference a variable like $MY_VAR in the same command where you call op run, your shell expands $MY_VAR before op run can substitute the secret reference. For example, a command like the following will not resolve the secret from 1Password: 
MY_VAR=op://vault/item/field op run --no-masking -- echo "$MY_VAR"
To make sure op run substitutes the secret before the variable expands, run the command to expand the variable in a subshell:

​
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
MYSQL_DATABASE = "op://$APP_ENV/mysql/database"
MYSQL_USERNAME = "op://$APP_ENV/mysql/username"
MYSQL_PASSWORD = "op://$APP_ENV/mysql/password"
To use the set of secrets from the dev vault to deploy an app in the development environment: 
APP_ENV=dev op run --env-file="./app.env" -- myapp deploy

​
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.

​
Learn more