feat: guides and docs for CLI v1 (#1795)

Co-authored-by: Vincent <[email protected]>
ory · Aug 1, 2024 · 049a943 · 049a943
1 parent 27aad66
commit 049a943
Show file tree

Hide file tree

Showing 4 changed files with 153 additions and 103 deletions.
diff --git a/docs/guides/cli/03_cli-migration-v1.mdx b/docs/guides/cli/03_cli-migration-v1.mdx
@@ -0,0 +1,75 @@
+---
+title: Migration Guide to Ory CLI v1
+id: cli-migration-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.
+
+## Upgrade to v1
+
+To upgrade the Ory CLI to v1 please follow the [installation guide](01_installation.mdx) for your OS.
+
+## New authentication methods
+
+The Ory CLI v1 comes with multiple new authentication mechanisms, please visit the [CLI Basics document](05_cli-basics.mdx) for an
+overview of the different authentication methods.
+
+## Migrate 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, see [here](05_cli-basics.mdx) for a detailed description of the new authentication mechanisms.  
+If your script uses multiple workspaces or projects, you need to create multiple keys and use the corresponding environment
+variables.
+
+Here are the changes to commands:
+
+```diff
+- 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=<workspace> ORY_PROJECT=<project-id> ory proxy|tunnel
+
+- ory create event-stream|jwk|oauth2-client|organization|project|relationships|workspace <project>
++ ory create event-stream|jwk|oauth2-client|organization|project|relationships|workspace --project <project>
++ ory create event-stream|jwk|oauth2-client|organization|project|relationships|workspace --workspace <workspace> --project <project>
++ ORY_WORKSPACE=<workspace> ORY_PROJECT=<project> ory create event-stream|jwk|oauth2-client|organization|project|relationships|workspace
+
+- ory delete access-tokens|event-stream|identity|jwk|oauth2-client|organization|relationships <project>
++ ory delete access-tokens|event-stream|identity|jwk|oauth2-client|organization|relationships --project <project>
++ ory delete access-tokens|event-stream|identity|jwk|oauth2-client|organization|relationships --workspace <workspace> --project <project>
++ ORY_WORKSPACE=<workspace> ORY_PROJECT=<project> ory delete access-tokens|event-stream|identity|jwk|oauth2-client|organization|relationships
+
+- ory list event-streams|identities|oauth2-clients|organizations|projects|relationships|workspaces <project>
++ ory list event-streams|identities|oauth2-clients|organizations|projects|relationships|workspaces --project <project>
++ ory list event-streams|identities|oauth2-clients|organizations|projects|relationships|workspaces --workspace <workspace> --project <project>
++ ORY_WORKSPACE=<workspace> ORY_PROJECT=<project> ory list event-streams|identities|oauth2-clients|organizations|projects|relationships|workspaces
+
+- ory import identities|jwk|oauth2-client <project>
++ ory import identities|jwk|oauth2-client --project <project>
++ ory import identities|jwk|oauth2-client --workspace <workspace> --project <project>
++ ORY_WORKSPACE=<workspace> ORY_PROJECT=<project> ory import identities|jwk|oauth2-client
+
+- ory patch identity-config|oauth2-config|opl|permission-config|project <project>
++ ory patch identity-config|oauth2-config|opl|permission-config|project --project <project>
++ ory patch identity-config|oauth2-config|opl|permission-config|project --workspace <workspace> --project <project>
++ ORY_WORKSPACE=<workspace> ORY_PROJECT=<project> ory patch identity-config|oauth2-config|opl|permission-config|project
+
+- ory update event-stream|identity-config|oauth2-client|oauth2-config|opl|organization|permission-config|project <project>
++ ory update event-stream|identity-config|oauth2-client|oauth2-config|opl|organization|permission-config|project --project <project>
++ ory update event-stream|identity-config|oauth2-client|oauth2-config|opl|organization|permission-config|project --workspace <workspace> --project <project>
++ ORY_WORKSPACE=<workspace> ORY_PROJECT=<project> ory update event-stream|identity-config|oauth2-client|oauth2-config|opl|organization|permission-config|project
+```
diff --git a/docs/guides/cli/05_cli-basics.mdx b/docs/guides/cli/05_cli-basics.mdx
@@ -14,8 +14,7 @@ to get more information about the command, available command-specific flags and
 
 ```shell
 ory auth --help
-
-Create an or sign into your Ory Network account
+Create a new Ory Network account or sign in to an existing account.
 
 Usage:
   ory auth [flags]
@@ -26,7 +25,7 @@ Available Commands:
 
 Flags:
   -c, --config string   Path to the Ory Network configuration file.
-      --format string   Set the output format. One of table, json, and json-pretty. (default "default")
+      --format string   Set the output format. One of table, json, yaml, json-pretty, jsonpath and jsonpointer. (default "default")
   -h, --help            help for auth
   -q, --quiet           Be quiet with output printing.
   -y, --yes             Confirm all dialogs with yes.
@@ -41,113 +40,86 @@ documentation is generated automatically from the CLI source code.
 
 :::
 
-## Create Ory Network account and project
+## Authentication
 
-With Ory CLI, you can create a new Ory Network account and project from your terminal.
+The Ory CLI comes with multiple authentication mechanisms.
 
-Follow these steps:
+### Browser login
 
-1. Run this command to start the wizard:
+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.
 
-   ```shell
-   ory auth
-   ```
+:::info
 
-2. If you haven't signed in with the CLI before, you're asked if you have an Ory Network account.
+In case you are interested, the Ory CLI uses the authorization code flow with Ory Hydra to authenticate you. Take a look at how
+it's implemented in the
+[source code](https://github.com/ory/cli/blob/ed90e254aa7113533c1255f639fa1bf1b142de9f/cmd/cloudx/client/auth.go#L143).
 
-   ```shell
-   Do you already have an Ory Console account you wish to use? [y/n]: n
-   ```
+:::
 
-   Answer "no" to create a new account. In the process, you must provide the basic account information: email address, password,
-   user name, and choose if you want to be informed about platform security updates.
+### API key
 
-3. As a final step, accept the [Terms of Service](https://www.ory.sh/ptos).
+In automated environments like CI/CD pipelines, you can authenticate using API keys. The Ory CLI supports both workspace and
+project API keys. 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.
 
-   ```shell
-   I accept the Terms of Service https://www.ory.sh/ptos:  [y/n]: y
-   ```
+Set the API keys using the `ORY_WORKSPACE_API_KEY` and `ORY_PROJECT_API_KEY` environment variables:
 
-4. When the process is completed, the CLI displays the details of the created account and the ID of the currently selected
-   project:
+```shell
+export ORY_WORKSPACE_API_KEY=ory_wak_8dwW9s....
+export ORY_PROJECT_API_KEY=ory_pt_Wse93s....
+```
 
-   ```text
-   You are now signed in as: [email protected]
-   ID			              cae666dg-2ffa-491b-9912-6b090ec10e1c
-   EMAIL			          [email protected]
-   SELECTED_PROJECT	      00000000-0000-0000-0000-000000000000
-   ```
+## Set the working context
 
-:::note
+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.
 
-By default, no projects are associated with new accounts created through the Ory CLI. To create a new project, use the
-[CLI](#create-ory-cloud-project) or the [Ory Console](https://console.ory.sh/).
+It is also possible to set the default workspace and project using the `ory use` command:
 
-:::
+```shell
+ory use workspace $ORY_WORKSPACE
+ory use project $ORY_PROJECT
+```
 
-## Create a project
+## Create a new workspace and project
 
-Run this command to create a new project:
+Run this command to create a new workspace.
 
 ```shell
-ory create project
+ory create workspace --name "My New Workspace"
 ```
 
-When the operation is successful, the system returns the details of the newly created project:
+```bash
+# Example response
 
-```text
-Project created successfully!
-ID	     5e2281bd-e094-87b5-9d76-812ce4a9cfb3
-SLUG	 twisty-galois-kz61jdc42q
-STATE	 running
-NAME	 My Amazing Project
+Workspace created successfully!
+ID                 885a2468-c23d-40df-a783-c941387a8701
+NAME               My New Workspace
+SUBSCRIPTION PLAN  <none>
 ```
 
-## Use CLI with existing account
-
-Sign in to use the CLI with your existing Ory Network account and project.
-
-1. Run this command to start the wizard:
-
-   ```shell
-   ory auth
-   ```
-
-2. If you haven't signed in with the CLI before, you're asked if you have an Ory Network account.
-
-   ```shell
-   Do you already have an Ory Console account you wish to use? [y/n]: n
-   ```
+Now export the workspace ID
 
-3. Follow the on-screen instructions to sign in to your account.
-
-   :::info
-
-   If you created your Ory Network account with a social sign-in provider, you must adjust the account configuration to use the
-   CLI. [Read this section for more information](#accounts-with-social-sign-in).
-
-   :::
-
-4. Upon successful sign in, the CLI shows the details of the signed-in user and the selected project:
-
-   ```text
-   You are now signed in as: [email protected]
-   ID			              7759555-e23a-44b7-b148-7fed7f908024
-   EMAIL			          [email protected]
-   SELECTED_PROJECT	      00000000-0000-0000-0000-000000000000
-   ```
-
-### Accounts with social sign-in
+```
+export ORY_WORKSPACE=885a2468-c23d-40df-a783-c941387a8701
+```
 
-If you created your account through a social sign-in provider such as GitHub or Google, you must adjust your account configuration
-to use the Ory CLI.
+and run this command to create a new project.
 
-Accounts created with social sign-in providers don't use passwords. To use your account with Ory CLI, your account must have a
-password.
+```shell
+ory create project --name "My New Project" --workspace $ORY_WORKSPACE
+```
 
-Follow these steps to create a password for an account created with a social sign-in provider:
+```bash
+# Example response
 
-1. Open the [Ory Console](https://console.ory.sh/) and sign in.
-2. Go to your [account settings](https://console.ory.sh/settings).
-3. Enter a new password in the **Update Password** field.
-4. Click **Save** to finish.
+Project created successfully!
+ID		b7d8a15d-a783-40e6-40df-7acd60cb2b64
+NAME		My New Project
+ENVIRONMENT	dev
+WORKSPACE	885a2468-c23d-40df-a783-c941387a8701
+SLUG		peaceful-something-4iuafwx2vk
+STATE		running
+```
diff --git a/docs/guides/gitops.mdx b/docs/guides/gitops.mdx
@@ -8,18 +8,19 @@ This guide will walk you through the process of managing your Ory Network config
 these steps, you'll be able to track changes, review, and approve them through pull requests, and automatically update the
 configuration upon merge.
 
-This guide uses the [Ory CLI GitHub Action](https://github.com/lomsa-dev/ory-cli-action) to update the configuration and manage
-changes through pull requests. You can adapt this to other git providers and CI/CD systems.
+This guide uses the GitHub Actions to update the configuration and manage changes through pull requests. You can adapt this to
+GitLab CI, TravisCI, CircleCI, and other CI/CD systems.
 
 ## Ory Network configuration
 
 ### Ory Identities configuration
 
 First, pull the current configuration from your Ory Network project. You can also automate this with a GitHub Action, but in this
-case, you just need it once. You can find the `project_id` in the Ory Network dashboard or by using `ory list projects`.
+case, you just need it once. You can find the `workspace-id` and `project-id` in the Ory Network dashboard or by using
+`ory list workspaces` and `ory list projects --workspace <workspace_id>`.
 
 ```bash
-ory get identity-config "$PROJECT_ID" --format json-pretty > identity-config-"$PROJECT_ID".json
+ory get identity-config --workspace "<workspace-id>" --project "<project-id>" --format json-pretty > identity-config.json
 ```
 
 Commit the configuration to git and push it to your repository.
@@ -31,28 +32,29 @@ Create a new file `.github/workflows/ory-cli.yml`. Add the following content to
 ```yaml
 name: Update Ory Network Config
 
+env:
+  ORY_PROJECT_ID: "<project-id>"
+  ORY_WORKSPACE_ID: "<workspace-id>"
+  ORY_WORKSPACE_API_KEY: ${{ secrets.ORY_WORKSPACE_API_KEY }}
+
 on:
   push:
     branches:
       - master
 jobs:
   run-ory-cli:
     runs-on: ubuntu-latest
+    container: oryd/ory:v1
     steps:
       - name: checkout
         uses: actions/checkout@v3
-      - name: ory-cli
-        uses: lomsa-dev/[email protected] # use the latest version
-        with:
-          username: ${{ secrets.ORY_USERNAME }}
-          password: ${{ secrets.ORY_PASSWORD }}
-          commands: |
-            update identity-config "$PROJECT_ID" --file identity-config-"$PROJECT_ID".json
+      - name: Push changes to Ory Network
+        run: ory update identity-config --file identity-config.json
 ```
 
-For the GitHub Action to authenticate with Ory Network, you need to add the ORY_USERNAME and ORY_PASSWORD secrets to your
-repository. You can configure these secrets in the repository's settings.  
-Optionally, you can add the `project_id` as a secret or hardcode it in the workflow file.
+For the GitHub Action to authenticate with Ory Network, you need to add the ORY_WORKSPACE_API_KEY secret to your repository. You
+can configure secrets in the
+[repository's settings](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository).
 
 Now you can make changes to the configuration in git and create pull requests to review and approve the changes. When the pull
 request is merged, the configuration will be updated automatically. You can also use this to roll back changes via the git
@@ -98,8 +100,8 @@ update opl --project "$PROJECT_ID" --file opl-"$PROJECT_ID".ts
 
 ## OpenID Connect Claims and Ory Actions payload
 
-Ory uses Jsonnet snippets for mapping OIDC provider claims to Ory Network identities and for configuring the payload of Ory
-Actions webhooks. You can save and version these snippets in git. You have several options for managing Jsonnet snippets in git.
+Ory uses JSONNet snippets for mapping OIDC provider claims to Ory Network identities and for configuring the payload of Ory
+Actions webhooks. You can save and version these snippets in git. You have several options for managing JSONNet snippets in git.
 Here's an example of how you can organize them:
 
 ```bash
@@ -108,7 +110,7 @@ touch oidc-mapping/google.jsonnet
 # add the mappings for OIDC providers you use
 mkdir actions-payload
 touch actions-payload/registration.jsonnet
-# add the Jsonnet payloads for Ory Actions you use
+# add the JSONNet payloads for Ory Actions you use
 ```
 
 When you make changes, convert the new OIDC mapping or Ory Actions payload to base64 and add it to the config file. You can use
@@ -148,7 +150,7 @@ This is how it looks with OIDC mappings:
 //...
 ```
 
-When you update the configuration, Ory Network will automatically decode the base64 string and save the Jsonnet snippet in the Ory
+When you update the configuration, Ory Network will automatically decode the base64 string and save the JSONNet snippet in the Ory
 Network backend.
 
 ## Identity Schema

diff --git a/docusaurus.config.ts b/docusaurus.config.ts
@@ -50,6 +50,7 @@ const config: Config = {
         "dart",
         "csharp",
         "cshtml",
+        "diff",
       ],
       magicComments: [
         {