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.
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:
-
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 argumentcategory 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": ""
}
]
}
| 1Password CLI 1 | 1Password CLI 2 | Notes |
|---|
uuid | | |
templateUuid | category | |
details | - | replaced by sections and fields |
| 1Password CLI 1 | 1Password CLI 2 | Notes |
|---|
name | id | |
title | label | |
fields | - | moved separately |
| 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
