1Password command-line tool: Full documentation

The 1Password command-line tool provides commands to manage and administer a 1Password account.

Sign in to an account to get started. Run op signin --help to learn more.

How to specify objects

You can specify all objects by name or UUID. You can also specify some objects by other attributes:

• Items: item link
• Login or Password items: domain name
• Users: email address

When you specify an item by name or domain, there may be more than one item that matches. To be more specific, use the --vault option to only look in one vault at a time, or use a unique ID (UUID) instead.

Commands

Usage

op [command] [options]

Global options

-h, --help                get help with a command
    --account shorthand   use the account with this shorthand
    --session token       authenticate with this session token

Get help

For help with any command, use the --help option:

op <command> [subcommand] --help

add

Subcommands

• add group: Grant a group access to a vault
• add user: Grant a user access to a vault or group

Related commands

• edit: Edit an object
• remove: Revoke access to groups or vaults

add group

Grants a group access to a vault.

op add group <group> <vault> [flags]

add user

Grants a user access to a vault or group.

op add user <user> [<vault> | <group>] [flags]

Options for add user

--role role   set the user's role in a group (member or manager) (default "member")

completion

Generates shell completion information for the 1Password command-line tool.

op completion <shell> [flags]

How completion works

If you use Bash or Zsh, you can add shell completion for the 1Password command-line tool. With completions loaded, after you start typing an op command, press Tab to see available commands and options.

Load shell completion information for Bash

To always load the completion information for Bash, add this to your .bashrc file:

source <(op completion bash)

To use shell completion in Bash, you’ll need the `bash-completion` package.

Load shell completion information for Zsh

To always load the completion information for Zsh, add this to your .zshrc file:

eval "$(op completion zsh)"; compdef _op op

confirm

Confirms users.

op confirm [<user> | --all]

Options for confirm

--all    confirm all unconfirmed users

Related commands

• create user: Create a user

create

Subcommands

• create document: Create a document
• create group: Create a group
• create item: Create an item
• create user: Create a user
• create vault: Create a vault

create document

Creates a document.

op create document <file> [flags]

Options for create document

--file-name name   set the file's name
--tags tags        add one or more tags (comma-separated) to the item
--title title      set the item's title
--vault vault      save the document in this vault

How create document works

When you create a document, a JSON object containing its UUID is returned. The document is saved to the Private or Personal vault unless you specify another with the --vault option.

Create a file from standard input

To create a file from standard input (stdin), enter a hyphen (-) instead of a file path. You can use the --file-name option to change the name of the saved file.

Examples for create document

Create a document from standard input:

cat auth.log.* | op create document - --title "Authlogs 2020-06" --file-name "auth.log.2020.06"

create group

Creates a group.

op create group <name> [flags]

Options for create group

--description description   set the group's description

How create group works

When you create a group, a JSON object containing its UUID is returned.

create item

Creates an item.

op create item <category> [<encoded_item>] [<assignment> ...] [flags]

Options for create item

--generate-password [recipe]   give the item a randomly generated password
--tags tags                    add one or more tags (comma-separated) to the item
--title title                  set the item's title
--url URL                      set the URL associated with the item
--vault vault                  save the item in this vault

How create item works

Create an item using assignment statements or with a 1Password JSON object template.

When you create an item, a JSON object containing its UUID is returned. The item is saved to the Private or Personal vault unless you specify another with the --vault option.

Create an item with assignment statements

Use an assignment statement to set a field’s value:

[<section>.]<field>=<value>

You can omit spaces when you specify the section or field name. You can also refer to the field by its JSON short name (name or n).

phonetollfree=012066188656

The section is optional unless multiple sections have a field with the same name.

testingserver.address=db.local.1password.com
developmentserver.address=db.dev.1password.com

You can't make a new custom section using an assignment statement.

Generate a password

Use the --generate-password option to generate and set a random password for a Login or Password item. By default, it will create a 32-character password made up of letters, numbers, and symbols.

You can customize the password with a password recipe. Specify the password length and which character types to use in a comma-separated list. Ingredients are:

• letters for uppercase and lowercase letters
• digits for numbers
• symbols for special characters (!@.-_*)
• 1-64 for password length

Create an item with a template

If you want to create an item with custom sections or fields, use a JSON object template. Download and edit a template for the category of item you want to create. Run op help get template for a list of template categories. To create an item using a template:

