1Password CLI 1 reference
1Password CLI 1 is deprecated as of October 1, 2024. Scripts and integrations that use version 1 will no longer work as expected. Upgrade to 1Password CLI 2 to maintain uninterrupted access and compatibility with the latest features.
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.
Looking up an item (such as a Connect server or vault) by ID is more efficient than using the name.
Cache item and vault information
1Password CLI can use its daemon process to cache items, vault
information, and the keys to access information in an account. To use
the cache, use the --cache
option with a command. When working with
items, the cache is most effective after it has a list of the items in a
vault.
The daemon stores encrypted information in memory using the same encryption methods as on 1Password.com. It can read the information to pass to 1Password CLI but can’t decrypt it. 1Password CLI starts the daemon automatically and it terminates itself after 24 hours of inactivity.
Use alternative character encoding
By default, 1Password CLI processes input and output with UTF-8
encoding. You can use an alternative character encoding with the
--encoding
option. Supported alternative character encoding types:
gbk
shift-jis
Commands
- add: Grant access to groups or vaults
- completion: Generate shell completion information
- confirm: Confirm a user
- create: Create an object
- delete: Remove an object
- edit: Edit an object
- encode: Encode the JSON needed to create an item
- forget: Remove a 1Password account from this device
- get: Get details about an object
- list: List objects and events
- manage: Manage group access to 1Password integrations
- reactivate: Reactivate a suspended user
- remove: Revoke access to groups or vaults
- signin: Sign in to a 1Password account
- signout: Sign out of a 1Password account
- suspend: Suspend a user
- update: Check for and download updates
Usage
Global options
Get help
For help with any command, use the --help
option:
add
Subcommands
- add connect: Grant access to vaults to 1Password Secrets Automation
- add group: Grant a group access to a vault
- add user: Grant a user access to a vault or group
Related commands
add connect
Subcommands
- add connect server: Grant a Connect server access to a vault
add connect server
Grant a Connect server access to a vault.
Related commands
- create connect token: Issue a token for a 1Password Connect server
add group
Grant a group access to a vault.
add user
Grant a user access to a vault or group.
Options for add user
completion
Generate shell completion information for 1Password CLI.
How completion works
If you use Bash or Zsh, you can add shell completion for 1Password CLI.
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:
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:
confirm
Confirm users.
Options for confirm
Related commands
- create user: Create a user
create
Subcommands
- create connect: Create 1Password Connect servers and tokens
- create document: Create a document
- create group: Create a group
- create integration: Create an integration
- create item: Create an item
- create user: Create a user
- create vault: Create a vault
create connect
Subcommands
- create connect server: Set up a 1Password Connect server
- create connect token: Issue a token for a 1Password Connect server
create connect server
Add a 1Password Connect server to your account and generate a credentials file for it.
Options for create connect server
How create connect server works
The 1password-credentials.json
file is saved in the current directory.
Related commands
- create connect token: Issue a token for a 1Password Connect server
- manage connect add: Grant access to manage Secrets Automation
- manage connect remove: Revoke access to manage Secrets Automation
create connect token
Issue a new token for an Connect server.
Options for create connect token
How create connect token works
Returns a token.
You can only grant a token access to a vault that the server has access to and only the permissions the server has for it.
By default, the --vault
option grants the same permissions as the server.
You can further limit the permissions a token has to read-only or write-only
by adding a comma and r
or w
after the vault specification. For example:
Related commands
- manage connect add: Grant access to manage Secrets Automation
- manage connect remove: Revoke access to manage Secrets Automation
create document
Create a document.
Options for create document
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 the file contents from standard input (stdin
), enter a
hyphen (-
) instead of a path. You can use the --filename
option to
change the name of the file.
Examples for create document
Create a document from standard input:
create group
Create a group.
Options for create group
How create group works
When you create a group, a JSON object containing its UUID is returned.
create integration
Subcommands
- create integration events-api: Create an Events API integration
create integration events-api
Create an Events API integration token. Print the Events API integration token when successful.
Options for create integration events-api
create item
Create an item.
Options for create item
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:
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
).
The section is optional unless multiple sections have a field with the same name.
You can't make a new custom section using an assignment statement.
If you can't trust other users or processes on your system, use op create item <category> --template=file.json
instead.
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 lettersdigits
for numberssymbols
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:
-
Get a template for the category of item you want to create, and save it to a file:
-
Edit the template to add your information.
-
Create the item from the template file:
-
When you’re finished, remove the template file.
You can use a tool like jq to reformat JSON to make it easier to read.
If you were using op encode
previously when creating items,
upgrade to the more secure create item --template=file.json
.
It skips the need to encode the file.
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
Create a new user.
Options for create user
Related commands
- confirm: Confirm a user
create vault
Create a new vault.
Options for create vault
How create vault works
Valid icon keywords are:
- airplane
- application
- art-supplies
- bankers-box
- brown-briefcase
- brown-gate
- buildings
- cabin
- castle
- circle-of-dots
- coffee
- color-wheel
- curtained-window
- document
- doughnut
- fence
- galaxy
- gears
- globe
- green-backpack
- green-gem
- handshake
- heart-with-monitor
- house
- id-card
- jet
- large-ship
- luggage
- plant
- porthole
- puzzle
- rainbow
- record
- round-door
- sandals
- scales
- screwdriver
- shop
- tall-window
- treasure-chest
- vault-door
- vehicle
- wallet
- wrench
delete
Subcommands
- delete connect: Remove 1Password Connect servers and tokens
- delete document: Delete or archive a Document
- delete group: Remove a group
- delete item: Delete or archive an item
- delete trash: Delete trash
- delete user: Completely remove a user
- delete vault: Remove a vault
delete connect
Subcommands
- delete connect server: Remove a 1Password Connect server
- delete connect token: Revoke a token for a Connect server
delete connect server
Remove a 1Password Connect server.
How delete connect server works
The credentials file and all the tokens for the server will no longer be valid.
delete connect token
Revoke a token for a Connect server.
Options for delete connect token
Related commands
- create connect token: Issue a token for a 1Password Connect server
delete document
Permanently delete a document. Use the --archive
option to move it to
the Archive instead.
Options for delete document
How delete document works
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.
Examples for delete document
Permanently delete a document:
Move a document to the Archive:
delete group
Remove a group.
delete item
Permanently delete an item. Use the --archive
option to move it to
the Archive instead.
Options for delete item
How delete item works
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.
Examples for delete item
Permanently delete an item:
Move an item to the Archive:
delete trash
You can permanently delete an item with op delete <item>
or to move it to the Archive, use op delete item --archive <item>
.
delete user
Remove a user and all their data from the account.
delete vault
Remove a vault.
edit
Subcommands
- edit connect: Edit 1Password Connect servers and tokens
- edit document: Edit a document
- 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 metadata
Related commands
- add: Grant access to groups or vaults
edit connect
Subcommands
- edit connect server: Rename a Connect server
- edit connect token: Rename a Connect token
edit connect server
Rename a Connect server.
Options for edit connect server
Related commands
- list connect servers: Get a list of 1Password Connect servers
edit connect token
Rename a Connect token.
Options for edit connect token
Related commands
- list connect tokens: Get a list of tokens
edit document
Update a document.
Options for edit document
How edit document works
Replace the file contents of a Document item with the provided file
or with the information on standard input (stdin
).
Update a file from standard input
To update the file contents from standard input (stdin
), enter a
hyphen (-
) instead of a path. You can use the --filename
option to
change the name of the file.
edit group
Change a group's name or description.
Options for edit group
edit item
Edit an item's details.
Options for edit item
How edit item works
Use an assignment statement to change a field's 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
).
The section is optional unless multiple sections have a field with the same name.
You can't make a new custom section using an assignment statement.
When providing secrets on the command line, always be wary of any other processes that might be monitoring what you’re doing.
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 lettersdigits
for numberssymbols
for special characters (!@.-_*
)1
-64
for password length
edit user
Change a user's name or Travel Mode status.
Options for edit user
edit vault
Edit the name, icon, and description of a vault.
Options for edit vault
How edit vault works
Valid icon keywords are:
- airplane
- application
- art-supplies
- bankers-box
- brown-briefcase
- brown-gate
- buildings
- cabin
- castle
- circle-of-dots
- coffee
- color-wheel
- curtained-window
- document
- doughnut
- fence
- galaxy
- gears
- globe
- green-backpack
- green-gem
- handshake
- heart-with-monitor
- house
- id-card
- jet
- large-ship
- luggage
- plant
- porthole
- puzzle
- rainbow
- record
- round-door
- sandals
- scales
- screwdriver
- shop
- tall-window
- treasure-chest
- vault-door
- vehicle
- wallet
- wrench
Related commands
- list vaults: Get a list of vaults
- get vault: Get details about a vault
encode
This command has been deprecated.
Use the more secure --template flag with create item
instead.
It skips the need to encode the file.
How encode works
Encode the JSON needed to create an item with base64url
encoding. Accepts input from standard input (stdin
).
Examples for encode
Encode a basic item template:
Save the encoded contents of a file to another file:
Related commands
- get template: Get an item template
- create item: Create an item
- edit item: Edit an item's details
forget
Remove the details for a 1Password account from this device.
get
Subcommands
- get account: Get details about your account
- get document: Download a document
- get group: Get details about a group
- get item: Get item details
- get template: Get an item template
- get totp: Get the one-time password for an item
- get user: Get details about a user
- get vault: Get details about a vault
get account
Get details about your account.
get document
Download a document and print the contents to standard output (stdout
).
Options for get document
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 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
:
get group
Get details about a group.
How get group works
Use standard input to specify objects
If you enter a hyphen (-
) instead of a single object for this command,
1Password CLI 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. 1Password CLI
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:
Get details for the groups who have access to a vault:
get item
Return details about an item.
Options for get item
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 Archive
Items in the Archive are ignored by default. To get details for an
item in the Archive, specify the item by UUID or use the
--include-archive
option.
Examples for get item
Get details for all items with a specified tag:
Get a CSV list of the website, username, and password for all logins in a vault:
get template
Return a template for an item type.
How get template works
You can create a new item with a template.
Run op create item --help
for more information.
Categories are:
- API Credential
- Bank Account
- Credit Card
- Database
- Document
- Driver License
- Email Account
- Identity
- Login
- Medical Record
- Membership
- Outdoor License
- Passport
- Password
- Reward Program
- Secure Note
- Server
- Social Security Number
- Software License
- Wireless Router
Related commands
- encode: Encode the JSON needed to create an item
- create item: Create an item
get totp
Get an item's current time-based one-time password.
Options for get totp
How get totp works
Items in the Archive
Items in the Archive are ignored by default. To get the TOTP for an item in the Archive, specify the item by UUID.
get user
Get details about a user.
Options for get user
How get user works
Use standard input to specify objects
If you enter a hyphen (-
) instead of a single object for this command,
1Password CLI 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. 1Password CLI
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:
Get the public key for all users in a group:
Get details for all users who have access to a vault:
get vault
Get details about a vault.
How get vault works
Use standard input to specify objects
If you enter a hyphen (-
) instead of a single object for this command,
1Password CLI 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. 1Password CLI
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:
Get details for the vaults that a group has access to:
Related commands
- list vaults: Get a list of vaults
- edit vault: Edit a vault's metadata
list
Subcommands
- list connect: List 1Password Connect servers and tokens
- list documents: Get a list of documents
- list events: Get a list of events from the Activity Log
- list groups: Get a list of groups
- list items: Get a list of items
- list templates: Get a list of templates
- list users: Get the list of users
- list vaults: Get a list of vaults
list connect
Subcommands
- list connect servers: Get a list of 1Password Connect servers
- list connect tokens: Get a list of tokens
list connect servers
List 1Password Connect servers.
Related commands
- create connect token: Issue a token for a 1Password Connect server
- edit connect server: Rename a Connect server
list connect tokens
List tokens for Connect servers.
Options for list connect tokens
How list connect tokens works
Returns active (A
) and revoked (R
) tokens.
The integrationUuid
is the UUID for the Connect server the token belongs to.
Related commands
- edit connect token: Rename a Connect token
list documents
List documents.
Options for list documents
How list documents works
Returns a list of all documents the account has read access to by default. Excludes items in the Archive by default.
list events
List events from the Activity Log.
Options for list events
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:
List events before a specific log entry:
list groups
List groups.
Options for list groups
How list groups works
Returns all groups in an account by default.
Examples for list groups
Get details for all groups:
Get details for the groups who have access to a vault:
Get details for the groups that a person belongs to:
list items
List items.
Options for list items
How list items works
Returns a list of all items the account has read access to by default. Excludes items in the Archive by default.
Categories are:
- API Credential
- Bank Account
- Credit Card
- Database
- Document
- Driver License
- Email Account
- Identity
- Login
- Medical Record
- Membership
- Outdoor License
- Passport
- Password
- Reward Program
- Secure Note
- Server
- Social Security Number
- Software License
- Wireless Router
Examples for list items
Get details for all items with a specified tag:
Get a CSV list of the website
, username
, and password
for all logins in a vault:
list templates
List available item type templates.
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
List users.
Options for list users
How list users works
Returns all users in an account by default.
When you use the --group
option, the output includes the user's role
in the group.
Examples for list users
Get details for all users:
Get the public key for all users in a group:
Get details for all users who have access to a vault:
list vaults
List vaults.
Options for list vaults
How list vaults works
Returns all vaults the account has access to by default.
Examples for list vaults
Get details for all vaults:
Get details for vaults that a group has access to:
Get details for vaults that a user has access to:
Related commands
- get vault: Get details about a vault
- edit vault: Edit a vault's metadata
manage
Subcommands
- manage connect: Manage group access to 1Password Secrets Automation
manage connect
Subcommands
- manage connect add: Grant access to manage Secrets Automation
- manage connect remove: Revoke access to manage Secrets Automation
manage connect add
Grant a group access to manage Secrets Automation.
How manage connect add works
If you don't specify a server, it adds the group to the list of Secrets Automation managers.
manage connect remove
Revoke access from a group to manage Secrets Automation.
reactivate
Reactivate a suspended user.
Related commands
- suspend: Suspend a user
remove
Subcommands
- remove connect: Remove access to vaults from 1Password Connect servers
- 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 connect
Subcommands
- remove connect server: Revoke a Connect server's access to a vault
remove connect server
Revoke access to a vault from a Connect server.
remove group
Revoke a group's access to a vault.
remove user
Revoke a user's access to a vault or group.
signin
Sign in to a 1Password account and return a session token.
Options for signin
How signin works
Sign in to an account
To sign in to an account the first time, use your sign-in address and email address:
After you sign in the first time, you can sign in again using only the shorthand for the account:
Use session tokens
1Password CLI uses a session token to authenticate commands with
1Password.com. Sessions expire after 30 minutes of inactivity. You can
save the session token in an environment variable for 1Password CLI to use
automatically or provide a token with each command using the --session
option.
To use the environment variable, run the export
command that 1Password CLI
provides after you sign in. When you run a command, 1Password CLI uses it
automatically.
To provide a session token each time you run a command, sign in using
the --raw
option to get a token. Then use the --session
option with
each command.
Reuse a session token
You can use the --session
option with the signin
command to reuse an
active token or to test whether a session has expired. This may be
useful when writing scripts that use 1Password CLI. If the
session is active, 1Password CLI will use it and return the same token. If
the session is expired, you’ll have to sign in again.
Work with multiple accounts
You can sign in to more than one account at a time. If you store the
session token in an environment variable, 1Password CLI will use the account
you most recently signed in to by default. Use the --account
option to
specify a different account. By default, the shorthand is your account’s
subdomain. You can change it the first time you sign in by using the
--shorthand
option, or in the configuration file. Hyphens (-
) are
converted to underscores (_
) for system compatibility.
Examples for signin
Sign in and set the environment variable in one step:
Related commands
- signout: Sign out of a 1Password account
signout
Sign out of a 1Password account.
Options for signout
How signout works
Signs out of the most recently used account by default.
Related commands
- signin: Sign in to a 1Password account
suspend
Suspend a user.
Options for suspend
Related commands
- reactivate: Reactivate a suspended user
update
Check for updates to op
. Downloads an updated version, if available.