The Wayback Machine - https://web.archive.org/web/20230209110905/https://developer.1password.com/docs/cli/secret-references/
Skip to main content

Replace plaintext secrets with secret references

Learn how to create and use secret references to avoid putting plaintext secrets in code.

With 1Password CLI, you can use secret references to securely load secrets saved in 1Password in environment variables, configuration files, and anywhere else you might need them, without putting any plaintext secrets in code. At runtime, secret references are automatically replaced with the actual secrets they refer to.

Secret references use the following syntax to point to where the secret is saved in your 1Password account:

For example, if you've saved your GitHub personal token in 1Password, you can set the GITHUB_TOKEN environment variable with a secret reference instead of a plaintext secret:

Requirements​

Before you can use secret references with 1Password CLI, you'll need to sign up for 1Password and install 1Password CLI.

Save your secret in 1Password​

To create a secret reference, you first need to save the secret in 1Password and make note of how you saved it.

In this example, we've saved the GitHub item in the development vault, with the personal token saved in the personal_token field within the credentials section.

The GitHub item in 1Password.The GitHub item in 1Password.

Generate a secret reference​

You can use op item get to automatically generate a secret reference for every field saved on an item:

Each field will include a line titled "reference" that contains its secret reference. For example, the output for the GitHub item:

You can also create a secret reference manually using the secret reference syntax.

Read a secret reference​

You can use op read to resolve a secret reference into the secret it refers to:

If a secret reference includes a whitespace, it must be enclosed in quotation marks.

Export a secret reference as an environment variable​

You can export a secret reference to an environment variable:

Then use op run with the --no-masking flag to print the variable and check the resolved secret:

Learn more​

Load secrets into the environment​

Replace the secrets in your environment file with secret references, then use op run to pass your secrets to an application. You can use environment variables within each secret reference to differentiate between different sets of secrets for different environments.

Load secrets into config files​

Replace the secrets in your config file with secret references, then use op inject to provision them into your environment at runtime. You can use environment variables within each secret reference to differentiate between different sets of secrets for different environments.

Secret reference syntax​

Learn the secret reference syntax rules and write your own secret references.

Was this page helpful?