1. Get a template for the category of item you want to create, and save it to a file:

    op get template "Login" > login.json
   

2. Edit the template to add your information.

3. Encode the JSON object and create the item:

    op create item "Login" "$(op encode < login.json)"
   

When you’re finished, delete the unencrypted JSON template file.

You can use a tool like jq (https://stedolan.github.io/jq/) to reformat JSON to make it easier to read.

If you use both a template and assignment statements in the same command, the assignment statements overwrite the template’s values.

Related commands

• encode: Encode the JSON needed to create an item
• get template: Get an item template
• list templates: Get a list of templates

create user

Creates a new user.

op create user <email_address> <name> [flags]

Options for create user

--language language   set the user's account language (default "en")

Related commands

• confirm: Confirm a user

create vault

Creates a new vault.

op create vault <name> [flags]

Options for create vault

--allow-admins-to-manage true|false   set whether admins can manage vault access
--description description             set the group's description

delete

Subcommands

delete document

Moves a document to the Trash.

op delete document <document> [flags]

Options for delete document

--vault vault   look for the document in this vault

delete group

Removes a group.

op delete group <group> [flags]

delete item

Moves an item to the Trash.

op delete item <item> [flags]

Options for delete item

--vault vault   look for the item in this vault

delete trash

Empties the Trash for the vault.

op delete trash <vault> [flags]

How delete trash works

The items in the Trash will be permanently deleted.

delete user

Removes a user and all their data from the account.

op delete user <user> [flags]

delete vault

Removes a vault.

op delete vault <vault> [flags]

edit

Subcommands

• edit group: Edit a group’s name or description
• edit item: Edit an item’s details
• edit user: Edit a user’s name or Travel Mode status
• edit vault: Edit a vault’s name

Related commands

• add: Grant access to groups or vaults

edit group

Changes a group’s name or description.

op edit group <group> [flags]

Options for edit group

--description description   change the group's description
--name name                 change the group's name

edit item

Edits an item’s details.

op edit item <item> <assignment> [<assignment> ...] [flags]

Options for edit item

--generate-password [recipe]   give the item a randomly generated password
--vault vault                  look for the item in this vault

How edit item works

Use an assignment statement to change a field’s value:

[<section>.]<field>=<value>

You can omit spaces when you specify the section or field name. You can also refer to the field by its JSON short name (name or n).

issuingcountry=Canada

The section is optional unless multiple sections have a field with the same name.

testingserver.address=db.local.1password.com
developmentserver.address=db.dev.1password.com

You can’t make a new custom section using an assignment statement.

Generate a password

Use the --generate-password option to generate and set a random password for a Login or Password item. By default, it will create a 32-character password made up of letters, numbers, and symbols.

You can customize the password with a password recipe. Specify the password length and which character types to use in a comma-separated list. Ingredients are:

• letters for uppercase and lowercase letters
• digits for numbers
• symbols for special characters (!@.-_*)
• 1-64 for password length

edit user

Changes a user’s name or Travel Mode status.

op edit user <user> [flags]

Options for edit user

--name name           set the user's name
--travelmode on|off   turn Travel Mode on or off for the user (default )

edit vault

Changes a vault’s name.

op edit vault <vault> [flags]

Options for edit vault

--name name   change the vault's name

encode

Encodes the JSON data needed to create a new item with base64url encoding. Accepts input from standard input (stdin).

op encode [flags]

Examples for encode

Encode a basic item template:

op get template login | op encode

Save the encoded contents of a file to another file:

cat my-new-login.json | op encode > my-new-login.encoded-json

Related commands

• get template: Get an item template
• create item: Create an item
• edit item: Edit an item’s details

forget

Removes the details for a 1Password account from this device.

op forget <account> [flags]

get

Subcommands

get account

Gets details about your account.

op get account [flags]

get document

Downloads a document and prints the contents to standard output (stdout).

op get document <document> [flags]

Options for get document

--include-trash   include items from the Trash
--output path     save the document to the file path instead of stdout
--vault vault     look for the document in this vault

How get document works

Save to a file

Use the --output option to have op save the document. This may be useful in some shells in order to preserve the file’s original encoding.

The --output option won’t overwrite an existing file. The destination path must be an empty file or not exist.

Examples for get document

Save a document to a file called secret-plans.text:

op get document "Top Secret Plan B" > secret-plans.text

get group

Gets details about a group.

op get group <group> [flags]

How get group works

Use standard input to specify objects

If you enter a hyphen (-) instead of a single object for this command, the tool will read object specifiers from standard input (stdin). Separate each specifier with a new line. For more information about how to specify objects, run op help.

You can also pass the command a list or array of JSON objects. The tool will get an item for any object that has a UUID key, ignoring line breaks. This is useful for passing information from one op command to another.

Examples for get group

Get details for all groups:

op list groups | op get group -

Get details for the groups who have access to a specified vault:

op list groups --vault "Development" | op get group -

get item

Returns details about an item.

op get item <item> [flags]

Options for get item

--fields fields   only return data from these fields
--format format   return data in this format (CSV or JSON) (use with --fields)
--include-trash   include items in the Trash
--share-link      get a shareable link for the item
--vault vault     look for the item in this vault

How get item works

By default, get item returns a complete 1Password JSON object.

Customize returned data

To only get details from specific fields, use the --fields option.

Specify fields in a comma-separated list. You can omit spaces when you specify the section or field name. You can also refer to the field by its JSON short name (name or n).

When you specify one field, its data is returned as a simple string. If you specify more than one field, the data is returned in a simple key-value pair JSON object. If a field doesn’t exist, an empty value is returned.

Use the --format option to change the output format to JSON or CSV.

Specify items on standard input

The command treats each line of information on standard input (stdin) as an object specifier. Run op help to learn more about how to specify objects.

The input can also be a list or array of JSON objects. The command will get an item for any object that has a UUID key. This is useful for passing information from one op command to another.

Items in the Trash

Items in the Trash are ignored by default. To get details for an item in the Trash, specify the item by UUID or use the --include-trash option.

Examples for get item

Get details for all items with a specified tag:

op list items --tags "travel" | op get item -

Get the username and password for all logins in a specified vault, in CSV format:

op list items --category "Login" --vault "Slack" | op get item - --fields username,password --format CSV

get template

Returns a template for an item type.

op get template <category> [flags]

How get template works

You can create a new item with a template. Run op create item --help for more information.

Categories are:

Related commands

• encode: Encode the JSON needed to create an item
• create item: Create an item

get totp

Gets an item’s current time-based one-time password (TOTP).

op get totp <item> [flags]

Options for get totp

--vault vault   look for the item in this vault

How get totp works

Items in the Trash

Items in the Trash are ignored by default. To get the TOTP for an item in the Trash, specify the item by UUID.

get user

Gets details about a user.

op get user <user> [flags]

Options for get user

--fingerprint   get the user's public key fingerprint
--publickey     get the user's public key

How get user works

Use standard input to specify objects

If you enter a hyphen (-) instead of a single object for this command, the tool will read object specifiers from standard input (stdin). Separate each specifier with a new line. For more information about how to specify objects, run op help.

You can also pass the command a list or array of JSON objects. The tool will get an item for any object that has a UUID key, ignoring line breaks. This is useful for passing information from one op command to another.

Examples for get user

Get details for all users:

op list users | op get user -

Get the public key for all users in a specified group:

op list users --group "Administrators" | op get user - --publickey

Get details for all users who have access to a specified vault:

op list users --vault "Development" | op get user -

get vault

Gets details about a vault.

op get vault <vault> [flags]

How get vault works

Use standard input to specify objects

If you enter a hyphen (-) instead of a single object for this command, the tool will read object specifiers from standard input (stdin). Separate each specifier with a new line. For more information about how to specify objects, run op help.

You can also pass the command a list or array of JSON objects. The tool will get an item for any object that has a UUID key, ignoring line breaks. This is useful for passing information from one op command to another.

Examples for get vault

Get details for all vaults:

op list vaults | op get vault -

Get details for vaults that a specified group has access to:

op list vaults --group "Security" | op get vault -

list

Subcommands

list documents

Lists documents.

op list documents [flags]

Options for list documents

--include-trash   include documents in the Trash
--vault vault     only list documents in this vault

How list documents works

Returns a list of all documents the account has read access to by default. Excludes items in the Trash by default.

list events

Lists events from the Activity Log.

op list events [flags]

Options for list events

--eventid eid   start listing from event with ID eid
--older         list events from before the specified event

How list events works

Returns the 100 most recent events by default.

The Activity Log is only available for 1Password Business accounts.

Examples for list events

List events after a specific log entry

You can provide an event ID (eid) as a starting point for listing entries by using the --eventid option. A maximum of 100 events will be returned, starting after, but not including, the provided event.

op list events --eventid 319458129

List events before a specific log entry

You can use the --older flag with the --eventid option to list entries that occurred before the provided event ID. A maximum of 100 events will be returned, starting with the event before, not including, the provided event.

op list events --older --eventid 319179570

list groups

Lists groups.

op list groups [flags]

Options for list groups

--vault vault   list groups who have direct access to this vault

How list groups works

Returns all groups in an account by default.

Examples for list groups

Get details for all groups:

op list groups | op get group -

Get details for the groups who have access to a specified vault:

op list groups --vault "Development" | op get group -

list items

Lists items.

op list items [flags]

Options for list items

--categories categories   only list items in these categories (comma-separated)
--include-trash           include items in the Trash
--tags tags               only list items with these tags (comma-separated)
--vault vault             only list items in this vault

How list items works

Returns a list of all items the account has read access to by default. Excludes items in the Trash by default.

Categories are:

Examples for list items

Get details for all items with a specified tag:

op list items --tags "travel" | op get item -

Get the username and password for all logins in a specified vault, in CSV format:

op list items --category "Login" --vault "Slack" | op get item - --fields username,password --format CSV

list templates

Lists available item type templates.

op list templates [flags]

How list templates works

Use op get template to get a template to use to create a new item.

Related commands

• create item: Create an item
• get template: Get an item template

list users

Lists users.

op list users [flags]

Options for list users

--group group   list users who belong to a group
--vault vault   list users who have direct access to vault

How list users works

Returns all users in an account by default.

Examples for list users

Get details for all users:

op list users | op get user -

Get the public key for all users in a specified group:

op list users --group "Administrators" | op get user - --publickey

Get details for all users who have access to a specified vault:

op list users --vault "Development" | op get user -

list vaults

Lists vaults.

op list vaults [flags]

Options for list vaults

--group group   list vaults a group has access to

How list vaults works

Returns all vaults the account has access to by default.

Examples for list vaults

Get details for all vaults:

op list vaults | op get vault -

Get details for vaults that a specified group has access to:

op list vaults --group "Security" | op get vault -

reactivate

Reactivates a suspended user.

op reactivate <user> [flags]

Related commands

• suspend: Suspend a user

remove

Subcommands

• remove group: Revoke a group’s access to a vault
• remove user: Revoke a user’s access to a vault or group

Related commands

• add: Grant access to groups or vaults

remove group

Revokes a group’s access to a vault.

op remove group <group> <vault> [flags]

remove user

Revokes a user’s access to a vault or group.

op remove user <user> [<vault> | <group>] [flags]

signin

Signs in to a 1Password account and returns a session token.

op signin [<sign_in_address> [<email_address> [<secret_key>]]] [flags]

Options for signin

-r, --raw              only return the session token
    --shorthand name   set the short account name

How signin works

Sessions expire after 30 minutes of inactivity.

Shorthands

Each account has a device-specific shorthand. By default, the shorthand is the account’s subdomain. Hyphens (-) are converted to underscores (_) for system compatibility. You can set the account shorthand the first time you sign in to an account.

Session tokens

You can save the session token to an environment variable (OP_SESSION_shorthand) for op to use automatically. The tool returns an export command by default, which you can use to set the environment variable. You can do this in one step by using the system eval command: eval $(op signin <shorthand>)

When you perform a command, op looks for a session token in an environment variable corresponding to the last signed-in account. If it exists, op uses that token automatically. You may need to sign in again if the session has expired.

Multiple accounts

You can sign in to multiple accounts at once. When signed in to more than one account, op will use the account you most recently signed in to. Use the --account option to specify a different account. Alternatively, use a session token passed with the --session option.

Related commands

• signout: Sign out of a 1Password account

signout

Signs out of a 1Password account.

op signout [flags]

Options for signout

--forget   remove the details for a 1Password account from this device

How signout works

Signs out of the most recently used account by default.

Related commands

• signin: Sign in to a 1Password account

suspend

Suspends a user.

op suspend <user> [flags]

Related commands

• reactivate: Reactivate a suspended user

update

Checks for updates to op. Gets link to download an updated version, if available.

op update [flags]