Migration Guide to Ory CLI v1

The Ory CLI v1 got a big lift in terms of usability and features. This guide helps you migrate from Ory CLI v0 to Ory CLI v1.

Authentication

Ory CLI v1 comes with multiple new authentication mechanisms.

Interactive Browser Login

You can authenticate using the ory auth command. The command opens a browser window where you can log in to your Ory account. After logging in, you can use the CLI to manage workspaces, projects, and project data.

info

In case you are interested, the Ory CLI uses the authorization code flow with Ory Hydra to authenticate you. Take a look at how we implemented that in the source code.

API Keys

In automated environments like CI/CD pipelines, you can authenticate using API keys. The Ory CLI supports both workspace and project API keys. Generally speaking, workspace API keys have permissions to manage project configs, while project API keys have permissions to manage project data. Depending on the use-case you might need to use one or both.

Set the API keys using the ORY_WORKSPACE_API_KEY and ORY_PROJECT_API_KEY environment variables:

export ORY_WORKSPACE_API_KEY=ory_wak_8dwW9s....
export ORY_PROJECT_API_KEY=ory_pt_Wse93s....

Setting the Working Context

All commands support the --workspace and --project flags to specify the working context. Legacy projects without a workspace can be used by omitting the --workspace flag. Alternatively, the project and workspace can be specified using the ORY_PROJECT and ORY_WORKSPACE environment variables.

It is also possible to set the default workspace and project using the ory use command:

ory use workspace <workspace-id-or-name>
ory use project <project-id-or-slug>

Migrating existing Scripts and Automation

All commands work mostly the same way as before. Use ory help to get more information about the available commands, arguments and flags. To use the new API key authentication, create the necessary keys and set the ORY_WORKSPACE_API_KEY and ORY_PROJECT_API_KEY environment variables. If your script uses multiple workspaces and/or projects, you might need to create multiple keys and use the corresponding environment variables.

These are the changes to specific commands:

- ory open ui <project>
+ ory open ui --project <project>
+ ory open ui --workspace <workspace> --project <project>
+ ORY_WORKSPACE=<workpsace> ORY_PROJECT=<project> ory open ui

- ory get identity-config|oauth2-config|permissions-config <project>
+ ory get identity-config|oauth2-config|permissions-config --project <project>
+ ory get identity-config|oauth2-config|permissions-config --workspace <workspace> --project <project>
+ ORY_WORKSPACE=<workpsace> ORY_PROJECT=<project> ory get identity-config|oauth2-config|permissions-config

- ORY_SDK_URL=https://<project-slug>.projects.oryapis.com ory proxy|tunnel
- ORY_KRATOS_URL=https://<project-slug>.projects.oryapis.com ory proxy|tunnel
+ ory proxy|tunnel --project <project>
+ ory proxy|tunnel --workspace <workspace_id> --project <project>
+ ORY_WORKSPACE=<workpsace> ORY_PROJECT=<project-id> ory proxy|tunnel