Upgrade to 1Password CLI 2 - 1Password Developer

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

1Password CLI 1 is deprecated1Password CLI 1 is deprecated as of October 1, 2024. Upgrade to 1Password CLI 2 to avoid disruptions with scripts or integrations that use version 1.

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:

Other schema changes include:

The default output is now a human-friendly, tabular schema.
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.

Use which op (or (Get-Command op).Path on Windows) to get the directory of the current installation.
Download 1Password CLI 2 and move op to the same directory, overwriting the existing copy.
To verify the installation, check the version number:
op --version
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.

Use the 1Password CLI Docker image or use your own image and add the CLI. Your Dockerfile should look like this:
FROM 1password/op:2 COPY ./your-script.sh /your-script.sh CMD ["/your-script.sh"]
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:

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

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.

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.
When you’ve updated all your scripts and are ready to upgrade, uninstall the earlier version of 1Password CLI.
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	by default, lists vaults you have read access to to see all the vaults you can manage, include `--permission manage`
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 1Password Events 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

{
  "fields": [
    {
      "designation": "username",
      "name": "username",
      "type": "T",
      "value": ""
    },
    {
      "designation": "password",
      "name": "password",
      "type": "P",
      "value": ""
    }
  ],
  "notesPlain": "",
  "passwordHistory": [],
  "sections": []
}

New template

{
  "title": "",
  "category": "LOGIN",
  "fields": [
    {
      "id": "username",
      "type": "STRING",
      "purpose": "USERNAME",
      "label": "username",
      "value": ""
    },
    {
      "id": "password",
      "type": "CONCEALED",
      "purpose": "PASSWORD",
      "label": "password",
      "value": ""
    },
    {
      "id": "notesPlain",
      "type": "STRING",
      "purpose": "NOTES",
      "label": "notesPlain",
      "value": ""
    }
  ]
}

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.

​About 1Password CLI 2

​New schema

​Secrets provisioning

​Integrate 1Password CLI with the 1Password desktop app

​Shell plugins

​Package manager installation

​Step 1: Choose an upgrade strategy

​Upgrade immediately

​Upgrade gradually

​Use Docker to upgrade individual projects

​Use both versions of 1Password CLI

​Step 2: Update your scripts

​Appendix: Change default output to JSON

​Appendix: Item JSON template

​Get help

​Learn more

About 1Password CLI 2

New schema

Secrets provisioning

Integrate 1Password CLI with the 1Password desktop app

Shell plugins

Package manager installation

Step 1: Choose an upgrade strategy

Upgrade immediately

Upgrade gradually

Use Docker to upgrade individual projects

Use both versions of 1Password CLI

Step 2: Update your scripts

Appendix: Change default output to JSON

Appendix: Item JSON template

Get help

Learn more