Skip to main content

Secret reference syntax

With 1Password CLI, you can use secret references to inject secrets from your 1Password account into environment files, configuration files, and scripts without storing any plaintext secrets in code.

You can copy secret references for most fields from the 1Password app.

A secret reference URI includes the name of the vault, item, section, and field where a secret is stored in your 1Password account:

To reference a file attachment, use the file name in place of a field name:

If any of the names include an unsupported character, you can refer to it using its ID instead.

Secret reference examples

A field inside a section

To create a secret reference that refers to the PagerDuty email field, which is within the Admin section, use:

  • Management refers to the vault where the item is saved
  • PagerDuty refers to the item
  • Admin refers to the section where the field is a part of
  • email refers to the field where the secret you want to reference is located
PagerDuty 1Password itemPagerDuty 1Password item

A field without a section

To create a secret reference for the Stripe publishable-key field, which is not part of a section, use:

  • dev refers to the vault where the item is saved
  • Stripe refers to the item
  • publishable-key refers to the field where the secret you want to reference is located
Stripe 1Password itemStripe 1Password item

Syntax rules

Secret references are case-insensitive and support the following characters:

  • alphanumeric characters (a-z, A-Z, 0-9)
  • -, _, . and the whitespace character

If a secret reference includes a whitespace, it should be enclosed in quotation marks. For example:

The / character is a delimiter character used to separate the different parts of the secret reference.

If an item or field name includes a / or an unsupported character, use the item or field's unique identifier (ID) instead of its name. To get an ID, run op item get with the output set to JSON. For example, to get the ID for a custom text field named test/:

See result...

You can also get a secret reference that uses IDs for fields with unsupported characters by copying the secret reference from the 1Password app.

Retrieve field and file metadata

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

Attribute parameter

To get information about item fields and file attachments, use the attribute (or attr) query parameter.

Fields

File attachments

You can use the attribute parameter to get the following information:

AttributeDefinition
typeThe field's type
valueThe field's content
idThe field's unique identifier
purposeThe designation of a built-in field (can be "username", "password", or "notes")
otpUse with one-time password fields to generate a one-time password code

File attachment attributes:

AttributeDefinition
typeThe field's type
contentThe file attachment's content
sizeThe size of the file attachment
idThe file attachment's unique identifier
nameThe name of the file attachment

For example, to retrieve an item's one-time password code:

See result...

To retrieve a field's type:

See result...

To retrieve the name of a file attachment:

See result...

SSH format parameter

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

Learn more

Was this page helpful?