Upgrade to 1Password CLI 2

Learn how to upgrade to 1Password CLI 2 from an earlier version, and update your scripts to the new command syntax.

Upcoming deprecation of 1Password CLI 1

1Password CLI 1 will be deprecated on October 1, 2024. Any scripts or integrations that use version 1 will stop working as expected. We recommend upgrading to 1Password CLI 2 as soon as possible to avoid disruptions.

About 1Password CLI 2

We released version 2 of the 1Password CLI in March 2022. Since then, more than 96% of users have adopted the latest version.

1Password CLI 2 includes a number of changes to the schema to make the tool easier to use as well as new features to help you provision secrets.

New schema

1Password CLI 2 introduces a noun-verb command structure that groups commands by topic rather than by operation. You can find all available topics with op --help, and see the commands avaialble for each topic with op <topic> --help. Topics include:

• vault
• item
• document
• user
• group
• account
• connect
• events-api

Other schema changes include:

• The default output is now a human-friendly, tabular schema.
  Learn how to change the default output to JSON.
• The JSON output schema now contains more useful information.
• Improved stdin processing allows you to chain more commands together.
• The new schema uses flags instead of positional arguments.

Secrets provisioning

To help you provision secrets locally, 1Password CLI 2 allows you to load secrets directly from 1Password in environment variables and configuration files. With secrets provisioning, you can replace your plaintext secrets with references to the secrets stored in 1Password and load them at runtime in your scripts, applications, and other workflows.

Integrate 1Password CLI with the 1Password desktop app

You can sign in to 1Password CLI 2 with the accounts you've added to the 1Password desktop app, then authenticate your accounts on the command line with biometrics.

Shell plugins

To simplify and secure your workflow, 1Password CLI 2 introduces shell plugins that allow you to securely authenticate third-party command-line tools using biometrics.

Package manager installation

1Password CLI 2 supports easier installation with package managers including Apt, Yum, Alpine, and tar.

You can find all changes in the changelog.

To share feedback with us, visit the support community forum.

Step 1: Choose an upgrade strategy

There are multiple ways to upgrade to 1Password CLI 2. You can upgrade immediately or gradually, depending on your workflow and toolchain.

Upgrade immediately

The quickest way to upgrade to 1Password CLI 2 is to overwrite your existing installation. This is a good option if you have a small team who can upgrade their local installations simultaneously.

1. Use which op (or (Get-Command op).Path on Windows) to get the directory of the current installation.

2. Download 1Password CLI 2 and move op to the same directory, overwriting the existing copy.

3. To verify the installation, check the version number:

4. Update your scripts to use the 1Password CLI 2 syntax.

Make sure everyone on your team upgrades to 1Password CLI 2. After you update your scripts, they won't work with earlier versions of 1Password CLI.

Upgrade gradually

If you're not ready to upgrade immediately, you can use Docker to upgrade individual projects or use both versions of 1Password CLI side-by-side. We will continue to support version 1 for one year after version 2 is released.

Use Docker to upgrade individual projects

If you want to upgrade project by project, you can Dockerize your workflow so that each team member uses the version of 1Password CLI in a Docker image for a specific project. This is a good option for large teams, because it doesn't require each team member to update a local installation.

1. Use the 1Password CLI Docker image or use your own image and add the CLI. Your Dockerfile should look like this:

2. After upgrading to 1Password CLI 2, update your scripts to use the new command syntax.

This approach also sets you up to move your scripts to headless environments such as CI/CD pipelines.

Use both versions of 1Password CLI

If your scripts depend on the local installation on each team member's machine, and you still want to migrate gradually, this is your best option.

Each team member should do the following:

1. Rename the earlier version of 1Password CLI op1.
2. Find and replace all occurences of op with op1.
3. Install 1Password CLI 2 inside your $PATH.
   caution

   For macOS 1Password CLI 2 has to be moved exactly to /usr/local/bin/op.
   For Linux, it is recommended to be moved to /usr/local/bin/op.

4. Update your scripts one-by-one to use the new op. You can continue to use your current scripts with the earlier version of 1Password CLI installed as op1.
5. When you've updated all your scripts and are ready to upgrade, uninstall the earlier version of 1Password CLI.
6. Find and replace all occurrences of op1 in your scripts to op.

Step 2: Update your scripts

If you've been using an earlier version of 1Password CLI in scripts, you'll need to update your scripts to the new syntax.

After you install 1Password CLI 2, use the following table to update your scripts. It shows all the updated commands and associated changes to arguments or flags.

