Skip to main content

Use secret references with 1Password CLI

With 1Password CLI, you can use secret references to securely load information saved in 1Password into environment variables, configuration files, and scripts without exposing any secrets in plaintext.

A secret reference URI includes the names (or unique identifiers) of the vault, item, section, and field where a secret is stored in your 1Password account:

To replace secret references with the secrets they refer to at runtime, use op read, op run, or op inject.

tip

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.

Requirements​

Before you can use secret references to securely load your secrets with 1Password CLI, you'll need to:

  1. Sign up for 1Password.
  2. Install 1Password CLI.
  3. Save the secrets you want to reference in your 1Password account.

Step 1: Get secret references​

You can get secret references in several ways:

Step 2: Replace plaintext secrets with secret references​

After you create secret references, use them in place of plaintext secrets in your code.

The example below shows a GitHub environment file with a secret reference pointing to where the GitHub Personal Access Token is stored in 1Password rather than a plaintext token.

An environment file using a plaintext secret and the same file using a secret reference.An environment file using a plaintext secret and the same file using a secret reference.

Step 3: Resolve secret references​

There are three ways you can replace secret references with the actual secrets they reference at runtime:

With op read​

You can use op read with a secret reference to print the secret to stdout.

See result...

To write the secret to a file instead of stdout, include the --out-file flag (or -o) with the path to the new file. For example, to create a file token.txt that contains the GitHub personal access token:

token.txt

You can also use op read with secret references to load secrets into scripts. For example, to use secret references in place of your Docker username and password with the docker login command:

myscript.sh

Query parameters​

You can use secret references with query parameters to get more information about an item.

To get information about item fields or file attachments, include the attribute (or attr) query parameter with the attribute you want to get.

You can query the following attributes for fields: type, value, title, id, purpose, otp

And the following attributes for file attachments: content, size, id, name, type.

For example, to retrieve a one-time password from the one-time password field on a GitHub item:

See result...

To get an SSH key's private key in the OpenSSH format, include the ssh-format query parameter with the value openssh on a secret reference for the SSH key's private key field.

See result...
Next step

Learn more about securely loading secrets into scripts.

With op run​

You can set environment variables to secret references, then use op run to pass secrets to an application or script at runtime.

op run scans environment variables for secret references, loads the corresponding values from 1Password, then runs the provided command in a subprocess with the secrets made available as environment variables for the duration of the subprocess.

Pass the secrets to an application or script​

To pass secrets to your script or application at runtime, wrap the command with op run.

For example, here's a Node.js app that needs credentials to connect to a database:

You can set the DB_USER and DB_PASSWORD environment variables to secret references:

Then use op run to pass the secrets to the node app.js command:

Use with environment files​

You can also use op run with environment files. To do this, use secret references instead of plaintext secrets in your environment file:

node.env

Then use op run with the --env-file flag:

If a subprocess used with op run prints a secret to stdout, the secret will be concealed by default. You can include the --no-masking flag to print the value.

To export an example environment variable DB_PASSWORD to a secret reference:

Use op run with the printenv command to print the concealed secret:

See result...

Include the --no-masking flag to print the actual secret:

See result...
Next step

Learn more about loading secrets into the environment with op run, including how to use template variables to switch between different sets of secrets for different environments.

With op inject​

You can use op inject to replace secret references in a script or file with the secrets they reference.

By default, op inject accepts input on stdin and outputs on stdout. You can use the --in-file flag (or -i) to read the input from a file instead, and the --out-file flag (or -o) to specify where the ouput should be written.

To use op inject to resolve a secret in a simple command:

See result...

To write the output to a file token.txt in the current directory:

token.txt

Use with configuration files​

You can use op inject to pass in a configuration file templated with secret references and output a configuration file that contains resolved secrets. Configuration files that use secret references instead of plaintext secrets can be safely checked into Git.

config.yml.tpl

Next step

Learn more about loading secrets into configuration files with op inject, including how to use template variables to switch between different sets of secrets for different environments.

Learn more​

Was this page helpful?