Load secrets into the environment

With op run, you can provide your project secrets directly from 1Password to an application or script as environment variables at runtime. You can use op run with 1Password Environments, environment variables set to secret references, or a combination of both.

1Password CLI loads the specified secrets, then runs the provided command in a subprocess with the secrets made available as environment variables only for the duration of the process. This allows you to avoid hardcoding any plaintext secrets and quickly switch between different sets of secrets for different development contexts.

Choose your configuration

1Password CLI provides multiple methods to load your project secrets:

• 1Password Environments (beta) allow you to create Environments in 1Password that contain all your environment variables for a specific workflow. You can share Environments with your team and create separate Environments for each project, application, or development context (like staging or production).

• Secret references are URIs that point to where a secret is stored in your 1Password account. A secret reference uses the names or unique identifiers of the vault, item, section, and field where the secret is stored in 1Password. You can set environment variables to secret references on the command line or use secret references in your .env files. Secret references require more manual setup than 1Password Environments to switch between different sets of environment variables for different contexts, or create shared team workflows.

• Hybrid approach: You can use op run to load variables from a 1Password Environment alongside secret references from .env files or exported environment variables.

tip

Authenticate with a 1Password Service Account to follow the principle of least privilege. You can scope service account access to specific vaults and 1Password Environments so that processes in your authorized terminal session can only access secrets required for a given purpose.

caution

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

1Password Environment (beta)

1. Sign up for 1Password.
2. Install the latest beta build of 1Password CLI, version 2.33.0-beta.02 or later.

Secret references

Before you can load secrets into the environment, you'll need to:

1. Sign up for 1Password.
2. Install 1Password CLI.

Step 1: Store your project secrets in 1Password

1Password Environment (beta)

To store your project secrets in a 1Password Environment, follow the steps to create an Environment, then import a .env file or manually add your environment variables.

Secret references

To use secret references, save your project secrets as items in a vault in your 1Password account.

Then follow the instructions to create secret references for each item using your preferred method:

• With the 1Password desktop app: Copy secret references from the app.
• With 1Password for VSCode: Insert secret references from 1Password as you edit code.
• With 1Password CLI: Get secret references for one or multiple fields with op item get.
• Use the secret reference syntax rules to write secret references manually.

Step 2: Pass the secrets to the application

1Password Environment (beta)

To pass your environment variables from 1Password to an application or script:

1. Open the 1Password app and navigate to Developer > Environments.

2. Select the Environment where your project secrets are stored, then select Manage environment > Copy environment ID.

3. Use op run -- with the command for starting the application or script. 1Password will run the provided command in a subprocess with the secrets made available as environment variables for the duration of the process.

   For example:

Secret references

Step 1: Map secret references to environment variables

To pass secrets to an application or script using op run and secret references, you must first map the secret references to the appropriate environment variables. To do this, you can set environment variables to secret references using an environment file or export them on the command line.

Environment file

Environment (.env) files allow you to define multiple environment variables as secret references with KEY=VALUE statements separated by a newline.

To use an environment file with op run, add key-value pairs for each of your project secrets with the value set to a secret reference. For example:

prod.env

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 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:

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

Optional: Differentiate between environments

tip

If you need to pass secrets for multiple environments, we recommend using 1Password Environments instead of secret references. 1Password Environments allow you to more easily organize, share, and pass environment variables for multiple contexts.

If you have different sets of secrets for different environments, like staging and production, you can check a single environment file into source control and include a variable within the secret references to represent the context. You can then set the variable to the appropriate context when you pass the file to op run.

To use this approach, you must organize your project secrets in 1Password into different vaults for each environment, with each item's fields structured in the same way. 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 reference in your environment file.

For example, in the following environment file, $APP_ENV is the externally set environment variable. It can be set to dev or prod to load secrets from either the dev vault or the prod vault in 1Password.

app.env

Command line

You can individually export environment variables as secret references from the command line.

For example, to set the variable GITHUB_TOKEN to a secret reference URI that points to the personal_token field within a credentials section in a GitHub item:

Bash, Zsh, sh

fish

PowerShell

Step 2: Pass the resolved secret references to the application

Environment file

To use an environment file with op run, specify the path to the environment file using the --env-file flag:

If you structured your environment file to load secrets for multiple environments, make sure to also set the variable for the vault (in the example below, APP_ENV).

For example, to pass secrets from the dev vault to an application running in the development environment:

Bash, Zsh, sh, fish

PowerShell

1. Set the $APP_ENV variable:

2. Run op run with the environment file:

Command line

If you exported environment variables as secret references on the command line, use op run -- with the command to start the application or script. 1Password will run the provided command in a subprocess with the secrets made available as environment variables for the duration of the process.

For example:

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 pass the secret reference URI instead of the secret value from 1Password:

To make sure op run substitutes the secret before the variable expands, run the command to expand the variable in a subshell:

See result...

Use both methods together

You can load environment variables from an Environment in combination with secret references from a .env file or flag. For example:

Next step: Run in production

Now that the application works locally, choose how to load your secrets in production or CI/CD:

• 1Password Service Account: Automate access with a service account token. Service accounts support both secret references and 1Password Environments.
• 1Password Connect Server: Best for self-hosting within your own infrastructure. Connect only supports secret references and does not currently support 1Password Environments.

Learn more

• Use 1Password Service Accounts with 1Password CLI
• Use 1Password Connect Server with 1Password CLI
• Load secrets into config files
• Secret reference syntax
• Template syntax