Old command	CLI 2 command	Notes
create vault	vault create
get vault	vault get
edit vault	vault edit	--travel-mode=on/off flag introduced
delete vault	vault delete	allows piped input when the - argument is provided
list vaults	vault list
list users --vault	vault user list
add group	vault group grant	--permission flag must be used to specify the permissions to grant granting allow_viewing, allow_editing and allow_managing is equivalent to granting all permissions group and vault arguments changed to --group and --vault flags
remove group	vault group revoke	--permission flag must be used to specify the permissions to revoke revoking allow_viewing, allow_editing and allow_managing is equivalent to revoking all permissions group and vault arguments changed to --group and --vault flags
add user <user> <vault>	vault user grant	--permission flag must be used to specify the permissions to grant granting allow_viewing, allow_editing and allow_managing is equivalent to granting all permissions user and vault arguments changed to --user and --vault flags
remove user <user> <vault>	vault user revoke	--permission flag must be used to specify the permissions to revoke revoking allow_viewing, allow_editing and allow_managing is equivalent to revoking all permissions user and vault arguments changed to --user and --vault flags
signin <url>	account add	for new accounts/urls the password can be piped in if email, address, and secret key are provided via flag
signin --list	account list	account list will format its output based on output format selection (JSON vs human readable)
forget account	account forget	new -—all flag for forgetting all accounts
get account	account get
confirm user	user confirm	allows piped input when the - argument is provided
create user	user provision	email and name arguments changed to --email and --name flags
delete user	user delete	allows piped input when the - argument is provided
edit user	user edit	allows piped input when the - argument is provided
reactivate user	user reactivate	allows piped input when the - argument is provided
suspend user	user suspend	--deauthorize-devices-after flag accepts any duration unit, not just seconds
list users	user list
get user	user get	added -—me flag to get the currently authenticated user —publickey changed to —public-key
create connect server	connect server create	add —-server flag instead of using an argument for specifying the related server
delete connect server	connect server delete	allows piped input when the - argument is provided
edit connect server	connect server edit
list connect servers	connect server list
-	connect server get
create connect token	connect token create
delete connect token	connect token delete
edit connect token	connect token edit	argument name changed from jti to token
list connect tokens	connect token list	ConnectVault.ACL is now displayed in lowercase_with_underscores
add connect server	connect vault grant	server and vault arguments changed to --server and --vault flags
remove connect server	connect vault revoke	server and vault arguments changed to --server and --vault flags
manage connect add group	connect group grant	server and group arguments changed to --server and --group flags
manage connect remove group	connect group revoke	server and group arguments changed to --server and --group flags
create item	item create	--template flag to specify item template file replaces encode item as an argument category argument changed to --category flag Template JSON format has changed. Learn more about the new format.
delete item	item delete	allows piped input when the - argument is provided
edit item	item edit	new --tags, --title, --url flags
get item	item get
list items	item list
list templates	item template list
get template	item template get
create group	group create
delete group	group delete	allows piped input when the - argument is provided
edit group	group edit	allows piped input when the - argument is provided
list groups	group list
get group	group get
add user <user> <group>	group user grant	user and group arguments changed to --user and --group flags
remove user <user> <group>	group user revoke	user and group args changed to --user and --group flags
op list users --group <group>	group user list	op list users --group GROUP still works
delete trash	-	deprecated
create document	document create	--filename flag changed to --file-name flag
edit document	document edit	--filename flag changed to --file-name flag
list documents	document list
get document	document get
delete document	document delete
create integration events-api	events-api create
list events	-	Use Events Reporting API instead.
encode	-	deprecated, use create item --template=file.json instead
get totp	item get --otp

Appendix: Change default output to JSON

The default output format for 1Password CLI 2 is a human-readable, tabular schema. You can change the default to machine-readable JSON in two ways:

• For a single command, include the --format json flag with your command. For example, op item get <name> --format json.
• To always default to JSON, set the $OP_FORMAT environment variable to json.

Appendix: Item JSON template

You can expect to see several formatting improvements and field name changes in 1Password CLI 2 item JSON templates.

Old template

New template

This is how 1Password CLI 1 template fields correspond to 1Password CLI 2:

Item

1Password CLI 1	1Password CLI 2	Notes
uuid
templateUuid	category
details	-	replaced by sections and fields

Section

1Password CLI 1	1Password CLI 2	Notes
name	id
title	label
fields	-	moved separately

Field

1Password CLI 1	1Password CLI 2
n	id
k	type
t	label
v	value
-	section

Get help

If you need help upgrading to 1Password CLI 2, contact 1Password Support or join our Developer Slack workspace and ask a question in the #cli channel.

Learn more

• Get started with 1Password CLI 2
• 1Password CLI 2 release notes import { textChangeRangeIsUnchanged } from "typescript"