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
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
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:
Attribute | Definition |
---|---|
type | The field's type |
value | The field's content |
id | The field's unique identifier |
purpose | The designation of a built-in field (can be "username", "password", or "notes") |
otp | Use with one-time password fields to generate a one-time password code |
File attachment attributes:
Attribute | Definition |
---|---|
type | The field's type |
content | The file attachment's content |
size | The size of the file attachment |
id | The file attachment's unique identifier |
name | The 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.