From e2720440edeff3fd9c0815b8f030ebfc7a6cb65f Mon Sep 17 00:00:00 2001 From: PascalSenn Date: Sun, 1 Dec 2024 20:26:33 +0100 Subject: [PATCH] Update Nitro CLI Documentation (#7762) Co-authored-by: Michael Staib Co-authored-by: Glen --- website/src/docs/docs.json | 9 + .../src/docs/nitro/cli-commands/api-key.md | 41 ++++- website/src/docs/nitro/cli-commands/api.md | 63 +++++-- website/src/docs/nitro/cli-commands/client.md | 174 ++++++++++++------ .../docs/nitro/cli-commands/environment.md | 27 ++- website/src/docs/nitro/cli-commands/pat.md | 66 +++++++ website/src/docs/nitro/cli-commands/schema.md | 20 ++ website/src/docs/nitro/cli-commands/stage.md | 47 ++++- .../src/docs/nitro/cli-commands/workspace.md | 37 +++- website/src/docs/nitro/cli/automation.md | 30 +++ website/src/docs/nitro/cli/global-options.md | 23 +++ 11 files changed, 450 insertions(+), 87 deletions(-) create mode 100644 website/src/docs/nitro/cli-commands/pat.md create mode 100644 website/src/docs/nitro/cli/automation.md create mode 100644 website/src/docs/nitro/cli/global-options.md diff --git a/website/src/docs/docs.json b/website/src/docs/docs.json index 74d06f61a25..9993ea0f2a0 100644 --- a/website/src/docs/docs.json +++ b/website/src/docs/docs.json @@ -100,6 +100,14 @@ { "path": "authentication", "title": "Authentication" + }, + { + "path": "global-options", + "title": "Global Options" + }, + { + "path": "automation", + "title": "Automation" } ] }, @@ -114,6 +122,7 @@ { "path": "launch", "title": "launch" }, { "path": "login", "title": "login" }, { "path": "logout", "title": "logout" }, + { "path": "pat", "title": "pat" }, { "path": "schema", "title": "schema" }, { "path": "stage", "title": "stage" }, { diff --git a/website/src/docs/nitro/cli-commands/api-key.md b/website/src/docs/nitro/cli-commands/api-key.md index f4758c54c11..5206725466a 100644 --- a/website/src/docs/nitro/cli-commands/api-key.md +++ b/website/src/docs/nitro/cli-commands/api-key.md @@ -4,21 +4,29 @@ title: API Key Management The `nitro api-key` command provides a set of subcommands that allow you to manage API keys. -# Create a Key +# Create an API Key The `nitro api-key create` command is used to create a new API key. -> **Important:** Use the value prefixed with `Secret:` as the api key value you pass to `ChilliCream.Nitro` +> **Important:** Use the value prefixed with `Secret:` as the API key value you pass to `nitro`. ```shell -nitro api-key create --api-id abc123 +nitro api-key create --name "My API Key" --api-id abc123 ``` **Options** -- `--api-id `: Specifies the ID of the API for which you want to create a new API key. This ID can be retrieved with the `nitro api list` command. You can set it from the environment variable `NITRO_API_ID`. +- `--name `: Specifies a name for the API key for future reference. You can set it from the environment variable `NITRO_API_KEY_NAME`. +- `--api-id `: Specifies the ID of the API for which you want to create the API key. This ID can be retrieved with the `nitro api list` command. You can set it from the environment variable `NITRO_API_ID`. +- `--workspace-id `: Specifies the ID of the workspace. If not provided, the default workspace is used. You can set it from the environment variable `NITRO_WORKSPACE_ID`. -# Delete a Key +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + +# Delete an API Key The `nitro api-key delete` command is used to delete an API key by its ID. @@ -30,10 +38,31 @@ nitro api-key delete api-key123 - ``: Specifies the ID of the API key you want to delete. -# List all Keys +**Options** + +- `--force`: If provided, the command will not ask for confirmation before deleting. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + +# List All API Keys The `nitro api-key list` command is used to list all API keys of a workspace. ```shell nitro api-key list ``` + +**Options** + +- `--cursor `: Specifies the cursor to start the query (for pagination). Useful in non-interactive mode. You can set it from the environment variable `NITRO_CURSOR`. +- `--workspace-id `: Specifies the ID of the workspace. If not provided, the default workspace is used. You can set it from the environment variable `NITRO_WORKSPACE_ID`. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` diff --git a/website/src/docs/nitro/cli-commands/api.md b/website/src/docs/nitro/cli-commands/api.md index 454c422c768..37366d6948f 100644 --- a/website/src/docs/nitro/cli-commands/api.md +++ b/website/src/docs/nitro/cli-commands/api.md @@ -9,9 +9,21 @@ The `nitro api` command provides a set of subcommands that allow you to manage A The `nitro api create` command is used to create a new API. ```shell -nitro api create +nitro api create --name "My API" --path "/my-api" ``` +**Options** + +- `--name `: Specifies the name of the API. You can set it from the environment variable `NITRO_API_NAME`. +- `--path `: Specifies the path to the API. You can set it from the environment variable `NITRO_API_PATH`. +- `--workspace-id `: Specifies the ID of the workspace. If not provided, the default workspace is used. You can set it from the environment variable `NITRO_WORKSPACE_ID`. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + # Delete an API The `nitro api delete` command is used to delete an API by its ID. @@ -20,18 +32,43 @@ The `nitro api delete` command is used to delete an API by its ID. nitro api delete abc123 ``` -**Arguments:** +**Arguments** - ``: Specifies the ID of the API you want to delete. -# List all APIs +**Options** -The `nitro api list` command is used to list all APIs of a workspace. +- `--force`: If provided, the command will not ask for confirmation before deleting. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + +# Set API Settings + +The `nitro api set-settings` command is used to set the settings of an API. ```shell -nitro api list +nitro api set-settings abc123 --treat-dangerous-as-breaking --allow-breaking-schema-changes ``` +**Arguments** + +- ``: Specifies the ID of the API whose settings you want to set. + +**Options** + +- `--treat-dangerous-as-breaking`: If provided, dangerous changes will be treated as breaking changes. You can set it from the environment variable `NITRO_TREAT_DANGEROUS_AS_BREAKING`. +- `--allow-breaking-schema-changes`: If provided, allows breaking schema changes when no client breaks. You can set it from the environment variable `NITRO_ALLOW_BREAKING_SCHEMA_CHANGES`. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + # Show API Details The `nitro api show` command is used to show the details of an API. @@ -40,18 +77,12 @@ The `nitro api show` command is used to show the details of an API. nitro api show abc123 ``` -**Arguments:** +**Arguments** - ``: Specifies the ID of the API whose details you want to see. -# Set API Settings - -The `nitro api set-settings` command is used to set the settings of an API. - -```shell -nitro api set-settings abc123 -``` - -**Arguments:** +**Global Options** -- ``: Specifies the ID of the API whose settings you want to set. +- `--cloud-url ` +- `--api-key ` +- `--output ` diff --git a/website/src/docs/nitro/cli-commands/client.md b/website/src/docs/nitro/cli-commands/client.md index f52ac4934ce..0a36e7e88af 100644 --- a/website/src/docs/nitro/cli-commands/client.md +++ b/website/src/docs/nitro/cli-commands/client.md @@ -2,119 +2,189 @@ title: Client Management --- -The `nitro client` command provides a set of subcommands that allow you to upload, validate, publish, and unpublish client versions, as well as create a new client, list all clients of an API, and show details of a specific client. +The `nitro client` command provides a set of subcommands that allow you to create, delete, upload, validate, publish, unpublish client versions, as well as list all clients of an API, show details of a specific client, and download queries from a stage. -# Publish a Client +# Create a Client -The `nitro client publish` command is used to publish a client version to a stage. +The `nitro client create` command is used to create a new client. ```shell -nitro client publish \ - --tag v1.0.0 \ - --stage production \ - --client-id Q2xpZW50CmdiOGRiYzk5NmRiNTI0OWRlYWIyM2ExNGRiYjdhMTIzNA== +nitro client create --api-id abc123 --name "My Client" ``` -**Options:** +**Options** -- `--tag ` **(required)**: Specifies the tag of the client version to deploy. It creates a new version of the client with the specified tag. The tag can be any string, but it's recommended to use a version number (e.g., v1, v2) or a commit hash. You can set it from the environment variable `NITRO_TAG`. +- `--api-id `: Specifies the ID of the API for which you want to create a client. This ID can be retrieved with the `nitro api list` command. You can set it from the environment variable `NITRO_API_ID`. +- `--name `: Specifies a name for the client for future reference. You can set it from the environment variable `NITRO_API_KEY_NAME`. -- `--stage ` **(required)**: Specifies the name of the stage. This is the name of the environment where the client will be published. You can set it from the environment variable `NITRO_STAGE`. +**Global Options** -- `--client-id ` **(required)**: Specifies the ID of the client. This ID can be retrieved with the `nitro client list` command. You can set it from the environment variable `NITRO_CLIENT_ID`. +- `--cloud-url ` +- `--api-key ` +- `--output ` -- `--api-key `: Specifies the API key used for authentication. It doesn't have to be provided when you are logged in. Otherwise, it's the secret that `nitro api-key create` returns. You can set it from the environment variable `NITRO_API_KEY`. +# Delete a Client -- `--wait-for-approval`: Waits for a user to approve the schema change in the app in case of a breaking change. +The `nitro client delete` command is used to delete a client by its ID. -# Unpublish a Client +```shell +nitro client delete client123 +``` -The `nitro client unpublish` command is used to unpublish a client version from a stage. +**Arguments** + +- ``: Specifies the ID of the client you want to delete. + +**Options** + +- `--force`: If provided, the command will not ask for confirmation before deleting. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + +# Upload a Client Version + +The `nitro client upload` command is used to upload a new client version. ```shell -nitro client unpublish \ - --tag v1.0.0 \ - --stage production \ - --client-id Q2xpZW50CmdiOGRiYzk5NmRiNTI0OWRlYWIyM2ExNGRiYjdhMTIzNA== +nitro client upload --tag v1.0.1 --operations-file ./operations.json --client-id client123 ``` -**Options:** +**Options** + +- `--tag ` **(required)**: Specifies the tag of the client version to upload. It creates a new version of the client with the specified tag. The tag can be any string, but it's recommended to use a version number (e.g., v1.0.1) or a commit hash. You can set it from the environment variable `NITRO_TAG`. +- `--operations-file ` **(required)**: Specifies the path to the JSON file with the operations. This is a file containing persisted queries in Relay style. You can set it from the environment variable `NITRO_OPERATIONS_FILE`. +- `--client-id ` **(required)**: Specifies the ID of the client. This ID can be retrieved with the `nitro client list` command. You can set it from the environment variable `NITRO_CLIENT_ID`. + +**Global Options** -The options for the `unpublish` command are the same as for the `publish` command. +- `--cloud-url ` +- `--api-key ` +- `--output ` -# Validate a Client +# Validate a Client Version The `nitro client validate` command is used to validate a client version. ```shell -nitro client validate \ - --stage production \ - --client-id Q2xpZW50CmdiOGRiYzk5NmRiNTI0OWRlYWIyM2ExNGRiYjdhMTIzNA== \ - --operations-file ./operations.json +nitro client validate --stage production --client-id client123 --operations-file ./operations.json ``` -**Options:** +**Options** - `--stage ` **(required)**: Specifies the name of the stage. This is the name of the environment where the client will be validated. You can set it from the environment variable `NITRO_STAGE`. +- `--client-id ` **(required)**: Specifies the ID of the client. You can set it from the environment variable `NITRO_CLIENT_ID`. +- `--operations-file ` **(required)**: Specifies the path to the JSON file with the operations. You can set it from the environment variable `NITRO_OPERATIONS_FILE`. -- `--client-id ` **(required)**: Specifies the ID of the client. This ID can be retrieved with the `nitro client list` command. You can set it from the environment variable `NITRO_CLIENT_ID`. +**Global Options** -- `--operations-file ` **(required)**: Specifies the path to the JSON file with the operations. This is a file containing persisted queries in relay style. You can set it from the environment variable `NITRO_OPERATIONS_FILE`. +- `--cloud-url ` +- `--api-key ` +- `--output ` -- `--api-key `: Specifies the API key used for authentication. It doesn't have to be provided when you are logged in. Otherwise, it's the secret that `nitro api-key create` returns. You can set it from the environment variable `NITRO_API_KEY`. +# Publish a Client Version -# Upload a Client - -The `nitro client upload` command is used to upload a new client version. +The `nitro client publish` command is used to publish a client version to a stage. ```shell -nitro client upload --tag v1.0.1 --operations-file ./operations.json --client-id Q2xpZW50CmdiMDk4MDEyODM0MTI0MDIxNDgxMjQzMTI0MTI= +nitro client publish --tag v1.0.0 --stage production --client-id client123 ``` -**Options:** +**Options** -- `--tag ` **(required)**: Specifies the tag of the client version to deploy. It creates a new version of the client with the specified tag. The tag can be any string, but it's recommended to use a version number (e.g., v1, v2) or a commit hash. You can set it from the environment variable `NITRO_TAG`. +- `--tag ` **(required)**: Specifies the tag of the client version to publish. You can set it from the environment variable `NITRO_TAG`. +- `--stage ` **(required)**: Specifies the name of the stage. You can set it from the environment variable `NITRO_STAGE`. +- `--client-id ` **(required)**: Specifies the ID of the client. You can set it from the environment variable `NITRO_CLIENT_ID`. +- `--force`: If provided, the command will not ask for confirmation before publishing. +- `--wait-for-approval`: If provided, waits for a user to approve the schema change in case of a breaking change. -- `--operations-file ` **(required)**: Specifies the path to the JSON file with the operations. This is a file containing persisted queries in relay style. You can set it from the environment variable `NITRO_OPERATIONS_FILE`. +**Global Options** -- `--client-id ` **(required)**: Specifies the ID of the client. This ID can be retrieved with the `nitro client list` command. You can set it from the environment variable `NITRO_CLIENT_ID`. +- `--cloud-url ` +- `--api-key ` +- `--output ` -- `--api-key `: Specifies the API key used for authentication. It doesn't have to be provided when you are logged in. Otherwise, it's the secret that `nitro api-key create` returns. You can set it from the environment variable `NITRO_API_KEY`. +# Unpublish a Client Version -# Create Client +The `nitro client unpublish` command is used to unpublish a client version from a stage. -The `nitro client create` command is used to create a new client. +```shell +nitro client unpublish --tag v1.0.0 --stage production --client-id client123 +``` + +**Options** + +- `--tag ` **(required)**: Specifies the tag of the client version to unpublish. You can set it from the environment variable `NITRO_TAG`. +- `--stage ` **(required)**: Specifies the name of the stage. You can set it from the environment variable `NITRO_STAGE`. +- `--client-id ` **(required)**: Specifies the ID of the client. You can set it from the environment variable `NITRO_CLIENT_ID`. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + +# Download Queries from a Stage + +The `nitro client download` command is used to download the queries from a stage. ```shell -nitro client create --api-id QXBpCmdiOGRiYzk5NmRiNTI0OWRlYWIyM2ExNGRiYjdhMTIzNA== +nitro client download --api-id abc123 --stage production --output ./queries --format relay ``` -**Options:** +**Options** -- `--api-id `: Specifies the ID of the API for which you want to create a client. This ID can be retrieved with the `nitro api list` command. You can set it from the environment variable `NITRO_API_ID`. +- `--api-id ` **(required)**: Specifies the ID of the API from which to download the queries. You can set it from the environment variable `NITRO_API_ID`. +- `--stage ` **(required)**: Specifies the name of the stage. You can set it from the environment variable `NITRO_STAGE`. +- `--output ` **(required)**: Specifies the path where the queries will be stored. +- `--format `: Specifies the format in which the queries will be stored. Options are `folder` or `relay`. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` -# List all Clients +# List All Clients The `nitro client list` command is used to list all clients of an API. ```shell -nitro client list --api-id QXBpCmdiOGRiYzk5NmRiNTI0OWRlYWIyM2ExNGRiYjdhMTIzNA== +nitro client list --api-id abc123 ``` -**Options:** +**Options** -- `--api-id `: Specifies the ID of the API for which you want to list the clients. This ID can be retrieved with the `nitro api list` command. You can set it from the environment variable `NITRO_API_ID`. +- `--api-id `: Specifies the ID of the API for which you want to list the clients. You can set it from the environment variable `NITRO_API_ID`. +- `--cursor `: Specifies the cursor to start the query (for pagination). You can set it from the environment variable `NITRO_CURSOR`. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` # Show Client Details The `nitro client show` command is used to show details of a specific client. ```shell -nitro client show Q2xpZW50CmdiMDk4MDEyODM0MTI0MDIxNDgxMjQzMTI0MTI= +nitro client show client123 --fields publishedVersions,versions ``` -**Arguments:** +**Arguments** + +- ``: The ID of the client whose details you want to show. + +**Options** + +- `--fields `: Specifies additional fields to display in the client detail prompt. You can specify multiple fields separated by commas. -- ``: The ID of the client whose details you want to show. This ID can be retrieved with the `nitro client list` command. +**Global Options** - +- `--cloud-url ` +- `--api-key ` +- `--output ` diff --git a/website/src/docs/nitro/cli-commands/environment.md b/website/src/docs/nitro/cli-commands/environment.md index 83c43b4e38f..c7838e7a0b5 100644 --- a/website/src/docs/nitro/cli-commands/environment.md +++ b/website/src/docs/nitro/cli-commands/environment.md @@ -4,30 +4,39 @@ title: Environment The `nitro environment` command provides a set of subcommands that allow you to manage environments. -# Create a Environment +# Create an Environment The `nitro environment create` command is used to create a new environment. ```shell -nitro environment create +nitro environment create --name "Development Environment" ``` -# List all Environments +**Options** -The `nitro environment list` command is used to list all environments of a workspace. +- `--name ` or `-n `: Specifies the name of the environment. +- `--workspace-id `: Specifies the ID of the workspace. You can set it from the environment variable `NITRO_WORKSPACE_ID`. -```shell -nitro environment list -``` +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` # Show Environment Details The `nitro environment show` command is used to show the details of an environment. ```shell -nitro environment show abc123 +nitro environment show env123 ``` -**Arguments:** +**Arguments** - ``: Specifies the ID of the environment whose details you want to see. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` diff --git a/website/src/docs/nitro/cli-commands/pat.md b/website/src/docs/nitro/cli-commands/pat.md new file mode 100644 index 00000000000..2a2a88d6179 --- /dev/null +++ b/website/src/docs/nitro/cli-commands/pat.md @@ -0,0 +1,66 @@ +--- +title: Personal Access Token Management +--- + +The `nitro pat` command provides a set of subcommands that allow you to manage Personal Access Tokens (PATs). PATs are tokens associated with your user account that can be used for authenticating with the Nitro platform in scripts, automation tools, and CI/CD pipelines. + +# Create a Personal Access Token + +> **Important:** Use the value prefixed with `Secret:` as the API key value you pass to `nitro`. + +The `nitro pat create` command is used to create a new personal access token. + +```shell +nitro pat create --description "Automation Token" --expires 180 +``` + +**Options** + +- `--description `: Provides a description for the PAT to help you identify it later. You can set it from the environment variable `NITRO_DESCRIPTION`. +- `--expires `: Specifies the expiration time of the PAT in days. The default is 180 days. You can set it from the environment variable `NITRO_EXPIRES`. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + +## List All Personal Access Tokens + +The `nitro pat list` command is used to list all personal access tokens associated with your account. + +```shell +nitro pat list +``` + +**Options** + +- `--cursor `: Specifies the cursor to start the query (for pagination). Useful in non-interactive mode. You can set it from the environment variable `NITRO_CURSOR`. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + +### Revoke a Personal Access Token + +The `nitro pat revoke` command is used to revoke a personal access token by its ID. + +```shell +nitro pat revoke UGVyc29uYWxBY2Nlc3NUb2tlbjpUaGlzIElzIE5vdCBBIFRva2VuIDspIA== +``` + +**Arguments** + +- ``: Specifies the ID of the personal access token you want to revoke. + +**Options** + +- `--force`: If provided, the command will not ask for confirmation before revoking. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` diff --git a/website/src/docs/nitro/cli-commands/schema.md b/website/src/docs/nitro/cli-commands/schema.md index 38d94b93b5e..310072ba169 100644 --- a/website/src/docs/nitro/cli-commands/schema.md +++ b/website/src/docs/nitro/cli-commands/schema.md @@ -62,4 +62,24 @@ nitro schema upload \ - `--api-key `: Specifies the API key used for authentication. It doesn't have to be provided when you are logged in. Otherwise, it's the secret that `nitro api-key create` returns. You can set it from the environment variable `NITRO_API_KEY`. +# Download a Schema + +The `nitro schema download` command is used to download a schema from a stage. + +```shell +nitro schema download --api-id abc123 --stage production --file ./schema.graphql +``` + +**Options** + +- `--api-id ` **(required)**: Specifies the ID of the API from which to download the schema. You can set it from the environment variable `NITRO_API_ID`. +- `--stage ` **(required)**: Specifies the name of the stage. You can set it from the environment variable `NITRO_STAGE`. +- `--file ` **(required)**: Specifies the file path where the schema will be stored. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + diff --git a/website/src/docs/nitro/cli-commands/stage.md b/website/src/docs/nitro/cli-commands/stage.md index 8407eb1cee5..071f2340e81 100644 --- a/website/src/docs/nitro/cli-commands/stage.md +++ b/website/src/docs/nitro/cli-commands/stage.md @@ -55,7 +55,42 @@ Remember to save any changes you've made before exiting the Console UI. - `--api-id `: Specifies the ID of the API for which you want to edit stages. This ID can be retrieved with the `nitro api list` command. You can set it from the environment variable `NITRO_API_ID`. -# List all Stages +# Edit Stages of an API (non-interactive) + +The `nitro stage edit` command also provides a non-interactive user interface for managing the stages of an API. + +```shell +nitro stage edit --api-id abc123 --configuration '[{"name":"stage1","displayName":"Stage 1","conditions":[{"afterStage":"stage2"}]}]' +``` + +**Options** + +- `--api-id `: Specifies the ID of the API for which you want to edit stages. You can set it from the environment variable `NITRO_API_ID`. +- `--configuration `: Provides the stage configuration in JSON format. If not provided, an interactive selection will be shown. The input should be a JSON array of stage configurations. + +**Example Configuration:** + +```json +[ + { + "name": "stage1", + "displayName": "Stage 1", + "conditions": [ + { + "afterStage": "stage2" + } + ] + } +] +``` + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + +# List All Stages The `nitro stage list` command is used to list all stages of an API. @@ -63,8 +98,14 @@ The `nitro stage list` command is used to list all stages of an API. nitro stage list --api-id QXBpCmdiOGRiYzk5NmRiNTI0OWRlYWIyM2ExNGRiYjdhMTIzNA== ``` -**Options:** +**Options** + +- `--api-id `: Specifies the ID of the API for which you want to list the stages. You can set it from the environment variable `NITRO_API_ID`. + +**Global Options** -- `--api-id `: Specifies the ID of the API for which you want to list the stages. This ID can be retrieved with the `nitro api list` command. You can set it from the environment variable `NITRO_API_ID`. +- `--cloud-url ` +- `--api-key ` +- `--output ` diff --git a/website/src/docs/nitro/cli-commands/workspace.md b/website/src/docs/nitro/cli-commands/workspace.md index f0fded78771..a6f53587799 100644 --- a/website/src/docs/nitro/cli-commands/workspace.md +++ b/website/src/docs/nitro/cli-commands/workspace.md @@ -9,9 +9,20 @@ The `nitro workspace` command provides a set of subcommands that allow you to ma The `nitro workspace create` command is used to create a new workspace. ```shell -nitro workspace create +nitro workspace create --name "My Workspace" --default ``` +**Options** + +- `--name `: Specifies the name of the workspace. +- `--default`: If provided, sets the created workspace as the default workspace. + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + # Set Default Workspace The `nitro workspace set-default` command is used to select a workspace and set it as your default workspace. @@ -20,6 +31,12 @@ The `nitro workspace set-default` command is used to select a workspace and set nitro workspace set-default ``` +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + # List all Workspaces The `nitro workspace list` command is used to list all workspaces. @@ -28,6 +45,12 @@ The `nitro workspace list` command is used to list all workspaces. nitro workspace list ``` +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + # Show Workspace Details The `nitro workspace show` command is used to show the details of a workspace. @@ -40,6 +63,12 @@ nitro workspace show abc123 - ``: Specifies the ID of the workspace whose details you want to see. +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` + # Show Current Workspace The `nitro workspace current` command is used to show the name of the currently selected workspace. @@ -47,3 +76,9 @@ The `nitro workspace current` command is used to show the name of the currently ```shell nitro workspace current ``` + +**Global Options** + +- `--cloud-url ` +- `--api-key ` +- `--output ` diff --git a/website/src/docs/nitro/cli/automation.md b/website/src/docs/nitro/cli/automation.md new file mode 100644 index 00000000000..81c5f50dbaa --- /dev/null +++ b/website/src/docs/nitro/cli/automation.md @@ -0,0 +1,30 @@ +--- +title: Automation +--- + +When integrating the `nitro` CLI into CI/CD pipelines or automation scripts, you can use API keys or personal access tokens (PATs) for authentication. + +- **API Keys**: Ideal for use in CI/CD or for telemetry reporting in your GraphQL server. You can create API keys with the `nitro api-key create` command. + +- **Personal Access Tokens (PATs)**: If you need to automate other tasks or require broader access, you can use personal access tokens. Create them with the `nitro pat create` command. Use the PAT in the CLI with the `--api-key` option. + +# Passing Inputs Non-Interactively + +All inputs in the CLI can be passed via environment variables or as options in the CLI commands. This allows you to skip the interactive mode and use the CLI non-interactively in your automation scripts. + +For example: + +- Use environment variables like `NITRO_API_ID`, `NITRO_STAGE`, etc., to provide inputs. +- Use command-line options like `--api-id`, `--stage`, etc., to specify inputs directly. + +# Parsing CLI Output + +By default, the CLI outputs rich text suitable for human reading. When using the CLI in automation scripts, you may want to parse the output programmatically. + +- Use the `--output json` option to get the output in JSON format. This allows you to easily parse the output using tools like `jq`. + +Example: + +```shell +nitro api-key list --output json | jq '.' +``` diff --git a/website/src/docs/nitro/cli/global-options.md b/website/src/docs/nitro/cli/global-options.md new file mode 100644 index 00000000000..7bf03084c87 --- /dev/null +++ b/website/src/docs/nitro/cli/global-options.md @@ -0,0 +1,23 @@ +--- +title: Global Options +--- + +Many commands in the `nitro` CLI share common options. These options are used to configure the CLI's behavior and authentication. Here are the common options: + +# `--cloud-url ` + +Specifies the URL where the Nitro server is located. By default, this points to the shared clusters at `api.chillicream.com`. If you have a self-hosted instance or a dedicated instance, you need to change this value to point to your server. + +You can set this option from the environment variable `NITRO_CLOUD_URL`. + +# `--api-key ` + +Accepts API keys created via the `nitro api-key create` command or personal access tokens (PATs) created with the `nitro pat create` command. If you are running in the interactive mode in the CLI, you can also use `nitro login` to authenticate. + +You can set this option from the environment variable `NITRO_API_KEY`. + +# `--output ` + +By default, the CLI uses rich text output suitable for human reading. If you want to parse the output programmatically (e.g., using `jq`), you can use this option to get the output in JSON format. This is especially useful when using the CLI in automation scripts or CI/CD pipelines. + +You can set this option from the environment variable `NITRO_OUTPUT_FORMAT`.