diff --git a/.github/workflows/update-cli-docs.yml b/.github/workflows/update-cli-docs.yml index 9b6352726c..a8f7ea4629 100644 --- a/.github/workflows/update-cli-docs.yml +++ b/.github/workflows/update-cli-docs.yml @@ -58,9 +58,20 @@ jobs: with: go-version: '1.22' + - name: Checkout cloud-cli repo + uses: actions/checkout@v4 + with: + path: cloud-cli + submodules: recursive + persist-credentials: true + token: ${{ steps.generate_token.outputs.token }} + repository: temporalio/cloud-cli + - name: Generate CLI docs working-directory: cli - run: go run ./cmd/gen-docs -input internal/temporalcli/commands.yaml -input cliext/option-sets.yaml -output dist/docs + run: | + go run ./cmd/gen-docs -input internal/temporalcli/commands.yaml -input cliext/option-sets.yaml -output dist/docs + go run ./cmd/gen-docs -input ../cloud-cli/temporalcloudcli/commands.yml -output dist/docs -subdir cloud - name: Publish generated docs to documentation repo env: @@ -78,7 +89,9 @@ jobs: branch_name="update-cli-docs-$CLI_RELEASE_TAG" git checkout -b "$branch_name" - cp ../cli/dist/docs/*.mdx docs/cli/ + rm -rf docs/cli/command-reference + mkdir -p docs/cli/command-reference + cp -r ../cli/dist/docs/* docs/cli/command-reference/ git add . git commit -m "$COMMIT_MESSAGE" git push origin "$branch_name" diff --git a/docs/best-practices/cost-optimization.mdx b/docs/best-practices/cost-optimization.mdx index 6d80cc85d2..4cd5aeb684 100644 --- a/docs/best-practices/cost-optimization.mdx +++ b/docs/best-practices/cost-optimization.mdx @@ -156,7 +156,7 @@ For expensive external operations like this, consider: - Increasing `InitialInterval` (for example, to 10s) to reduce retry frequency - Adding error types to `NonRetryableErrorTypes` for errors that won't resolve on retry (such as 4xx HTTP status codes) - Using [next retry delay](/encyclopedia/retry-policies#per-error-next-retry-delay) to dynamically control retry timing based on failure types (for example, respecting rate-limit headers) -- Implementing an [Activity pause pattern](/cli/activity#pause) to wait for manual intervention rather than automatic retries +- Implementing an [Activity pause pattern](/cli/command-reference/activity#pause) to wait for manual intervention rather than automatic retries Use the [Activity Retry Simulator](/develop/activity-retry-simulator) to visualize how different Retry Policy configurations affect retry behavior and Action consumption. diff --git a/docs/cli/cli-basics.mdx b/docs/cli/cli-basics.mdx new file mode 100644 index 0000000000..bb9e9ea622 --- /dev/null +++ b/docs/cli/cli-basics.mdx @@ -0,0 +1,247 @@ +--- +id: cli-basics +title: CLI basics +sidebar_label: CLI basics +slug: /cli/common-operations +description: + Common Temporal CLI operations for running a development server, starting and managing Workflows, and working with + Schedules and Namespaces. +keywords: + - Temporal CLI + - workflow start + - workflow list + - workflow describe + - workflow signal + - workflow terminate + - schedule + - namespace +hide_table_of_contents: true +--- + +import { SetupSteps, SetupStep, CodeSnippet } from '@site/src/components/elements/SetupSteps'; + +This page walks through the operations you're most likely to reach for when using the Temporal CLI. For the full set of +commands, see the [command reference](/cli#command-reference). + + + + +temporal server start-dev + + +temporal server start-dev --db-filename temporal.db + + +}> + +## Run a development server + +The Temporal CLI ships with a complete Temporal binary. Start a local Temporal Service for development with a single +command. + +The Temporal Service is available on `localhost:7233` and the Web UI at `http://localhost:8233`. + +To keep Workflow data between restarts, specify a database file. + +See [Install and configure](/cli/setup-cli#run-a-local-development-server) for more development server options. + + + + + +{`temporal workflow start \\ + --task-queue my-task-queue \\ + --type MyWorkflow \\ + --workflow-id my-workflow-id \\ + --input '"my-input-value"'`} + + +{`temporal workflow execute \\ + --task-queue my-task-queue \\ + --type MyWorkflow \\ + --workflow-id my-workflow-id \\ + --input '"my-input-value"'`} + + +}> + +## Start a Workflow + +Start a Workflow Execution with `temporal workflow start`. + +To start a Workflow and wait for the result, use `temporal workflow execute` instead. + + + + + +temporal workflow list + + +temporal workflow describe --workflow-id my-workflow-id + + +temporal workflow show --workflow-id my-workflow-id + + +}> + +## Check Workflow status + +List running Workflows. + +Get details about a specific Workflow Execution. + +View the Event History for a Workflow Execution. + + + + + +{`temporal workflow signal \\ + --workflow-id my-workflow-id \\ + --name my-signal \\ + --input '"signal-value"'`} + + +{`temporal workflow query \\ + --workflow-id my-workflow-id \\ + --name my-query`} + + +}> + +## Send Signals and Queries + +Send a [Signal](/sending-messages#sending-signals) to a running Workflow. + +[Query](/sending-messages#sending-queries) a running Workflow for its current state. + + + + + +temporal workflow cancel --workflow-id my-workflow-id + + +temporal workflow terminate --workflow-id my-workflow-id + + +}> + +## Cancel or Terminate a Workflow + +Cancel a Workflow Execution. Cancellation allows cleanup logic to run before the Workflow completes. + +Terminate a Workflow Execution. Termination stops the Workflow immediately with no cleanup. + + + + + +temporal cloud login + + +{`temporal workflow list \\ + --address ..tmprl.cloud:7233 \\ + --namespace .`} + + +}> + +## Log in to Temporal Cloud + +Log in to Temporal Cloud with `temporal cloud login`. After login, you can run commands against Temporal Cloud by +providing the address and Namespace. + +See [Use with Temporal Cloud](/cli/temporal-cloud) for all authentication options. + + + + + +{`temporal schedule create \\ + --schedule-id my-schedule \\ + --interval 1h \\ + --task-queue my-task-queue \\ + --type MyScheduledWorkflow`} + + +temporal schedule list + + +{`temporal schedule toggle \\ + --schedule-id my-schedule \\ + --pause --reason "maintenance"`} + + +{`temporal schedule toggle \\ + --schedule-id my-schedule \\ + --unpause --reason "maintenance complete"`} + + +}> + +## Work with Schedules + +Create a [Schedule](/schedule) that starts a Workflow on an interval. + +List all Schedules. + +Pause and unpause a Schedule. + + + + + +temporal operator namespace list + + +temporal operator namespace create --namespace my-namespace + + +}> + +## Manage Namespaces + +List available [Namespaces](/namespaces). + +Create a new Namespace. + +To manage Namespaces on Temporal Cloud, use the Temporal Cloud extension and +[`temporal cloud namespace`](/cli/command-reference/cloud/namespace) commands. + + + + + +temporal workflow list --output json + + +{`temporal workflow list --output json | jq '.[].type.name'`} + + +}> + +## Format and filter output + +Use `--output json` to get machine-readable output from any command. + +Combine with [jq](https://jqlang.github.io/jq/) for filtering. + + + + +## Next steps + +- [Use with Temporal Cloud](/cli/temporal-cloud) to connect the CLI to Temporal Cloud. +- [Command reference](/cli#command-reference) for the full set of commands and options. diff --git a/docs/cli/cloud.mdx b/docs/cli/cloud.mdx new file mode 100644 index 0000000000..552a0aff43 --- /dev/null +++ b/docs/cli/cloud.mdx @@ -0,0 +1,114 @@ +--- +id: cloud +title: Use with Temporal Cloud +sidebar_label: Use with Temporal Cloud +slug: /cli/temporal-cloud +description: Use the Temporal CLI with Temporal Cloud to run Workflows, manage Namespaces, and administer your account. +keywords: + - Temporal CLI + - Temporal Cloud + - API keys + - mTLS + - authentication + - cloud extension +--- + +The Temporal CLI works with Temporal Cloud. The same commands you use for local or self-hosted Temporal services, such +as `temporal workflow start` and `temporal workflow list`, work with Temporal Cloud as allowed by your role once you +provide an address and credentials. + +For administrative tasks, install the Temporal Cloud extension. The extension adds `temporal cloud` commands for +managing your Temporal Cloud account, including Namespaces, users, API keys, and Nexus endpoints. + +:::tip Support, stability, and dependency info + +The Temporal Cloud extension is in [Pre-release](/evaluate/development-production-features/release-stages#pre-release). +APIs and configuration may change before the stable release. + +::: + +Access to Temporal Cloud is governed by role-based access control (RBAC). Your ability to perform actions, including +running CLI commands against in Temporal Cloud is determined by the roles and permissions you have been assigned. Refer +to the [Access control](/cloud/manage-access) page for more details. + +## Connect to Temporal Cloud + +To connect the CLI to Temporal Cloud, provide the Temporal service address, Namespace name, and credentials. Temporal +Cloud supports three credential types: OAuth tokens obtained through the `temporal cloud login` interactive login +command, API keys, and mTLS certificates. + +### Interactive login + +The `temporal cloud login` command opens a browser to authenticate with Temporal Cloud using OAuth. Provide a profile +name to store credentials in. If no profile is specified, credentials are stored in the `default` profile. + +```bash +temporal cloud login --profile prod +``` + +Complete the interactive login process in your browser. After login, your OAuth token is stored in the specified +configuration profile. Run commands against Temporal Cloud by specifying the profile, address, and Namespace: + +```bash +temporal workflow list --profile prod \ + --address
\ + --namespace +``` + +### Non-interactive login + +For AI agents, CI pipelines, scripts, and other non-interactive environments, use API keys or mTLS certificates. Store +credentials in a [configuration profile](/develop/environment-configuration#cli-integration) or set them as +[environment variables](/cli/setup-cli#environment-variables) to avoid passing them on every command. + +To pass credentials inline: + +```bash +# Using an API key +temporal workflow list \ + --address ..tmprl.cloud:7233 \ + --namespace . \ + --api-key + +# Using mTLS certificates +temporal workflow list \ + --address ..tmprl.cloud:7233 \ + --namespace . \ + --tls-cert-path /path/to/client.pem \ + --tls-key-path /path/to/client.key +``` + +### Log out + +To log out, run the `temporal cloud logout` command. + +```bash +temporal cloud logout --profile prod +``` + +This will remove the OAuth token from the specified configuration profile. If you provided API keys or mTLS +certificates, they will remain in the profile. + +## Cloud administration + +The Temporal Cloud extension adds `temporal cloud` commands for managing your Temporal Cloud control plane resources in +your Temporal Cloud account, including Namespaces, Users, Service Accounts, API keys, and others. Any of the +authentication methods above grants access to these commands. + +The extension enables you to do the following through the CLI: + +- Create, configure, and delete Namespaces. +- Create and manage API keys for programmatic access. +- Invite users, assign roles, and manage user groups. +- Create and configure Nexus endpoints. +- View account information and manage connectivity rules. + +For installation instructions, see +[Install the Temporal Cloud extension](/cli/setup-cli#install-the-temporal-cloud-extension). For the full list of +commands, see the [`cloud` command reference](/cli/command-reference/cloud). + +## Next steps + +- [CLI basics](/cli/common-operations) for common CLI commands. +- [Environment configuration](/develop/environment-configuration) for managing connection profiles across environments. +- [Cloud command reference](/cli/command-reference/cloud) for all `temporal cloud` commands. diff --git a/docs/cli/activity.mdx b/docs/cli/command-reference/activity.mdx similarity index 100% rename from docs/cli/activity.mdx rename to docs/cli/command-reference/activity.mdx diff --git a/docs/cli/batch.mdx b/docs/cli/command-reference/batch.mdx similarity index 100% rename from docs/cli/batch.mdx rename to docs/cli/command-reference/batch.mdx diff --git a/docs/cli/command-reference/cloud/account.mdx b/docs/cli/command-reference/cloud/account.mdx new file mode 100644 index 0000000000..c7343d148a --- /dev/null +++ b/docs/cli/command-reference/cloud/account.mdx @@ -0,0 +1,318 @@ +--- +id: account +title: Temporal CLI cloud account command reference +sidebar_label: account +description: Account Management Commands +toc_max_heading_level: 4 +keywords: + - account + - management +tags: + - account +--- + +{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten. +This file is generated from https://github.com/temporalio/cli via cmd/gen-docs */} + +This page provides a reference for the `temporal cloud account` commands. The flags applicable to each subcommand are presented in a table within the heading for the subcommand. Refer to [Global Flags](#global-flags) for flags that you can use with every subcommand. + +## audit-log + +Commands for working with account audit logs. + +### audit-log get + +Returns a paginated list of audit logs for the account, optionally filtered by time range. + +Example: + temporal cloud account audit-log get --page-size 50 + temporal cloud account audit-log get --start-time 2024-01-01T00:00:00Z --end-time 2024-02-01T00:00:00Z + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--end-time` | No | **timestamp** Filter for logs before this UTC time (RFC3339 format, e.g. 2024-02-01T00:00:00Z). Defaults to current time. | +| `--page-size` | No | **int** Number of logs to retrieve per page. Cannot exceed 1000. Defaults to 100. | +| `--page-token` | No | **string** Page token from a previous response to retrieve the next page. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--start-time` | No | **timestamp** Filter for logs at or after this UTC time (RFC3339 format, e.g. 2024-01-01T00:00:00Z). Defaults to 30 days ago. | + +### audit-log sink + +Commands for working with account audit log sinks. + +#### audit-log sink delete + +Delete an audit log sink for the account. This action is irreversible. + +Example: + temporal cloud account audit-log sink delete --name my-sink + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** The name of the audit log sink to delete. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +#### audit-log sink disable + +Disable an audit log sink for the account. + +Example: + temporal cloud account audit-log sink disable --name my-sink + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** The name of the audit log sink to disable. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +#### audit-log sink enable + +Enable an audit log sink for the account. + +Example: + temporal cloud account audit-log sink enable --name my-sink + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** The name of the audit log sink to enable. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +#### audit-log sink get + +Returns the details of an audit log sink for the account. + +Example: + temporal cloud account audit-log sink get --name my-sink + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--name` | Yes | **string** The name of the audit log sink to get. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +#### audit-log sink kinesis + +Commands for managing Kinesis-based audit log sinks. + +##### audit-log sink kinesis create + +Create an account audit log sink that streams audit events to Amazon Kinesis. + +Temporal Cloud assumes the specified IAM role to write events to the Kinesis +stream identified by the destination URI. + +Example: + temporal cloud account audit-log sink kinesis create \ + --name my-sink \ + --role-name arn:aws:iam::123456789012:role/MyRole \ + --destination-uri arn:aws:kinesis:us-east-1:123456789012:stream/MyStream \ + --region us-east-1 + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--destination-uri` | Yes | **string** ARN of the Kinesis stream to deliver audit log events to. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** Name of the audit log sink. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--region` | Yes | **string** AWS region where the Kinesis stream is located (e.g. us-east-1). | +| `--role-name` | Yes | **string** ARN of the IAM role that Temporal Cloud assumes to write to the Kinesis stream. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +##### audit-log sink kinesis update + +Update an existing Kinesis audit log sink. Only the flags you provide are changed; +omitted string flags retain their current values. + +Example: + temporal cloud account audit-log sink kinesis update \ + --name my-sink \ + --role-name arn:aws:iam::123456789012:role/NewRole + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--destination-uri` | No | **string** ARN of the Kinesis stream to deliver audit log events to. If omitted, the current value is kept. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** Name of the audit log sink to update. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--region` | No | **string** AWS region where the Kinesis stream is located (e.g. us-east-1). If omitted, the current value is kept. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--role-name` | No | **string** ARN of the IAM role that Temporal Cloud assumes to write to the Kinesis stream. If omitted, the current value is kept. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +##### audit-log sink kinesis validate + +Validate an audit log sink configuration against Amazon Kinesis without creating it. +Use this to verify that the IAM role and Kinesis stream are correctly configured +before creating or updating the sink. + +Example: + temporal cloud account audit-log sink kinesis validate \ + --name my-sink \ + --role-name arn:aws:iam::123456789012:role/MyRole \ + --destination-uri arn:aws:kinesis:us-east-1:123456789012:stream/MyStream \ + --region us-east-1 + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--destination-uri` | Yes | **string** ARN of the Kinesis stream to deliver audit log events to. | +| `--region` | Yes | **string** AWS region where the Kinesis stream is located (e.g. us-east-1). | +| `--role-name` | Yes | **string** ARN of the IAM role that Temporal Cloud assumes to write to the Kinesis stream. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +#### audit-log sink list + +Returns a paginated list of audit log sinks for the account. + +Example: + temporal cloud account audit-log sink list + temporal cloud account audit-log sink list --page-size 50 + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--page-size` | No | **int** Number of sinks to retrieve per page. Cannot exceed 1000. Defaults to 100. | +| `--page-token` | No | **string** Page token from a previous response to retrieve the next page. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +#### audit-log sink pubsub + +Commands for managing PubSub audit log sinks. + +##### audit-log sink pubsub create + +Creates a new PubSub audit log sink for the account using Google Cloud Pub/Sub. + +Example: + +``` +temporal cloud account audit-log sink pubsub create \ + --name my-sink \ + --service-account-id my-sa \ + --topic-name my-topic \ + --gcp-project-id my-project +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--gcp-project-id` | Yes | **string** The GCP project ID of the PubSub topic and service account. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** The name of the audit log sink. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--service-account-id` | Yes | **string** The GCP service account ID that Temporal Cloud impersonates for writing records to the customer's PubSub topic. | +| `--topic-name` | Yes | **string** The destination PubSub topic name where audit logs will be sent. | + +##### audit-log sink pubsub update + +Updates an existing PubSub audit log sink for the account. + +Example: + +``` +temporal cloud account audit-log sink pubsub update \ + --name my-sink \ + --service-account-id new-sa \ + --topic-name new-topic \ + --gcp-project-id new-project +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--gcp-project-id` | No | **string** The GCP project ID of the PubSub topic and service account. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** The name of the audit log sink to update. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--service-account-id` | No | **string** The GCP service account ID that Temporal Cloud impersonates for writing records to the customer's PubSub topic. | +| `--topic-name` | No | **string** The destination PubSub topic name where audit logs will be sent. | + +##### audit-log sink pubsub validate + +Validates a PubSub audit log sink specification without creating or modifying any resources. + +Example: + +``` +temporal cloud account audit-log sink pubsub validate \ + --name my-sink \ + --service-account-id my-sa \ + --topic-name my-topic \ + --gcp-project-id my-project +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--gcp-project-id` | Yes | **string** The GCP project ID of the PubSub topic and service account. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--service-account-id` | Yes | **string** The GCP service account ID that Temporal Cloud impersonates for writing records to the customer's PubSub topic. | +| `--topic-name` | Yes | **string** The destination PubSub topic name where audit logs will be sent. | + +## Global Flags + +The following options can be used with any command. + +| Flag | Required | Description | Default | +|------|----------|-------------|--------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | | +| `--auto-confirm` | No | **bool** Automatically confirm prompts and actions that require user confirmation. Useful for scripting and automation. | | +| `--config-dir` | No | **string** Directory path where CLI configuration files are stored, including authentication tokens and settings. | | +| `--disable-pop-up` | No | **bool** Prevent the CLI from opening a browser window during authentication. Useful for headless environments or when using alternative auth methods. | | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | `saas-api.tmprl-test.cloud:443` | + diff --git a/docs/cli/command-reference/cloud/apikey.mdx b/docs/cli/command-reference/cloud/apikey.mdx new file mode 100644 index 0000000000..63c1f4d59c --- /dev/null +++ b/docs/cli/command-reference/cloud/apikey.mdx @@ -0,0 +1,253 @@ +--- +id: apikey +title: Temporal CLI cloud apikey command reference +sidebar_label: apikey +description: API Key Management Commands +toc_max_heading_level: 4 +keywords: + - apikey + - api-key + - management +tags: + - apikeys +--- + +{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten. +This file is generated from https://github.com/temporalio/cli via cmd/gen-docs */} + +This page provides a reference for the `temporal cloud apikey` commands. The flags applicable to each subcommand are presented in a table within the heading for the subcommand. Refer to [Global Flags](#global-flags) for flags that you can use with every subcommand. + +## create-for-me + +Create a new API key owned by the currently authenticated user. +The token is printed once on creation and cannot be retrieved again. + +Example: + +``` +cloud apikey create-for-me --display-name "My Key" +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--description` | No | **string** An optional description for the API key. | +| `--display-name` | Yes | **string** A human-readable display name for the API key. | +| `--expiry-duration` | No | **duration** Expiry duration relative to now (e.g. 30d, 24h, 90m). Supports days (d), hours (h), minutes (m), and seconds (s). Mutually exclusive with --expiry-time. | +| `--expiry-time` | No | **timestamp** Expiry time for the API key in RFC3339 format (e.g. 2025-12-31T00:00:00Z). Mutually exclusive with --expiry-duration. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## create-for-service-account + +Create a new API key owned by the specified service account. +The token is printed once on creation and cannot be retrieved again. + +Example: + +``` +cloud apikey create-for-service-account --service-account-id my-sa-id --display-name "My Key" +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--description` | No | **string** An optional description for the API key. | +| `--display-name` | Yes | **string** A human-readable display name for the API key. | +| `--expiry-duration` | No | **duration** Expiry duration relative to now (e.g. 30d, 24h, 90m). Supports days (d), hours (h), minutes (m), and seconds (s). Mutually exclusive with --expiry-time. | +| `--expiry-time` | No | **timestamp** Expiry time for the API key in RFC3339 format (e.g. 2025-12-31T00:00:00Z). Mutually exclusive with --expiry-duration. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--service-account-id` | Yes | **string** The ID of the service account to create the API key for. | + +## delete + +Delete a Temporal Cloud API key. This action is irreversible. + +Example: + +``` +cloud apikey delete --key-id my-key-id +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--key-id` | Yes | **string** The ID of the API key to delete. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## disable + +Disable a Temporal Cloud API key. Disabled keys cannot be used for authentication. + +Example: + +``` +cloud apikey disable --key-id my-key-id +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--key-id` | Yes | **string** The ID of the API key to disable. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## edit + +Open an API key configuration in your default editor for interactive +modification. After saving and closing the editor, the changes are +applied to Temporal Cloud. + +The editor is determined by the EDITOR environment variable, falling +back to 'vi' if not set. + +Example: + +``` +cloud apikey edit --key-id my-key-id +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--key-id` | Yes | **string** The ID of the API key to edit. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--verbose-diff` | No | **bool** Show detailed differences between the current and desired namespace configurations when changes are detected. | + +## enable + +Enable a previously disabled Temporal Cloud API key. + +Example: + +``` +cloud apikey enable --key-id my-key-id +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--key-id` | Yes | **string** The ID of the API key to enable. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## get + +Retrieve the configuration and status of a Temporal Cloud API key. + +Example: + +``` +cloud apikey get --key-id my-key-id +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--key-id` | Yes | **string** The ID of the API key to retrieve. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## list + +List API keys. Optionally filter by user ID, user email, or service account ID. +At most one filter may be specified. + +Example: + +``` +cloud apikey list +cloud apikey list --user-id my-user-id +cloud apikey list --service-account-id my-sa-id +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--page-size` | No | **int** Number of API keys to return per page. | +| `--page-token` | No | **string** Token for retrieving the next page of results. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--service-account-id` | No | **string** Filter API keys by service account ID. Mutually exclusive with --user-id and --user-email. | +| `--user-email` | No | **string** Filter API keys by user email. Mutually exclusive with --user-id and --service-account-id. | +| `--user-id` | No | **string** Filter API keys by user ID. Mutually exclusive with --user-email and --service-account-id. | + +## update + +Update an API key's display name, description, or disabled status. +Only flags that are explicitly provided are changed. + +Example: + +``` +cloud apikey update --key-id my-key-id --display-name "New Name" +cloud apikey update --key-id my-key-id --disabled=true +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--description` | No | **string** New description for the API key. | +| `--disabled` | No | **bool** Set to true to disable the API key, or false to enable it. | +| `--display-name` | No | **string** New display name for the API key. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--key-id` | Yes | **string** The ID of the API key to update. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## Global Flags + +The following options can be used with any command. + +| Flag | Required | Description | Default | +|------|----------|-------------|--------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | | +| `--auto-confirm` | No | **bool** Automatically confirm prompts and actions that require user confirmation. Useful for scripting and automation. | | +| `--config-dir` | No | **string** Directory path where CLI configuration files are stored, including authentication tokens and settings. | | +| `--disable-pop-up` | No | **bool** Prevent the CLI from opening a browser window during authentication. Useful for headless environments or when using alternative auth methods. | | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | `saas-api.tmprl-test.cloud:443` | + diff --git a/docs/cli/command-reference/cloud/connectivity.mdx b/docs/cli/command-reference/cloud/connectivity.mdx new file mode 100644 index 0000000000..df9a076e50 --- /dev/null +++ b/docs/cli/command-reference/cloud/connectivity.mdx @@ -0,0 +1,144 @@ +--- +id: connectivity +title: Temporal CLI cloud connectivity command reference +sidebar_label: connectivity +description: Connectivity Management Commands +toc_max_heading_level: 4 +keywords: + - connectivity + - connectivity-rule +tags: + - connectivity +--- + +{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten. +This file is generated from https://github.com/temporalio/cli via cmd/gen-docs */} + +This page provides a reference for the `temporal cloud connectivity` commands. The flags applicable to each subcommand are presented in a table within the heading for the subcommand. Refer to [Global Flags](#global-flags) for flags that you can use with every subcommand. + +## delete + +Delete a connectivity rule by its ID. + +Example: + +``` +cloud connectivity delete --id +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--id` | Yes | **string** The ID of the connectivity rule. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## get + +Get details of a specific connectivity rule by its ID. + +Example: + +``` +cloud connectivity get --id +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--id` | Yes | **string** The ID of the connectivity rule. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## list + +List connectivity rules, optionally filtered by namespace. + +Example: + +``` +cloud connectivity list --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--namespace`, `-n` | No | **string** Filter connectivity rules by namespace (e.g., 'my-namespace.my-account'). | +| `--page-size` | No | **int** Number of connectivity rules to return per page. | +| `--page-token` | No | **string** Page token for pagination. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## private + +Commands for managing private connectivity rules. + +### private create + +Create a new private VPC connectivity rule. Requires --connection-id and --region. + +Example: + +``` +cloud connectivity private create --connection-id vpce-12345 --region aws-us-west-2 +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--connection-id` | Yes | **string** The connection ID for private connectivity. | +| `--gcp-project-id` | No | **string** The GCP project ID (only for GCP private connectivity). | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--region` | Yes | **string** The region for private connectivity. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## public + +Commands for managing public connectivity rules. + +### public create + +Create a new public internet connectivity rule. + +Example: + +``` +cloud connectivity public create +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## Global Flags + +The following options can be used with any command. + +| Flag | Required | Description | Default | +|------|----------|-------------|--------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | | +| `--auto-confirm` | No | **bool** Automatically confirm prompts and actions that require user confirmation. Useful for scripting and automation. | | +| `--config-dir` | No | **string** Directory path where CLI configuration files are stored, including authentication tokens and settings. | | +| `--disable-pop-up` | No | **bool** Prevent the CLI from opening a browser window during authentication. Useful for headless environments or when using alternative auth methods. | | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | `saas-api.tmprl-test.cloud:443` | + diff --git a/docs/cli/command-reference/cloud/index.mdx b/docs/cli/command-reference/cloud/index.mdx new file mode 100644 index 0000000000..0a5549b83a --- /dev/null +++ b/docs/cli/command-reference/cloud/index.mdx @@ -0,0 +1,27 @@ +--- +id: index +title: Temporal CLI cloud command reference +sidebar_label: Overview +description: Command reference for the temporal cloud extension. +slug: /cli/command-reference/cloud +toc_max_heading_level: 4 +keywords: + - temporal cli + - cloud + - command reference +tags: + - Temporal CLI +--- + +This section includes the command reference for the `temporal cloud` CLI extension. + +- [account](/cli/command-reference/cloud/account) +- [apikey](/cli/command-reference/cloud/apikey) +- [connectivity](/cli/command-reference/cloud/connectivity) +- [login](/cli/command-reference/cloud/login) +- [logout](/cli/command-reference/cloud/logout) +- [namespace](/cli/command-reference/cloud/namespace) +- [nexus](/cli/command-reference/cloud/nexus) +- [user](/cli/command-reference/cloud/user) +- [user-group](/cli/command-reference/cloud/user-group) +- [whoami](/cli/command-reference/cloud/whoami) diff --git a/docs/cli/command-reference/cloud/login.mdx b/docs/cli/command-reference/cloud/login.mdx new file mode 100644 index 0000000000..3d79a3ad91 --- /dev/null +++ b/docs/cli/command-reference/cloud/login.mdx @@ -0,0 +1,40 @@ +--- +id: login +title: Temporal CLI cloud login command reference +sidebar_label: login +description: Login +toc_max_heading_level: 4 +keywords: + - login + - authentication + - auth +tags: + - login +--- + +{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten. +This file is generated from https://github.com/temporalio/cli via cmd/gen-docs */} + +This page provides a reference for the `temporal cloud login` command. + +Authenticate with Temporal Cloud using browser-based OAuth login. + +This command opens your default browser to complete authentication. Once +logged in, your credentials are stored locally for subsequent commands. + +Example: + +``` +cloud login +``` + +For headless environments, use --disable-pop-up and follow the printed URL. + +| Flag | Required | Description | +|------|----------|-------------| +| `--audience` | No | **string** OAuth audience parameter for token generation. | +| `--client-id` | No | **string** OAuth client identifier for authentication. | +| `--domain` | No | **string** Authentication domain for the OAuth provider. | +| `--redirect-url` | No | **string** Redirect URL for OAuth authentication flow. | +| `--reset` | No | **bool** Clear stored login credentials and configuration, then re-authenticate. Use this if you need to switch accounts or fix authentication issues. | + diff --git a/docs/cli/command-reference/cloud/logout.mdx b/docs/cli/command-reference/cloud/logout.mdx new file mode 100644 index 0000000000..dc56c21389 --- /dev/null +++ b/docs/cli/command-reference/cloud/logout.mdx @@ -0,0 +1,32 @@ +--- +id: logout +title: Temporal CLI cloud logout command reference +sidebar_label: logout +description: Logout +toc_max_heading_level: 4 +keywords: + - logout + - authentication + - auth +tags: + - login +--- + +{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten. +This file is generated from https://github.com/temporalio/cli via cmd/gen-docs */} + +This page provides a reference for the `temporal cloud logout` command. + +Log out from Temporal Cloud by clearing stored authentication tokens +and credentials from the local configuration. + +Example: + +``` +cloud logout +``` + +| Flag | Required | Description | +|------|----------|-------------| +| `--domain` | No | **string** Authentication domain for the OAuth provider. | + diff --git a/docs/cli/command-reference/cloud/namespace.mdx b/docs/cli/command-reference/cloud/namespace.mdx new file mode 100644 index 0000000000..eb5e516915 --- /dev/null +++ b/docs/cli/command-reference/cloud/namespace.mdx @@ -0,0 +1,1148 @@ +--- +id: namespace +title: Temporal CLI cloud namespace command reference +sidebar_label: namespace +description: Namespace Management Commands +toc_max_heading_level: 4 +keywords: + - namespace + - management +tags: + - namespaces +--- + +{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten. +This file is generated from https://github.com/temporalio/cli via cmd/gen-docs */} + +This page provides a reference for the `temporal cloud namespace` commands. The flags applicable to each subcommand are presented in a table within the heading for the subcommand. Refer to [Global Flags](#global-flags) for flags that you can use with every subcommand. + +## apply + +Apply a namespace configuration to Temporal Cloud. Creates a new namespace +if it doesn't exist, or updates an existing one to match the specification. + +The specification can be provided as inline JSON or loaded from a file +by prefixing the path with '@'. + +Example with inline JSON: + +``` +cloud namespace apply --spec '{"name": "namespace-name", "region": "us-west-2", "retention_days": 7}' +``` + +Example with file path: + +``` +cloud namespace apply --spec @namespace-spec.json +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the namespace already matches the specification. Without this flag, the command errors when no changes are needed. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--spec` | Yes | **string** Namespace configuration in JSON format. Provide inline JSON directly, or use '@path/to/file.json' to load from a file. | +| `--verbose-diff` | No | **bool** Show detailed differences between the current and desired namespace configurations when changes are detected. | + +## cert-ca + +Commands for managing the client CA certificates of Temporal Cloud namespaces. + +### cert-ca create + +Add client CA certificates to a Temporal Cloud namespace from a PEM file +or base64 encoded string. These certificates are used to verify client +connections and enable mTLS authentication. + +Specify either --ca-certificate-file or --ca-certificate, but not both. + +Example with file: + +``` +cloud namespace cert-ca create --namespace my-namespace.my-account --ca-certificate-file ca-cert.pem +``` + +Example with base64 encoded data: + +``` +cloud namespace cert-ca create --namespace my-namespace.my-account --ca-certificate +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--ca-certificate` | No | **string** Base64-encoded CA certificate for mTLS authentication. Mutually exclusive with --ca-certificate-file. | +| `--ca-certificate-file` | No | **string** Path to a CA certificate PEM file for mTLS authentication. Mutually exclusive with --ca-certificate. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### cert-ca delete + +Delete client CA certificates from a Temporal Cloud namespace. This operation +requires confirmation and will remove the specified certificates from the +namespace configuration. + +Specify either --ca-certificate-file or --ca-certificate, but not both. + +Example with file: + +``` +cloud namespace cert-ca delete --namespace my-namespace.my-account --ca-certificate-file ca-cert.pem +``` + +Example with base64 encoded data: + +``` +cloud namespace cert-ca delete --namespace my-namespace.my-account --ca-certificate +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--ca-certificate` | No | **string** Base64-encoded CA certificate for mTLS authentication. Mutually exclusive with --ca-certificate-file. | +| `--ca-certificate-file` | No | **string** Path to a CA certificate PEM file for mTLS authentication. Mutually exclusive with --ca-certificate. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### cert-ca list + +Retrieve the list of client CA certificates configured for a Temporal Cloud +namespace. These certificates are used for client authentication. + +Example: + +``` +cloud namespace cert-ca list --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## cert-filter + +Commands for managing certificate filters for Temporal Cloud namespaces. +Certificate filters restrict mTLS connections to client certificates with +specific distinguished name properties. + +### cert-filter create + +Add new certificate filters to a Temporal Cloud namespace. Certificate +filters restrict mTLS connections to client certificates whose distinguished +name properties match at least one of the filters. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--common-name` | No | **string** The common name (CN) field from the certificate's distinguished name. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--organization` | No | **string** The organization (O) field from the certificate's distinguished name. | +| `--organizational-unit` | No | **string** The organizational unit (OU) field from the certificate's distinguished name. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--subject-alternative-name` | No | **string** The subject alternative name (SAN) from the certificate. | + +### cert-filter delete + +Delete certificate filters from a Temporal Cloud namespace. Filters are +matched by exact field equality. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--common-name` | No | **string** The common name (CN) field from the certificate's distinguished name. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--organization` | No | **string** The organization (O) field from the certificate's distinguished name. | +| `--organizational-unit` | No | **string** The organizational unit (OU) field from the certificate's distinguished name. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--subject-alternative-name` | No | **string** The subject alternative name (SAN) from the certificate. | + +### cert-filter list + +List all certificate filters configured for a Temporal Cloud namespace. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## codec + +Commands for managing the codec server configuration of Temporal Cloud namespaces. + +The codec server is used to encode and decode payloads for workflows and activities. + +### codec delete + +Delete the codec server configuration from a Temporal Cloud namespace. + +Example: + +``` +cloud namespace codec delete --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### codec get + +Retrieve the current codec server configuration for a Temporal Cloud namespace. + +Example: + +``` +cloud namespace codec get --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### codec set + +Set the codec server configuration for a Temporal Cloud namespace. + +Example: + +``` +cloud namespace codec set --namespace my-namespace.my-account --endpoint https://my-codec.example.com +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--custom-error-message-default-link` | No | **string** A link to display alongside the custom error message for remote codec server errors. | +| `--custom-error-message-default-message` | No | **string** A custom message to display for remote codec server errors. | +| `--endpoint` | Yes | **string** The codec server endpoint URL. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--include-cross-origin-credentials` | No | **bool** Whether to include cross-origin credentials in requests to the codec server. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--pass-access-token` | No | **bool** Whether to pass the user access token to the codec server endpoint. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## create + +Create a new Temporal Cloud namespace with the specified configuration. + +Options are passed as individual flags. To create or update a namespace +using a full JSON specification, use 'namespace apply' instead. + +Example: + +``` +cloud namespace create --name my-namespace --region aws-us-east-1 --retention-days 30 +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--api-key-auth-enabled` | No | **bool** Enable API key authentication for the namespace. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--ca-certificate` | No | **string** Base64-encoded CA certificate for mTLS authentication. Mutually exclusive with --ca-certificate-file. | +| `--ca-certificate-file` | No | **string** Path to a CA certificate PEM file for mTLS authentication. Mutually exclusive with --ca-certificate. | +| `--certificate-filter` | No | **string[]** Certificate filter as a JSON object (e.g. `'{"commonName":"foo"}'`). Repeat to add multiple. | +| `--certificate-filter-file` | No | **string** Path to a JSON file containing a certificate filter object. | +| `--codec-endpoint` | No | **string** HTTPS codec server endpoint URL. | +| `--codec-include-cross-origin-credentials` | No | **bool** Include cross-origin credentials in codec server requests. | +| `--codec-pass-access-token` | No | **bool** Pass the user access token to the codec server endpoint. | +| `--connection-rule-id` | No | **string[]** Private connectivity rule ID. Repeat to specify multiple. | +| `--enable-delete-protection` | No | **bool** Prevent accidental deletion of this namespace. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name`, `-n` | Yes | **string** The name for the new namespace (becomes part of the namespace ID). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--region` | Yes | **string[]** Cloud region where the namespace will be hosted. Repeat to specify multiple regions for High Availability (e.g. --region aws-us-east-1 --region aws-us-west-2). | +| `--retention-days` | No | **int** Number of days to retain closed workflow history. If not specified, the server default applies. | +| `--search-attribute` | No | **string[]** Custom search attribute as 'name=Type' (e.g. --search-attribute myAttr=Keyword). Valid types: Text, Keyword, Int, Double, Bool, Datetime, KeywordList. Repeat to add multiple. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## delete + +Delete a Temporal Cloud namespace and all associated data. This action is +irreversible and will permanently remove all workflows, activities, and +history within the namespace. + +Example: + +``` +cloud namespace delete --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the namespace does not exist. Without this flag, the command errors if the namespace is not found. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## edit + +Open a namespace configuration in your default editor for interactive +modification. After saving and closing the editor, the changes are +applied to Temporal Cloud. + +The editor is determined by the EDITOR environment variable, falling +back to 'vi' if not set. + +Example: + +``` +cloud namespace edit --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if no changes were made in the editor. Without this flag, the command errors when the configuration is unchanged. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--verbose-diff` | No | **bool** Show detailed differences between the current and desired namespace configurations when changes are detected. | + +## export + +Commands for managing workflow history export sinks for Temporal Cloud namespaces. + +Export sinks define destinations (S3 or GCS) to which workflow history is exported. + +### export delete + +Delete a workflow history export sink from a Temporal Cloud namespace. + +Example: + +``` +cloud namespace export delete --namespace my-namespace.my-account --sink-name my-sink +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--sink-name` | Yes | **string** The name of the export sink. | + +### export disable + +Disable a workflow history export sink for a Temporal Cloud namespace. +The sink configuration is preserved and can be re-enabled later. + +Example: + +``` +cloud namespace export disable --namespace my-namespace.my-account --sink-name my-sink +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--sink-name` | Yes | **string** The name of the export sink. | + +### export enable + +Enable a previously disabled workflow history export sink for a Temporal Cloud namespace. + +Example: + +``` +cloud namespace export enable --namespace my-namespace.my-account --sink-name my-sink +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--sink-name` | Yes | **string** The name of the export sink. | + +### export gcs + +Commands for managing GCS workflow history export sinks for Temporal Cloud namespaces. + +#### export gcs create + +Create a new GCS workflow history export sink for a Temporal Cloud namespace. +The sink is created in the enabled state. + +Example: + +``` +cloud namespace export gcs create --namespace my-namespace.my-account --sink-name my-sink \ + --sa-id my-service-account@my-project.iam.gserviceaccount.com \ + --bucket-name my-bucket --gcp-project-id my-project --region us-central1 +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--bucket-name` | Yes | **string** The name of the destination GCS bucket. | +| `--gcp-project-id` | Yes | **string** The GCP project ID associated with the bucket and service account. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--region` | Yes | **string** The GCS bucket region. | +| `--sa-id` | Yes | **string** The customer service account ID that Temporal Cloud impersonates for writing to GCS. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--sink-name` | Yes | **string** The name of the export sink. | + +#### export gcs update + +Update the configuration of an existing GCS workflow history export sink. +The enabled/disabled state is preserved. + +Example: + +``` +cloud namespace export gcs update --namespace my-namespace.my-account --sink-name my-sink \ + --sa-id my-service-account@my-project.iam.gserviceaccount.com \ + --bucket-name my-bucket --gcp-project-id my-project --region us-central1 +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--bucket-name` | Yes | **string** The name of the destination GCS bucket. | +| `--gcp-project-id` | Yes | **string** The GCP project ID associated with the bucket and service account. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--region` | Yes | **string** The GCS bucket region. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--sa-id` | Yes | **string** The customer service account ID that Temporal Cloud impersonates for writing to GCS. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--sink-name` | Yes | **string** The name of the export sink. | + +#### export gcs validate + +Validate a GCS workflow history export sink configuration without creating or updating it. +A successful response means the configuration is valid. + +Example: + +``` +cloud namespace export gcs validate --namespace my-namespace.my-account --sink-name my-sink \ + --sa-id my-service-account@my-project.iam.gserviceaccount.com \ + --bucket-name my-bucket --gcp-project-id my-project --region us-central1 +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--bucket-name` | Yes | **string** The name of the destination GCS bucket. | +| `--gcp-project-id` | Yes | **string** The GCP project ID associated with the bucket and service account. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--region` | Yes | **string** The GCS bucket region. | +| `--sa-id` | Yes | **string** The customer service account ID that Temporal Cloud impersonates for writing to GCS. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--sink-name` | Yes | **string** The name of the export sink. | + +### export get + +Retrieve the configuration and status of a workflow history export sink for a +Temporal Cloud namespace. + +Example: + +``` +cloud namespace export get --namespace my-namespace.my-account --sink-name my-sink +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--sink-name` | Yes | **string** The name of the export sink. | + +### export list + +List all workflow history export sinks configured for a Temporal Cloud namespace. + +Example: + +``` +cloud namespace export list --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### export s3 + +Commands for managing S3 workflow history export sinks for Temporal Cloud namespaces. + +#### export s3 create + +Create a new S3 workflow history export sink for a Temporal Cloud namespace. +The sink is created in the enabled state. + +Example: + +``` +cloud namespace export s3 create --namespace my-namespace.my-account --sink-name my-sink \ + --role-name arn:aws:iam::123456789012:role/my-role --bucket-name my-bucket \ + --region us-east-1 --aws-account-id 123456789012 +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--aws-account-id` | Yes | **string** The AWS account ID associated with the bucket and role. | +| `--bucket-name` | Yes | **string** The name of the destination S3 bucket. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--kms-arn` | No | **string** The AWS KMS key ARN for server-side encryption of exported data. Optional. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--region` | Yes | **string** The AWS region where the S3 bucket is located. | +| `--role-name` | Yes | **string** The IAM role ARN that Temporal Cloud assumes for writing to S3. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--sink-name` | Yes | **string** The name of the export sink. | + +#### export s3 update + +Update the configuration of an existing S3 workflow history export sink. +The enabled/disabled state is preserved. + +Example: + +``` +cloud namespace export s3 update --namespace my-namespace.my-account --sink-name my-sink \ + --role-name arn:aws:iam::123456789012:role/my-new-role --bucket-name my-bucket \ + --region us-east-1 --aws-account-id 123456789012 +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--aws-account-id` | Yes | **string** The AWS account ID associated with the bucket and role. | +| `--bucket-name` | Yes | **string** The name of the destination S3 bucket. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--kms-arn` | No | **string** The AWS KMS key ARN for server-side encryption of exported data. Optional. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--region` | Yes | **string** The AWS region where the S3 bucket is located. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--role-name` | Yes | **string** The IAM role ARN that Temporal Cloud assumes for writing to S3. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--sink-name` | Yes | **string** The name of the export sink. | + +#### export s3 validate + +Validate an S3 workflow history export sink configuration without creating or updating it. +A successful response means the configuration is valid. + +Example: + +``` +cloud namespace export s3 validate --namespace my-namespace.my-account --sink-name my-sink \ + --role-name arn:aws:iam::123456789012:role/my-role --bucket-name my-bucket \ + --region us-east-1 --aws-account-id 123456789012 +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--aws-account-id` | Yes | **string** The AWS account ID associated with the bucket and role. | +| `--bucket-name` | Yes | **string** The name of the destination S3 bucket. | +| `--kms-arn` | No | **string** The AWS KMS key ARN for server-side encryption of exported data. Optional. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--region` | Yes | **string** The AWS region where the S3 bucket is located. | +| `--role-name` | Yes | **string** The IAM role ARN that Temporal Cloud assumes for writing to S3. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--sink-name` | Yes | **string** The name of the export sink. | + +## get + +Retrieve the configuration and status of a Temporal Cloud namespace. + +Returns details including region, retention period, endpoints, and +certificate information. + +Example: + +``` +cloud namespace get --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--spec` | No | **bool** Output only the namespace specification in JSON format, omitting metadata and status information. | + +## ha + +Commands for managing High Availability (HA) settings of Temporal Cloud namespaces. + +HA settings control active region, managed failover, and replica regions. + +### ha failover + +Trigger a failover for a Temporal Cloud namespace to a different region. +The target region must already be a replica region of the namespace. + +Example: + +``` +cloud namespace ha failover --namespace my-namespace.my-account --region aws-us-west-2 +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--region` | Yes | **string** The target region to failover to (e.g., aws-us-west-2). | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### ha get + +Retrieve the current High Availability configuration for a Temporal Cloud namespace. +Shows the active region and whether managed failover is enabled. + +Example: + +``` +cloud namespace ha get --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### ha region + +Commands for managing replica regions of Temporal Cloud namespaces. + +#### ha region add + +Add a replica region to a Temporal Cloud namespace. The region will be added +as a passive replica and can later be used for failover. + +Example: + +``` +cloud namespace ha region add --namespace my-namespace.my-account --region aws-us-west-2 +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--region` | Yes | **string** The region ID to add as a replica (e.g., aws-us-west-2). | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +#### ha region delete + +Remove a replica region from a Temporal Cloud namespace. Note that a 7-day +cooldown period applies before the same region can be re-added. + +Example: + +``` +cloud namespace ha region delete --namespace my-namespace.my-account --region aws-us-west-2 +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--region` | Yes | **string** The region ID to remove (e.g., aws-us-west-2). | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +#### ha region list + +List all regions and their states for a Temporal Cloud namespace. + +Example: + +``` +cloud namespace ha region list --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### ha update + +Update the High Availability configuration for a Temporal Cloud namespace. +Use --disable-auto-failover to toggle Temporal-managed automatic failover. + +Example: + +``` +cloud namespace ha update --namespace my-namespace.my-account --disable-auto-failover true +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--disable-auto-failover` | Yes | **bool** Set to true to disable Temporal-managed automatic failover for the namespace. Set to false to re-enable automatic failover. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## lifecycle + +Commands for managing lifecycle settings of Temporal Cloud namespaces. + +Lifecycle settings control the behavior and protection of namespaces, +including delete protection to prevent accidental deletion. + +### lifecycle get + +Retrieve the current lifecycle configuration for a Temporal Cloud namespace. +Lifecycle settings include delete protection status. + +Example: + +``` +cloud namespace lifecycle get --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### lifecycle set + +Set the lifecycle configuration for a Temporal Cloud namespace. +Lifecycle settings include delete protection to prevent accidental deletion. + +Example: + +``` +cloud namespace lifecycle set --namespace my-namespace.my-account --enable-delete-protection true +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--enable-delete-protection` | Yes | **bool** Enable or disable delete protection for the namespace. When enabled, the namespace cannot be deleted until this flag is set to false. | +| `--idempotent` | No | **bool** Succeed silently if the lifecycle configuration is already set to the specified value. Without this flag, the command errors when no change is needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--resource-version` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--verbose-diff` | No | **bool** Show detailed differences between the current and desired namespace configurations when changes are detected. | + +## list + +List all Temporal Cloud namespaces accessible with the current +authentication credentials. + +Example: + +``` +cloud namespace list +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--name` | No | **string** Filter namespaces by the name as defined in the specification of the namespace. | +| `--page-size` | No | **int** Number of namespaces to return per page. Use for paginated results. | +| `--page-token` | No | **string** Token for retrieving the next page of results in a paginated list. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## retention + +Commands for managing data retention settings of Temporal Cloud namespaces. + +Retention determines how long closed workflow history data are stored before +being automatically deleted. + +### retention get + +Retrieve the current data retention period for a Temporal Cloud namespace. +The retention period defines how long closed workflow history data are stored. + +Example: + +``` +cloud namespace retention get --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### retention set + +Set the data retention period for a Temporal Cloud namespace. The +retention period defines how long closed workflow history data are stored. + +Example: + +``` +cloud namespace retention set --namespace my-namespace.my-account --retention-days 14 +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--retention-days` | Yes | **int** New retention period in days for closed workflow history data. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## search-attribute + +Commands for managing custom search attributes for Temporal Cloud namespaces. +Search attributes enable filtering and searching workflows by custom fields. + +### search-attribute create + +Create a new custom search attribute for a Temporal Cloud namespace. + +Example: + +``` +cloud namespace search-attribute create --namespace my-namespace.my-account --name MyField --type Keyword +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** The name of the search attribute to create. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--type` | Yes | **string** The type of the search attribute. Valid values: Text, Keyword, Int, Double, Bool, Datetime, KeywordList. | + +### search-attribute list + +List all custom search attributes configured for a Temporal Cloud namespace. + +Example: + +``` +cloud namespace search-attribute list --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### search-attribute rename + +Rename an existing custom search attribute for a Temporal Cloud namespace. +This operation preserves all existing data associated with the search attribute. + +Example: + +``` +cloud namespace search-attribute rename --namespace my-namespace.my-account --existing-name OldField --new-name NewField +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--existing-name` | Yes | **string** The current name of the search attribute to rename. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--new-name` | Yes | **string** The new name for the search attribute. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## tag + +Commands for managing tags of Temporal Cloud namespaces. + +Tags are key-value pairs used for organization and categorization of namespaces. + +### tag create + +Create a new tag for a Temporal Cloud namespace. Fails if a tag with +the specified key already exists. + +Example: + +``` +cloud namespace tag create --namespace my-namespace.my-account --key environment --value production +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--key` | Yes | **string** The tag key. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--value` | Yes | **string** The tag value. | + +### tag delete + +Delete a tag from a Temporal Cloud namespace by its key. + +Example: + +``` +cloud namespace tag delete --namespace my-namespace.my-account --key environment +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--key` | Yes | **string** The tag key to delete. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### tag list + +List all tags configured for a Temporal Cloud namespace. + +Example: + +``` +cloud namespace tag list --namespace my-namespace.my-account +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### tag update + +Update the value of an existing tag for a Temporal Cloud namespace. +Fails if the specified tag key does not exist. + +Example: + +``` +cloud namespace tag update --namespace my-namespace.my-account --key environment --value staging +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--key` | Yes | **string** The tag key to update. | +| `--namespace`, `-n` | Yes | **string** The fully qualified namespace name in the format 'namespace.account' (e.g., 'my-namespace.my-account'). | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--value` | Yes | **string** The new value for the tag. | + +## Global Flags + +The following options can be used with any command. + +| Flag | Required | Description | Default | +|------|----------|-------------|--------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | | +| `--auto-confirm` | No | **bool** Automatically confirm prompts and actions that require user confirmation. Useful for scripting and automation. | | +| `--config-dir` | No | **string** Directory path where CLI configuration files are stored, including authentication tokens and settings. | | +| `--disable-pop-up` | No | **bool** Prevent the CLI from opening a browser window during authentication. Useful for headless environments or when using alternative auth methods. | | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | `saas-api.tmprl-test.cloud:443` | + diff --git a/docs/cli/command-reference/cloud/nexus.mdx b/docs/cli/command-reference/cloud/nexus.mdx new file mode 100644 index 0000000000..5341d64fd4 --- /dev/null +++ b/docs/cli/command-reference/cloud/nexus.mdx @@ -0,0 +1,212 @@ +--- +id: nexus +title: Temporal CLI cloud nexus command reference +sidebar_label: nexus +description: Nexus Operations Management Commands +toc_max_heading_level: 4 +keywords: + - nexus +tags: + - nexus +--- + +{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten. +This file is generated from https://github.com/temporalio/cli via cmd/gen-docs */} + +This page provides a reference for the `temporal cloud nexus` commands. The flags applicable to each subcommand are presented in a table within the heading for the subcommand. Refer to [Global Flags](#global-flags) for flags that you can use with every subcommand. + +## endpoint + +Commands for managing Nexus Endpoints in Temporal Cloud. + +### endpoint allowed-namespace + +Commands for managing allowed namespaces for Nexus Endpoints. + +#### endpoint allowed-namespace add + +Add namespaces that are allowed to call this Nexus Endpoint. +Namespaces that are already allowed are silently ignored. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** The name of the Nexus Endpoint. | +| `--namespace` | Yes | **string[]** A namespace to allow. Can be specified multiple times. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +#### endpoint allowed-namespace list + +List all namespaces that are allowed to call this Nexus Endpoint. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--name` | Yes | **string** The name of the Nexus Endpoint. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +#### endpoint allowed-namespace remove + +Remove namespaces from the list of allowed callers of this Nexus Endpoint. +Namespaces that are not currently allowed are silently ignored. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** The name of the Nexus Endpoint. | +| `--namespace` | Yes | **string[]** A namespace to remove. Can be specified multiple times. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +#### endpoint allowed-namespace set + +Set the full list of namespaces that are allowed to call this Nexus Endpoint, +replacing any previously allowed namespaces. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** The name of the Nexus Endpoint. | +| `--namespace` | Yes | **string[]** A namespace to allow. Can be specified multiple times. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### endpoint create + +Create a new Nexus Endpoint on the Cloud Account. +An endpoint name is used in workflow code to invoke Nexus operations. +The endpoint target is a worker and `--target-namespace` and `--target-task-queue` +must both be provided. This will fail if an endpoint with the same name is already registered. + +Example: + +``` +cloud nexus endpoint create --name my-endpoint --target-namespace my-ns.my-account --target-task-queue my-tq +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--allow-namespace` | No | **string[]** A namespace that is allowed to call this endpoint. Can be specified multiple times. | +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--description` | No | **string** An optional endpoint description in markdown format. | +| `--description-file` | No | **string** Path to a file containing an endpoint description in markdown format. Mutually exclusive with --description. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** The name of the Nexus Endpoint to create. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--target-namespace` | Yes | **string** The namespace in which a handler worker will be polling for Nexus tasks. | +| `--target-task-queue` | Yes | **string** The task queue on which a handler worker will be polling for Nexus tasks. | + +### endpoint delete + +Delete a Nexus Endpoint on the Cloud Account. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** The name of the Nexus Endpoint to delete. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### endpoint get + +This command gets a Nexus Endpoint configuration by name from the Cloud Account. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--name` | Yes | **string** The name of the Nexus Endpoint to retrieve. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### endpoint list + +List all Nexus Endpoint configurations on the Cloud Account. + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--page-size` | No | **int** Number of endpoints to return per page. | +| `--page-token` | No | **string** Token for retrieving the next page of results. Initial value is empty string. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### endpoint update + +Update an existing Nexus Endpoint on the Cloud Account. +An endpoint name is used in workflow code to invoke Nexus operations. +The endpoint target is a worker and `--target-namespace` and `--target-task-queue` +must both be provided. + +The endpoint is patched leaving any existing fields for which flags are not provided +as they were. + +Example: + +``` +cloud nexus endpoint update --name my-endpoint --target-namespace new-ns.my-account --target-task-queue new-tq +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--description` | No | **string** An optional endpoint description in markdown format. | +| `--description-file` | No | **string** Path to a file containing an endpoint description in markdown format. Mutually exclusive with --description. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--name` | Yes | **string** The name of the Nexus Endpoint to update. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--target-namespace` | No | **string** The namespace in which a handler worker will be polling for Nexus tasks. | +| `--target-task-queue` | No | **string** The task queue on which a handler worker will be polling for Nexus tasks. | +| `--unset-description` | No | **bool** Unset the endpoint description. Cannot be used with --description or --description-file. | + +## Global Flags + +The following options can be used with any command. + +| Flag | Required | Description | Default | +|------|----------|-------------|--------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | | +| `--auto-confirm` | No | **bool** Automatically confirm prompts and actions that require user confirmation. Useful for scripting and automation. | | +| `--config-dir` | No | **string** Directory path where CLI configuration files are stored, including authentication tokens and settings. | | +| `--disable-pop-up` | No | **bool** Prevent the CLI from opening a browser window during authentication. Useful for headless environments or when using alternative auth methods. | | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | `saas-api.tmprl-test.cloud:443` | + diff --git a/docs/cli/command-reference/cloud/user-group.mdx b/docs/cli/command-reference/cloud/user-group.mdx new file mode 100644 index 0000000000..0bea76e917 --- /dev/null +++ b/docs/cli/command-reference/cloud/user-group.mdx @@ -0,0 +1,417 @@ +--- +id: user-group +title: Temporal CLI cloud user-group command reference +sidebar_label: user-group +description: User Group Management Commands +toc_max_heading_level: 4 +keywords: + - user-group + - management +tags: + - user-groups +--- + +{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten. +This file is generated from https://github.com/temporalio/cli via cmd/gen-docs */} + +This page provides a reference for the `temporal cloud user-group` commands. The flags applicable to each subcommand are presented in a table within the heading for the subcommand. Refer to [Global Flags](#global-flags) for flags that you can use with every subcommand. + +## apply + +Apply a user group configuration to Temporal Cloud. Creates a new user group +if no group with the given display name exists, or updates the existing one +to match the specification. + +The specification can be provided as inline JSON or loaded from a file +by prefixing the path with '@'. + +Example with inline JSON: + +``` +cloud user-group apply --spec '{"display_name": "Engineering", "cloud_group": {}, "access": {"account_access": {"role": "developer"}}}' +``` + +Example with file path: + +``` +cloud user-group apply --spec @user-group-spec.json +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--spec` | Yes | **string** User group configuration in JSON format. Provide inline JSON directly, or use '@path/to/file.json' to load from a file. | +| `--verbose-diff` | No | **bool** Show detailed differences between the current and desired namespace configurations when changes are detected. | + +## create-cloud-group + +Create a new Temporal Cloud-managed user group. Members can be managed +using the add-member and remove-member commands. + +Account roles: owner, admin, developer, finance-admin, read, metrics-read. +Namespace access format: 'namespace=permission' where permission is one of: admin, write, read. + +Example: + +``` +cloud user-group create-cloud-group --display-name "Engineering" \ + --account-role developer \ + --namespace-access my-namespace.my-account=write +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--account-role` | No | **string** The account-level role to assign. Valid values: owner, admin, developer, finance-admin, read, metrics-read. | +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--display-name` | Yes | **string** The display name of the user group. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace-access` | No | **string[]** Namespace access to grant, in the format 'namespace=permission'. Permission must be one of: admin, write, read. Can be repeated. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## create-google-group + +Create a new user group backed by a Google Group. Members are managed +via the Google Group itself. + +Account roles: owner, admin, developer, finance-admin, read, metrics-read. +Namespace access format: 'namespace=permission' where permission is one of: admin, write, read. + +Example: + +``` +cloud user-group create-google-group --display-name "Platform" \ + --google-group-email platform@example.com \ + --account-role developer +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--account-role` | No | **string** The account-level role to assign. Valid values: owner, admin, developer, finance-admin, read, metrics-read. | +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--display-name` | Yes | **string** The display name of the user group. | +| `--google-group-email` | Yes | **string** The email address of the Google Group. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace-access` | No | **string[]** Namespace access to grant, in the format 'namespace=permission'. Permission must be one of: admin, write, read. Can be repeated. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## create-scim-group + +Create a new user group backed by a SCIM identity provider group. +Members are managed via the upstream identity provider. + +Account roles: owner, admin, developer, finance-admin, read, metrics-read. +Namespace access format: 'namespace=permission' where permission is one of: admin, write, read. + +Example: + +``` +cloud user-group create-scim-group --display-name "Security" \ + --scim-idp-id idp-group-id-123 \ + --account-role read +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--account-role` | No | **string** The account-level role to assign. Valid values: owner, admin, developer, finance-admin, read, metrics-read. | +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--display-name` | Yes | **string** The display name of the user group. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace-access` | No | **string[]** Namespace access to grant, in the format 'namespace=permission'. Permission must be one of: admin, write, read. Can be repeated. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--scim-idp-id` | Yes | **string** The identity provider ID for the SCIM group. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## delete + +Delete a Temporal Cloud user group. This action is irreversible. + +Example: + +``` +cloud user-group delete --group-id my-group-id +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--group-id` | Yes | **string** The ID of the user group. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## edit + +Open a user group configuration in your default editor for interactive +modification. After saving and closing the editor, the changes are +applied to Temporal Cloud. + +The editor is determined by the EDITOR environment variable, falling +back to 'vi' if not set. + +Example: + +``` +cloud user-group edit --group-id my-group-id +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--group-id` | Yes | **string** The ID of the user group. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--verbose-diff` | No | **bool** Show detailed differences between the current and desired namespace configurations when changes are detected. | + +## get + +Retrieve the configuration and status of a Temporal Cloud user group. + +Example: + +``` +cloud user-group get --group-id my-group-id +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--group-id` | Yes | **string** The ID of the user group. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## list + +List all Temporal Cloud user groups accessible with the current +authentication credentials. + +Example: + +``` +cloud user-group list +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--display-name` | No | **string** Filter user groups by display name. | +| `--google-group-email-address` | No | **string** Filter user groups by Google group email address. | +| `--namespace` | No | **string** Filter user groups by the namespace they have access to. | +| `--page-size` | No | **int** Number of user groups to return per page. Use for paginated results. | +| `--page-token` | No | **string** Token for retrieving the next page of results in a paginated list. | +| `--scim-group-idp-id` | No | **string** Filter user groups by SCIM group IDP ID. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## members + +Commands for managing members of Temporal Cloud user groups. + +### members add + +Add a user to a Temporal Cloud user group. + +Specify the user with either --user-id or --user-email (not both). + +Example: + +``` +cloud user-group members add --group-id my-group-id --user-id my-user-id +cloud user-group members add --group-id my-group-id --user-email alice@example.com +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--group-id` | Yes | **string** The ID of the user group. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--user-email` | No | **string** The email address of the user. Mutually exclusive with --user-id. | +| `--user-id` | No | **string** The ID of the user. Mutually exclusive with --user-email. | + +### members list + +List all members of a Temporal Cloud user group. + +Example: + +``` +cloud user-group members list --group-id my-group-id +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--group-id` | Yes | **string** The ID of the user group. | +| `--page-size` | No | **int** Number of members to return per page. Use for paginated results. | +| `--page-token` | No | **string** Token for retrieving the next page of results in a paginated list. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +### members remove + +Remove a user from a Temporal Cloud user group. + +Specify the user with either --user-id or --user-email (not both). + +Example: + +``` +cloud user-group members remove --group-id my-group-id --user-id my-user-id +cloud user-group members remove --group-id my-group-id --user-email alice@example.com +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--group-id` | Yes | **string** The ID of the user group. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--user-email` | No | **string** The email address of the user. Mutually exclusive with --user-id. | +| `--user-id` | No | **string** The ID of the user. Mutually exclusive with --user-email. | + +## set-account-role + +Set the account-level role for a Temporal Cloud user group. + +Account roles: owner, admin, developer, finance-admin, read, metrics-read. + +Example: + +``` +cloud user-group set-account-role --group-id my-group-id --account-role developer +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--account-role` | Yes | **string** The account-level role to assign. Valid values: owner, admin, developer, finance-admin, read, metrics-read. | +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--group-id` | Yes | **string** The ID of the user group. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## set-namespace-permissions + +Add, update, or remove namespace-level permissions for a Temporal Cloud user group. +Changes are applied additively: namespaces not listed are left unchanged. + +Namespace access format: 'namespace=permission' where permission is one of: admin, write, read. +To remove access to a namespace, pass an empty permission: 'namespace='. + +Example: + +``` +cloud user-group set-namespace-permissions --group-id my-group-id \ + --namespace-access my-namespace.my-account=write \ + --namespace-access other-namespace.my-account=read +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--group-id` | Yes | **string** The ID of the user group. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace-access` | Yes | **string[]** Namespace access change in the format 'namespace=permission'. Permission must be one of: admin, write, read. Can be repeated. Use an empty permission (e.g. 'testns=') to remove access to a namespace. Changes are additive: namespaces not listed are left unchanged. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## update + +Update an existing Temporal Cloud user group's access settings. + +Provide at least one of --account-role or --namespace-access. + +Example: + +``` +cloud user-group update --group-id my-group-id --account-role developer +cloud user-group update --group-id my-group-id \ + --namespace-access my-namespace.my-account=write +cloud user-group update --group-id my-group-id --account-role admin \ + --namespace-access my-namespace.my-account=write \ + --namespace-access other-namespace.my-account=read +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--account-role` | No | **string** The account role to assign to the group. Role must be one of: admin, developer, finance-admin, read. | +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--group-id` | Yes | **string** The ID of the user group. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace-access` | No | **string[]** Namespace access change in the format 'namespace=permission'. Permission must be one of: admin, write, read. Can be repeated. Use an empty permission (e.g. 'testns=') to remove access to a namespace. Changes are additive: namespaces not listed are left unchanged. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## Global Flags + +The following options can be used with any command. + +| Flag | Required | Description | Default | +|------|----------|-------------|--------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | | +| `--auto-confirm` | No | **bool** Automatically confirm prompts and actions that require user confirmation. Useful for scripting and automation. | | +| `--config-dir` | No | **string** Directory path where CLI configuration files are stored, including authentication tokens and settings. | | +| `--disable-pop-up` | No | **bool** Prevent the CLI from opening a browser window during authentication. Useful for headless environments or when using alternative auth methods. | | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | `saas-api.tmprl-test.cloud:443` | + diff --git a/docs/cli/command-reference/cloud/user.mdx b/docs/cli/command-reference/cloud/user.mdx new file mode 100644 index 0000000000..e204ab53a4 --- /dev/null +++ b/docs/cli/command-reference/cloud/user.mdx @@ -0,0 +1,262 @@ +--- +id: user +title: Temporal CLI cloud user command reference +sidebar_label: user +description: User Management Commands +toc_max_heading_level: 4 +keywords: + - user + - management +tags: + - users +--- + +{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten. +This file is generated from https://github.com/temporalio/cli via cmd/gen-docs */} + +This page provides a reference for the `temporal cloud user` commands. The flags applicable to each subcommand are presented in a table within the heading for the subcommand. Refer to [Global Flags](#global-flags) for flags that you can use with every subcommand. + +## apply + +Apply a user configuration to Temporal Cloud. Creates a new user invitation +if the email does not exist, or updates the existing user to match the specification. + +The specification can be provided as inline JSON or loaded from a file +by prefixing the path with '@'. + +Example with inline JSON: + +``` +cloud user apply --spec '{"email": "alice@example.com", "access": {"account_access": {"role": "developer"}}}' +``` + +Example with file path: + +``` +cloud user apply --spec @user-spec.json +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--spec` | Yes | **string** User configuration in JSON format. Provide inline JSON directly, or use '@path/to/file.json' to load from a file. | +| `--verbose-diff` | No | **bool** Show detailed differences between the current and desired namespace configurations when changes are detected. | + +## delete + +Delete a Temporal Cloud user. This action is irreversible. + +Specify the user with either --user-id or --user-email (not both). + +Example: + +``` +cloud user delete --user-id my-user-id +cloud user delete --user-email alice@example.com +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--user-email` | No | **string** The email address of the user. Mutually exclusive with --user-id. | +| `--user-id` | No | **string** The ID of the user. Mutually exclusive with --user-email. | + +## edit + +Open a user configuration in your default editor for interactive +modification. After saving and closing the editor, the changes are +applied to Temporal Cloud. + +The editor is determined by the EDITOR environment variable, falling +back to 'vi' if not set. + +Specify the user with either --user-id or --user-email (not both). + +Example: + +``` +cloud user edit --user-id my-user-id +cloud user edit --user-email alice@example.com +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--user-email` | No | **string** The email address of the user. Mutually exclusive with --user-id. | +| `--user-id` | No | **string** The ID of the user. Mutually exclusive with --user-email. | +| `--verbose-diff` | No | **bool** Show detailed differences between the current and desired namespace configurations when changes are detected. | + +## get + +Retrieve the configuration and status of a Temporal Cloud user. + +Example: + +``` +cloud user get --user-id my-user-id +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--user-email` | No | **string** The email address of the user. Mutually exclusive with --user-id. | +| `--user-id` | No | **string** The ID of the user. Mutually exclusive with --user-email. | + +## invite + +Invite a user to Temporal Cloud by email. Optionally assign an account-level +role and namespace-level access permissions. + +Account roles: owner, admin, developer, finance-admin, read, metrics-read. +Namespace access format: 'namespace=permission' where permission is one of: admin, write, read. + +Example: + +``` +cloud user invite --email alice@example.com --account-role developer \ + --namespace-access my-namespace.my-account=write +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--account-role` | No | **string** The account-level role to assign. Valid values: owner, admin, developer, finance-admin, read, metrics-read. | +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--email` | Yes | **string** The email address of the user to invite. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace-access` | No | **string[]** Namespace access to grant, in the format 'namespace=permission'. Permission must be one of: admin, write, read. Can be repeated. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## list + +List all Temporal Cloud users accessible with the current +authentication credentials. + +Example: + +``` +cloud user list +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--email` | No | **string** Filter users by email address. | +| `--namespace` | No | **string** Filter users by the namespace they have access to. | +| `--page-size` | No | **int** Number of users to return per page. Use for paginated results. | +| `--page-token` | No | **string** Token for retrieving the next page of results in a paginated list. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + +## set-account-role + +Set the account-level role for a Temporal Cloud user. + +Account roles: owner, admin, developer, finance-admin, read, metrics-read. + +Specify the user with either --user-id or --user-email (not both). + +Example: + +``` +cloud user set-account-role --user-id my-user-id --account-role developer +cloud user set-account-role --user-email alice@example.com --account-role admin +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--account-role` | Yes | **string** The account-level role to assign. Valid values: owner, admin, developer, finance-admin, read, metrics-read. | +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--user-email` | No | **string** The email address of the user. Mutually exclusive with --user-id. | +| `--user-id` | No | **string** The ID of the user. Mutually exclusive with --user-email. | + +## set-namespace-permissions + +Add, update, or remove namespace-level permissions for a Temporal Cloud user. +Changes are applied additively: namespaces not listed are left unchanged. + +Namespace access format: 'namespace=permission' where permission is one of: admin, write, read. +To remove access to a namespace, pass an empty permission: 'namespace='. + +Specify the user with either --user-id or --user-email (not both). + +Example: + +``` +# Grant write access to my-namespace and read access to other-namespace: +cloud user set-namespace-permissions --user-id my-user-id \ + --namespace-access my-namespace.my-account=write \ + --namespace-access other-namespace.my-account=read + +# Remove access to a namespace: +cloud user set-namespace-permissions --user-id my-user-id \ + --namespace-access my-namespace.my-account= +``` + +Use the following options to change the behavior of this command. You can also use any of the [global flags](#global-flags) that apply to all subcommands. + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--async` | No | **bool** Return immediately after initiating the operation instead of waiting for completion. Use the returned operation ID to check status later. | +| `--async-operation-id` | No | **string** Custom identifier for tracking this async operation. If not provided, a unique ID is generated automatically. | +| `--idempotent` | No | **bool** Succeed silently if the resource already exists or matches the specification. Without this flag, the command errors when no changes are needed. | +| `--namespace-access` | Yes | **string[]** Namespace access change in the format 'namespace=permission'. Permission must be one of: admin, write, read. Can be repeated. Use an empty permission (e.g. 'testns=') to remove access to a namespace. Changes are additive: namespaces not listed are left unchanged. | +| `--poll-interval` | No | **duration** Time to wait between status checks when waiting for operation completion. Cannot be greater than 10 minutes. Supports minutes (m) and seconds (s). Default is 1s. | +| `--resource-version`, `-v` | No | **string** Resource version for optimistic concurrency control. If not provided, the current version is fetched automatically. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | +| `--user-email` | No | **string** The email address of the user. Mutually exclusive with --user-id. | +| `--user-id` | No | **string** The ID of the user. Mutually exclusive with --user-email. | + +## Global Flags + +The following options can be used with any command. + +| Flag | Required | Description | Default | +|------|----------|-------------|--------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | | +| `--auto-confirm` | No | **bool** Automatically confirm prompts and actions that require user confirmation. Useful for scripting and automation. | | +| `--config-dir` | No | **string** Directory path where CLI configuration files are stored, including authentication tokens and settings. | | +| `--disable-pop-up` | No | **bool** Prevent the CLI from opening a browser window during authentication. Useful for headless environments or when using alternative auth methods. | | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | `saas-api.tmprl-test.cloud:443` | + diff --git a/docs/cli/command-reference/cloud/whoami.mdx b/docs/cli/command-reference/cloud/whoami.mdx new file mode 100644 index 0000000000..6f7043e363 --- /dev/null +++ b/docs/cli/command-reference/cloud/whoami.mdx @@ -0,0 +1,35 @@ +--- +id: whoami +title: Temporal CLI cloud whoami command reference +sidebar_label: whoami +description: Who Am I +toc_max_heading_level: 4 +keywords: + - whoami + - identity + - authentication +tags: + - authentication +--- + +{/* NOTE: This is an auto-generated file. Any edit to this file will be overwritten. +This file is generated from https://github.com/temporalio/cli via cmd/gen-docs */} + +This page provides a reference for the `temporal cloud whoami` command. + +Display information about the currently authenticated identity. + +Shows whether you are authenticated as a user or service account, along +with the associated API key if one is in use. + +Example: + +``` +cloud whoami +``` + +| Flag | Required | Description | +|------|----------|-------------| +| `--api-key` | No | **string** API key for authenticating with Temporal Cloud. Can be used instead of interactive login for automation and CI/CD pipelines. | +| `--server` | No | **string** Override the Temporal Cloud API server address. Used for connecting to non-production environments. | + diff --git a/docs/cli/cmd-options.mdx b/docs/cli/command-reference/cmd-options.mdx similarity index 99% rename from docs/cli/cmd-options.mdx rename to docs/cli/command-reference/cmd-options.mdx index a1d4f084dc..f558aeb011 100644 --- a/docs/cli/cmd-options.mdx +++ b/docs/cli/command-reference/cmd-options.mdx @@ -476,7 +476,7 @@ Promote local Namespace to Global Namespace. ## query Provides a SQL-like Query of Search Attributes to return Workflow Executions to reset. For more information, refer to -the [`temporal workflow list`](/cli/workflow#list) command. +the [`temporal workflow list`](/cli/command-reference/workflow#list) command. ## raw diff --git a/docs/cli/config.mdx b/docs/cli/command-reference/config.mdx similarity index 100% rename from docs/cli/config.mdx rename to docs/cli/command-reference/config.mdx diff --git a/docs/cli/env.mdx b/docs/cli/command-reference/env.mdx similarity index 100% rename from docs/cli/env.mdx rename to docs/cli/command-reference/env.mdx diff --git a/docs/cli/command-reference/index.mdx b/docs/cli/command-reference/index.mdx new file mode 100644 index 0000000000..c479803987 --- /dev/null +++ b/docs/cli/command-reference/index.mdx @@ -0,0 +1,36 @@ +--- +id: index +title: Temporal CLI command reference +sidebar_label: Overview +description: Complete command reference for the Temporal CLI, including the cloud extension. +slug: /cli/command-reference +toc_max_heading_level: 4 +keywords: + - temporal cli + - command reference +tags: + - Temporal CLI +--- + +This section includes the complete command reference for the `temporal` CLI, including the cloud extension. + +- [activity](/cli/command-reference/activity) +- [batch](/cli/command-reference/batch) +- [cloud account](/cli/command-reference/cloud/account) +- [cloud apikey](/cli/command-reference/cloud/apikey) +- [cloud connectivity](/cli/command-reference/cloud/connectivity) +- [cloud login](/cli/command-reference/cloud/login) +- [cloud logout](/cli/command-reference/cloud/logout) +- [cloud namespace](/cli/command-reference/cloud/namespace) +- [cloud nexus](/cli/command-reference/cloud/nexus) +- [cloud user](/cli/command-reference/cloud/user) +- [cloud user-group](/cli/command-reference/cloud/user-group) +- [cloud whoami](/cli/command-reference/cloud/whoami) +- [config](/cli/command-reference/config) +- [env](/cli/command-reference/env) +- [operator](/cli/command-reference/operator) +- [schedule](/cli/command-reference/schedule) +- [server](/cli/command-reference/server) +- [task-queue](/cli/command-reference/task-queue) +- [worker](/cli/command-reference/worker) +- [workflow](/cli/command-reference/workflow) diff --git a/docs/cli/operator.mdx b/docs/cli/command-reference/operator.mdx similarity index 100% rename from docs/cli/operator.mdx rename to docs/cli/command-reference/operator.mdx diff --git a/docs/cli/schedule.mdx b/docs/cli/command-reference/schedule.mdx similarity index 100% rename from docs/cli/schedule.mdx rename to docs/cli/command-reference/schedule.mdx diff --git a/docs/cli/server.mdx b/docs/cli/command-reference/server.mdx similarity index 100% rename from docs/cli/server.mdx rename to docs/cli/command-reference/server.mdx diff --git a/docs/cli/task-queue.mdx b/docs/cli/command-reference/task-queue.mdx similarity index 100% rename from docs/cli/task-queue.mdx rename to docs/cli/command-reference/task-queue.mdx diff --git a/docs/cli/worker.mdx b/docs/cli/command-reference/worker.mdx similarity index 100% rename from docs/cli/worker.mdx rename to docs/cli/command-reference/worker.mdx diff --git a/docs/cli/workflow.mdx b/docs/cli/command-reference/workflow.mdx similarity index 100% rename from docs/cli/workflow.mdx rename to docs/cli/command-reference/workflow.mdx diff --git a/docs/cli/index.mdx b/docs/cli/index.mdx index 39bba67d13..d50be86792 100644 --- a/docs/cli/index.mdx +++ b/docs/cli/index.mdx @@ -1,10 +1,10 @@ --- id: index -title: Temporal CLI command reference +title: Temporal CLI sidebar_label: Temporal CLI description: - The Temporal CLI offers terminal access to Temporal Services for managing, monitoring, and debugging Workflows and - Activities, including Namespace and Task Queue management, with embedded development support. + The Temporal CLI provides terminal access to Temporal Services for managing, monitoring, and debugging Workflows and + Activities, plus embedded development support. slug: /cli toc_max_heading_level: 4 keywords: @@ -17,494 +17,35 @@ tags: - Temporal CLI --- -The Temporal CLI provides direct access to a Temporal Service via the terminal. It's a powerful tool for managing, -monitoring, and debugging Temporal Applications. You can use it to start, stop, inspect and operate on Workflows and -Activities, and perform administrative tasks such as Namespace, Schedule, and Task Queue management. +The Temporal CLI (`temporal`) provides direct access to a Temporal Service via the terminal. Use it to manage, monitor, +and debug Temporal applications, plus run an embedded development service when you need fast local feedback. -The Temporal CLI also includes an embedded Temporal Service suitable for use in development and CI/CD. It includes the -[Temporal Server](/temporal-service/temporal-server), SQLite persistence, and the [Temporal Web UI](/web-ui). +In addition, we provide and maintain an official extension for the Temporal CLI you can use to interact with Temporal +Cloud. Use the extension to manage your Temporal Cloud control plane resources, including Namespaces, Users, Service +Accounts, API keys, and perform other operational and administrative tasks. -:::note +## Install and configure the CLI -When upgrading from [tctl](/tctl-v1) to the Temporal CLI, make sure to update your environment variables and use updated -commands. For details, see [CLI release notes](https://github.com/temporalio/cli/releases/). +Install the CLI and cloud extension, run a local development server, and configure your environment in +[Install and configure the CLI](/cli/setup-cli). -::: +## Use with Temporal Cloud -## Install the Temporal CLI {#install} +Connect toTemporal Cloud with [environment configuration](/develop/environment-configuration) and use the Cloud +extension to manage your Temporal Cloud control plane resources in [Use with Temporal Cloud](/cli/temporal-cloud). -The Temporal CLI is available on macOS, Windows, and Linux, or as a Docker image. +## Start a development server {#start-dev-server} -### macOS - -Choose one of the following install methods to install the Temporal CLI on macOS: - -- Install the Temporal CLI with Homebrew. - -```shell -brew install temporal -``` - -- Install the Temporal CLI from CDN. - - 1. Select the platform and architecture needed. - - - Download for Darwin amd64: https://temporal.download/cli/archive/latest?platform=darwin&arch=amd64 - - Download for Darwin arm64: https://temporal.download/cli/archive/latest?platform=darwin&arch=arm64 - - 2. Extract the downloaded archive. - - 3. Add the Temporal CLI binary to your PATH. - -### Linux - -Choose one of the following install methods to install the Temporal CLI on Linux: - -- Install the Temporal CLI from CDN. - - 1. Select the platform and architecture needed. - - - Download for Linux amd64: https://temporal.download/cli/archive/latest?platform=linux&arch=amd64 - - Download for Linux arm64: https://temporal.download/cli/archive/latest?platform=linux&arch=arm64 - - 2. Extract the downloaded archive. - - 3. Add the `temporal` binary to your PATH. - -### Windows - -Choose one of the following methods to install the Temporal CLI on Windows: - -- Install the Temporal CLI from CDN. - - 1. Select the platform and architecture needed and download the binary. - - - Download for Windows amd64: https://temporal.download/cli/archive/latest?platform=windows&arch=amd64 - - Download for Windows arm64: https://temporal.download/cli/archive/latest?platform=windows&arch=arm64 - - 2. Extract the downloaded archive. - - 3. Add the `temporal.exe` binary to your PATH. - -### Docker - -The Temporal CLI container image is available on [DockerHub](https://hub.docker.com/r/temporalio/temporal) and can be -run directly: - -```shell -docker run --rm temporalio/temporal --help -``` - -:::note - -When running the Temporal CLI inside Docker, for the development server to be accessible from the host system, the -server needs to be configured to listen on external IP and the ports need to be forwarded: - -```shell -docker run --rm -p 7233:7233 -p 8233:8233 temporalio/temporal server start-dev --ip 0.0.0.0 -# UI is now accessible from host at http://localhost:8233/ -``` - -::: - -## Start a Temporal development server {#start-dev-server} - -To start a Temporal development server, run the following command: +The CLI includes a local Temporal development service for fast feedback while building or testing your application. ```bash temporal server start-dev ``` -This command automatically starts the Web UI, creates the `default` [Namespace](/namespaces), and uses an in-memory -database. - -The Temporal Server will be available on `localhost:7233` and the Temporal Web UI will be available at -[`http://localhost:8233`](http://localhost:8233/). - -The in-memory SQLite database does not persist if you stop the development server. Use the `--db-filename` option to -specify a database file, persisting application state. This is helpful if you plan on stopping and re-starting the -development server. - -```shell -temporal server start-dev --db-filename temporal.db -``` - -:::note - -Local databases created with `--db-filename` may not be compatible with newer versions of the Temporal CLI. The -`temporal server start-dev` command is only intended for development environments. - -::: +## CLI basics -For the full list of development server options, use the `--help` flag: - -```shell -temporal server start-dev --help -``` - -## Enable auto-completion {#enable-auto-completion} - -Enable auto-completion using the following commands. - -### zsh auto-completion - -1. Add the following line to your `~/.zshrc` startup script: - - ```sh - eval "$(temporal completion zsh)" - ``` - -2. Re-launch your shell or run: - - ```sh - source ~/.zshrc - ``` - -### Bash auto-completion - -1. Install [bash-completion](https://github.com/scop/bash-completion#installation) and add the software to your - `~/.bashrc`. - -2. Add the following line to your `~/.bashrc` startup script: - - ```sh - eval "$(temporal completion bash)" - ``` - -3. Re-launch your shell or run: - - ```sh - source ~/.bashrc - ``` - -:::note - -If auto-completion fails with the error: `bash: _get_comp_words_by_ref: command not found`, you did not successfully -install [bash-completion](https://github.com/scop/bash-completion#installation). This package must be loaded into your -shell for `temporal` auto-completion to work. - -::: - -### Fish auto-completion - -1. Create the Fish custom completions directory if it does not already exist: - - ```fish - mkdir -p ~/.config/fish/completions - ``` - -2. Configure the completions to load when needed. Note: the file name must be `temporal.fish` or the completions will - not be found: - - ```fish - echo 'eval "$(temporal completion fish)"' >~/.config/fish/completions/temporal.fish - ``` - -3. Re-launch your shell or run: - - ```fish - source ~/.config/fish/completions/temporal.fish - ``` - -## Command set - -- [temporal activity](/cli/activity/) -- [temporal batch](/cli/batch/) -- [temporal env](/cli/env/) -- [temporal operator](/cli/operator/) -- [temporal schedule](/cli/schedule/) -- [temporal server](/cli/server) -- [temporal task-queue](/cli/task-queue/) -- [temporal workflow](/cli/workflow/) - -## Configuration - -The following information provides important configuration details. - -### Namespace registration - -Namespaces are pre-registered at startup for immediate use. Customize pre-registered Namespaces with the following -command: - -```shell -temporal server start-dev --namespace foo --namespace bar -``` - -Register Namespaces with `namespace create`: - -```shell -temporal operator namespace create --namespace foo -``` - -### Enable or disable Temporal UI - -By default, the Temporal UI is enabled when running the development server using the Temporal CLI. To disable the UI, -use the `--headless` modifier: - -```shell -temporal server start-dev --headless -``` +Get started with the basics of the CLI in [CLI basics](/cli/common-operations). -### Dynamic configuration +## Command reference -Advanced Temporal CLI configuration requires a dynamic configuration file. - -To set values on the command line, use `--dynamic-config-value KEY=JSON_VALUE`. For example, enable the Search Attribute -cache: - -```bash -temporal server start-dev --dynamic-config-value system.forceSearchAttributesCacheRefreshOnRead=false -``` - -This setting makes created Search Attributes immediately available. - -## Environment variables - -The following table describes the environment variables you can set for the Temporal CLI. - - - -| Variable | Definition | Client Option | -| ---------------------------------------- | ------------------------------------------------------------------------- | ------------------------------- | -| `TEMPORAL_ADDRESS` | Host and port (formatted as host:port) for the Temporal Frontend Service. | --address | -| `TEMPORAL_CODEC_AUTH` | Authorization header for requests to Codec Server. | --codec-auth | -| `TEMPORAL_CODEC_ENDPOINT` | Endpoint for remote Codec Server. | --codec-endpoint | -| `TEMPORAL_NAMESPACE` | Namespace in Temporal Workflow. Default: "default". | --namespace | -| `TEMPORAL_TLS_CA` | Path to server CA certificate. | --tls-ca-path | -| `TEMPORAL_TLS_CERT` | Path to x509 certificate. | --tls-cert-path | -| `TEMPORAL_TLS_DISABLE_HOST_VERIFICATION` | Disables TLS host name verification. Default: false. | --tls-disable-host-verification | -| `TEMPORAL_TLS_KEY` | Path to private certificate key. | --tls-key-path | -| `TEMPORAL_TLS_SERVER_NAME` | Override for target TLS server name. | --tls-server-name | -| `TEMPORAL_API_KEY` | API key used for authentication. | --api-key | - - - - -:::tip ENVIRONMENT VARIABLES - -Do not confuse environment variables, set with your shell, with temporal env options. - -::: - -## Create and modify configuration files {#configuration-files} - -The Temporal CLI lets you create and modify TOML configuration files to store your environment variables and other -settings. Refer to [Environment Configuration](../develop/environment-configuration#cli-integration) for more -information. - -## Proxy support - -The Temporal CLI provides support for users who are operating behind a proxy. This feature ensures seamless -communication even in network-restricted environments. - -#### Setting up proxy support - -If you are behind a proxy, you'll need to instruct the Temporal CLI to route its requests via that proxy. You can -achieve this by setting the `HTTPS_PROXY` environment variable. - -```command -export HTTPS_PROXY=: -``` - -Replace `` with the proxy's hostname or IP address, and `` with the proxy's port number. - -Once set, you can run the Temporal CLI commands as you normally would. - -:::note - -Temporal CLI uses the gRPC library which natively supports HTTP CONNECT proxies. The gRPC library checks for the -`HTTPS_PROXY` (and its case-insensitive variants) environment variable to determine if it should route requests through -a proxy. - -::: - -In addition to `HTTPS_PROXY`, gRPC also respects the `NO_PROXY` environment variable. This can be useful if there are -specific addresses or domains you wish to exclude from proxying. - -For more information, see [Proxy](https://github.com/grpc/grpc-go/blob/master/Documentation/proxy.md) in the gRPC -documentation. - -## Common CLI operations {#common-operations} - -The following are some of the more common operations you can perform with the Temporal CLI. - -### Start a Workflow - -In another terminal, use the following commands to interact with the Server. The following command starts a Workflow: - -```shell -$ temporal workflow start \ - --task-queue hello-world \ - --type MyWorkflow \ - --workflow-id 123 \ - --input 456 - -Running execution: - WorkflowId 123 - RunId 357074e4-0dd8-4c44-8367-d92536dd0943 - Type MyWorkflow - Namespace default - TaskQueue hello-world - Args [456] -``` - -Shorthand options are available: - -```shell -temporal workflow start --task-queue hello-world --type MyWorkflow --workflow-id 123 --input 456 -``` - -You can also list and describe Workflows: - -```shell -$ temporal workflow list - - Status WorkflowId Name StartTime - Running 123 MyWorkflow 14 seconds ago - -$ temporal workflow describe --workflow-id 123 - -{ - "executionConfig": { - "taskQueue": { - "name": "hello-world", - "kind": "Normal" - }, - "workflowExecutionTimeout": "0s", - "workflowRunTimeout": "0s", - "defaultWorkflowTaskTimeout": "10s" - }, - "workflowExecutionInfo": { - "execution": { - "workflowId": "123", - "runId": "357074e4-0dd8-4c44-8367-d92536dd0943" - }, - "type": { - "name": "MyWorkflow" - }, - "startTime": "2023-04-15T06:42:31.191137Z", - "status": "Running", - "historyLength": "2", - "executionTime": "2023-04-15T06:42:31.191137Z", - "memo": { - - }, - "autoResetPoints": { - - }, - "stateTransitionCount": "1" - }, - "pendingWorkflowTask": { - "state": "Scheduled", - "scheduledTime": "2023-04-15T06:42:31.191173Z", - "originalScheduledTime": "2023-04-15T06:42:31.191173Z", - "attempt": 1 - } -} -``` - -For more detailed output in JSON format, use the following command: - -```shell -$ temporal workflow list --output json - -[ - { - "execution": { - "workflow_id": "123", - "run_id": "357074e4-0dd8-4c44-8367-d92536dd0943" - }, - "type": { - "name": "MyWorkflow" - }, - "start_time": "2023-04-15T06:42:31.191137Z", - "status": 1, - "execution_time": "2023-04-15T06:42:31.191137Z", - "memo": {}, - "task_queue": "hello-world" - } -] -``` - -Filter out Workflows based on Workflow Type with [jq](https://stedolan.github.io/jq/): - -```shell -$ temporal workflow list --output json | jq '.[].type.name' - -"OtherWorkflow" -"MyWorkflow" -"MyWorkflow" -``` - -To count the number of Workflows, use the following command: - -```shell -$ temporal workflow list --output json | jq '.[].type.name' | uniq -c - - 1 "OtherWorkflow" - 2 "MyWorkflow" -``` - -To see the full range of Workflow-related commands, run `temporal workflow` or see the -[Temporal CLI workflow command reference](/cli/workflow). - -For a full list of available commands, run `temporal` without arguments or see [Available commands](#command-set). - -### Customize your environment variables - -To communicate with a different Server, like a production Namespace on Temporal Cloud: - -1. Create an environment named `prod`. -2. Pass `--env prod` to commands, like `temporal workflow list --env prod`. - -To create a new environment and set its properties: - -```shell -temporal env set prod.namespace production.f45a2 -temporal env set prod.address production.f45a2.tmprl.cloud:7233 -temporal env set prod.tls-cert-path /temporal/certs/prod.pem -temporal env set prod.tls-key-path /temporal/certs/prod.key -``` - -Check your settings: - -```shell -$ temporal env get prod - - address production.f45a2.tmprl.cloud:7233 - namespace production.f45a2 - tls-cert-path /temporal/certs/prod.pem - tls-key-path /temporal/certs/prod.key -``` - -Run a command to test the connection: - -```shell -$ temporal workflow list --env prod -``` - -For a full list of properties, use `temporal env set -h`. - -```shell -$ temporal env set -h - -OPTIONS: - Client Options: - - --address value The host and port (formatted as host:port) for the Temporal Frontend Service. [$TEMPORAL_CLI_ADDRESS] - --codec-auth value Sets the authorization header on requests to the Codec Server. [$TEMPORAL_CLI_CODEC_AUTH] - --codec-endpoint value Endpoint for a remote Codec Server. [$TEMPORAL_CLI_CODEC_ENDPOINT] - --command-timeout duration Timeout for the span of a command. (default 0s) - --env value Name of the environment to read environment variables from. (default: "default") - --grpc-meta value [ --grpc-meta value ] Contains gRPC metadata to send with requests (format: key=value). Values must be in a valid JSON format. - --namespace value, -n value Identifies a Namespace in the Temporal Workflow. (default: "default") [$TEMPORAL_CLI_NAMESPACE] - --tls-ca-path value Path to server CA certificate. [$TEMPORAL_CLI_TLS_CA] - --tls-cert-path value Path to x509 certificate. [$TEMPORAL_CLI_TLS_CERT] - --tls-disable-host-verification Disables TLS host name verification if already enabled. (default: false) [$TEMPORAL_CLI_TLS_DISABLE_HOST_VERIFICATION] - --tls-key-path value Path to private certificate key. [$TEMPORAL_CLI_TLS_KEY] - --tls-server-name value Provides an override for the target TLS server name. [$TEMPORAL_CLI_TLS_SERVER_NAME] - - Display Options: - - --color value when to use color: auto, always, never. (default: "auto") -``` +Refer to the [command reference](/cli/command-reference) for the complete list of commands. diff --git a/docs/cli/setup-cli.mdx b/docs/cli/setup-cli.mdx index cf1e2dcfd0..3c916d6a95 100644 --- a/docs/cli/setup-cli.mdx +++ b/docs/cli/setup-cli.mdx @@ -1,9 +1,9 @@ --- id: setup-cli -title: Set up the Temporal CLI -sidebar_label: Set up the CLI +title: Install and configure the CLI +sidebar_label: Install and configure slug: /cli/setup-cli -description: Install the Temporal CLI and run a local development server. +description: Install the Temporal CLI, run a local development server, and configure your environment. keywords: - Temporal CLI - Install CLI @@ -11,18 +11,8 @@ keywords: - Run dev server --- -The Temporal CLI is a command-line tool for interacting with the Temporal Service. -It helps you manage, monitor, and debug Temporal applications. -You can also use it to run a local development server and interact with Temporal Applications from the command line. - -With the Temporal CLI, you can: - -- Run a local Temporal Service for development -- Start Workflow Executions on any Temporal Service (local, self-hosted, or Temporal Cloud) -- Interact with running Workflows -- Inspect the state of Workflows and Activities -- Manage Namespaces, Schedules, and Task Queues -- Monitor and debug application behavior +The Temporal CLI is a command-line tool for interacting with the Temporal Service. It helps you manage, monitor, and +debug Temporal applications. ## Install the CLI @@ -43,7 +33,7 @@ Or download from the CDN: - [Darwin amd64](https://temporal.download/cli/archive/latest?platform=darwin&arch=amd64) - [Darwin arm64](https://temporal.download/cli/archive/latest?platform=darwin&arch=arm64) -Extract the archive and add the `temporal` binary to your `PATH`. +extract the archive and add the `temporal` binary to your `PATH`. @@ -66,7 +56,7 @@ Or download from the CDN: - [Linux amd64](https://temporal.download/cli/archive/latest?platform=linux&arch=amd64) - [Linux arm64](https://temporal.download/cli/archive/latest?platform=linux&arch=arm64) -Extract the archive and add the `temporal` binary to your `PATH`. +extract the archive and add the `temporal` binary to your `PATH`. @@ -77,73 +67,239 @@ Download from the CDN: - [Windows amd64](https://temporal.download/cli/archive/latest?platform=windows&arch=amd64) - [Windows arm64](https://temporal.download/cli/archive/latest?platform=windows&arch=arm64) -Extract the archive and add the `temporal.exe` binary to your `PATH`. +extract the archive and add the `temporal.exe` binary to your `PATH`. -Temporal CLI container image is available on [DockerHub](https://hub.docker.com/r/temporalio/temporal) and can be run directly: +Temporal CLI container image is available on [DockerHub](https://hub.docker.com/r/temporalio/temporal) and can be run +directly: ```shell docker run --rm temporalio/temporal --help ``` +::::note + +When running the Temporal CLI inside Docker, for the development server to be accessible from the host system, the +server needs to be configured to listen on external IP and the ports need to be forwarded: + +```shell +docker run --rm -p 7233:7233 -p 8233:8233 temporalio/temporal server start-dev --ip 0.0.0.0 +# UI is now accessible from host at http://localhost:8233/ +``` + +:::: + -## Run the development server +## Install the Temporal Cloud extension + +If you are using Temporal Cloud, install the Temporal Cloud extension for the Temporal CLI. You can install the +extension using the following command: + +:::tip Support, stability, and dependency info + +The Temporal Cloud extension is in [Pre-release](/evaluate/development-production-features/release-stages#pre-release). +APIs and configuration may change before the stable release. + +::: + +```bash +brew install temporal-cloud +``` + +## Run a local development server The CLI includes a local Temporal development service for fast feedback while building your application. Start the server: ```bash -temporal server start-dev \ - --db-filename path/to/local-persistent-store +temporal server start-dev ``` -View available options: +This command automatically starts the Web UI, creates the `default` [Namespace](/namespaces), and uses an in-memory +SQLite database. -```bash -temporal server start-dev \ - --help +The Temporal Server will be available on `localhost:7233` and the Temporal Web UI will be available at +[`http://localhost:8233`](http://localhost:8233/). + +Persist state locally by specifying a database file: + +```shell +temporal server start-dev --db-filename temporal.db ``` -:::note +### Development server configuration + +#### Namespace registration -When running the CLI inside Docker, for the development server to be accessible from the host system, -the server needs to be configured to listen on external IP and the ports need to be forwarded: +Namespaces are pre-registered at startup for immediate use. Customize pre-registered Namespaces with the following +command: ```shell -docker run --rm \ - -p 7233:7233 -p 8233:8233 \ - temporalio/temporal server start-dev \ - --ip 0.0.0.0 -# UI is now accessible from host at http://localhost:8233/ +temporal server start-dev --namespace foo --namespace bar ``` -::: +Register Namespaces with `namespace create`: -### What the local server provides +```shell +temporal operator namespace create --namespace foo +``` -- A local instance of the Temporal Service -- Automatic startup of the Web UI -- A default Namespace -- Optional persistence using SQLite +#### Enable or turn off the Temporal Web UI -Omitting `--db-filename` uses an in-memory database. This speeds up testing but does not persist Workflow data between sessions. +By default, the Temporal Web UI is enabled when running the development server using the Temporal CLI. To turn off the +UI, use the `--headless` modifier: -### Access the Web UI +```shell +temporal server start-dev --headless +``` -- Temporal Service: `localhost:7233` -- Web UI: [http://localhost:8233](http://localhost:8233) +#### Dynamic configuration -:::tip -The CLI works with all Temporal SDKs. -Use it to develop and test your application before deploying to production. -::: +Advanced Temporal CLI configuration requires a dynamic configuration file. + +To set values on the command line, use `--dynamic-config-value KEY=JSON_VALUE`. For example, enable the Search Attribute +cache: + +```bash +temporal server start-dev --dynamic-config-value system.forceSearchAttributesCacheRefreshOnRead=false +``` + +This setting makes created Search Attributes immediately available. + +## Configure the CLI + +### Environment variables + +The following table describes the environment variables you can set for the Temporal CLI. + +{/* This is an automatically generated file and the TEMPORAL_API_KEY correction will disappear on the next push. */} + +| Variable | Definition | Client Option | +| ---------------------------------------- | ------------------------------------------------------------------------- | ------------------------------- | +| `TEMPORAL_ADDRESS` | Host and port (formatted as host:port) for the Temporal Frontend Service. | --address | +| `TEMPORAL_CODEC_AUTH` | Authorization header for requests to Codec Server. | --codec-auth | +| `TEMPORAL_CODEC_ENDPOINT` | Endpoint for remote Codec Server. | --codec-endpoint | +| `TEMPORAL_NAMESPACE` | Namespace in Temporal Workflow. Default: "default". | --namespace | +| `TEMPORAL_TLS_CA` | Path to server CA certificate. | --tls-ca-path | +| `TEMPORAL_TLS_CERT` | Path to x509 certificate. | --tls-cert-path | +| `TEMPORAL_TLS_DISABLE_HOST_VERIFICATION` | Turns off TLS host name verification. Default: false. | --tls-disable-host-verification | +| `TEMPORAL_TLS_KEY` | Path to private certificate key. | --tls-key-path | +| `TEMPORAL_TLS_SERVER_NAME` | Override for target TLS server name. | --tls-server-name | +| `TEMPORAL_API_KEY` | API key used for authentication. | --api-key | + +{/* This is an automatically generated file and this caution will disappear on the next push. */} +{/* issue: https://github.com/temporalio/cli/issues/776 */} + +### Create and modify configuration files + + + +The Temporal CLI lets you create and modify TOML configuration files to store your environment variables and other +settings. Refer to [Environment Configuration](../develop/environment-configuration#cli-integration) for more +information. + +### Configure proxy support + +The Temporal CLI provides support for users who are operating behind a proxy. This feature ensures seamless +communication even in network-restricted environments. + +#### Setting up proxy support + +If you are behind a proxy, you'll need to instruct the Temporal CLI to route its requests via that proxy. You can +achieve this by setting the `HTTPS_PROXY` environment variable. + +```command +export HTTPS_PROXY=: +``` + +Replace `` with the proxy's hostname or IP address, and `` with the proxy's port number. + +Once set, you can run the Temporal CLI commands as you normally would. + +::::note + +Temporal CLI uses the gRPC library which natively supports HTTP CONNECT proxies. The gRPC library checks for the +`HTTPS_PROXY` (and its case-insensitive variants) environment variable to determine if it should route requests through +a proxy. + +:::: + +In addition to `HTTPS_PROXY`, gRPC also respects the `NO_PROXY` environment variable. This can be useful if there are +specific addresses or domains you wish to exclude from proxying. + +For more information, see [Proxy](https://github.com/grpc/grpc-go/blob/master/Documentation/proxy.md) in the gRPC +documentation. + +## Enable auto-completion + +Enable auto-completion using the following commands. + +### zsh auto-completion + +1. Add the following line to your `~/.zshrc` startup script: + + ```sh + eval "$(temporal completion zsh)" + ``` + +2. Re-launch your shell or run: + + ```sh + source ~/.zshrc + ``` + +### Bash auto-completion + +1. Install [bash-completion](https://github.com/scop/bash-completion#installation) and add the software to your + `~/.bashrc`. + +2. Add the following line to your `~/.bashrc` startup script: + + ```sh + eval "$(temporal completion bash)" + ``` + +3. Re-launch your shell or run: + + ```sh + source ~/.bashrc + ``` + +::::note + +If auto-completion fails with the error: `bash: _get_comp_words_by_ref: command not found`, you did not successfully +install [bash-completion](https://github.com/scop/bash-completion#installation). This package must be loaded into your +shell for `temporal` auto-completion to work. + +:::: + +### Fish auto-completion + +1. Create the Fish custom completions directory if it does not already exist: + + ```fish + mkdir -p ~/.config/fish/completions + ``` + +2. Configure the completions to load when needed. Note: the filename must be `temporal.fish` or the completions will not + be found: + + ```fish + echo 'eval "$(temporal completion fish)"' >~/.config/fish/completions/temporal.fish + ``` + +3. Re-launch your shell or run: + + ```fish + source ~/.config/fish/completions/temporal.fish + ``` ## Getting CLI help @@ -159,17 +315,4 @@ For example: - `temporal workflow --help` - `temporal workflow delete --help` -Available commands - -| Command | Description | -| ---------------------------------- | ----------------------------------------------------------- | -| [**activity**](/cli/activity) | Complete, update, pause, unpause, reset or fail an Activity | -| [**batch**](/cli/batch) | Manage running batch jobs | -| [**completion**](/cli/cmd-options) | Generate the autocompletion script for the specified shell | -| [**env**](/cli/env) | Manage environments | -| [**operator**](/cli/operator) | Manage Temporal deployments | -| [**schedule**](/cli/schedule) | Perform operations on Schedules | -| [**server**](/cli/server) | Run Temporal Server | -| [**task-queue**](/cli/task-queue) | Manage Task Queues | -| [**worker**](/cli/worker) | Read or update Worker state | -| [**workflow**](/cli/workflow) | Start, list, and operate on Workflows | +For a full list of commands, see the [Temporal CLI command reference](/cli#command-reference). diff --git a/docs/cloud/get-started/certificates.mdx b/docs/cloud/get-started/certificates.mdx index e6868890b5..7f9796b8ef 100644 --- a/docs/cloud/get-started/certificates.mdx +++ b/docs/cloud/get-started/certificates.mdx @@ -501,4 +501,5 @@ temporal \ --tls-server-name ``` -For more information on Temporal CLI environment variables, see [Environment variables](/cli#environment-variables). +For more information on Temporal CLI environment variables, see +[Environment variables](/cli/setup-cli#environment-variables). diff --git a/docs/develop/dotnet/best-practices/converters-and-encryption.mdx b/docs/develop/dotnet/best-practices/converters-and-encryption.mdx index 8f362cc1d8..6fdcd6a369 100644 --- a/docs/develop/dotnet/best-practices/converters-and-encryption.mdx +++ b/docs/develop/dotnet/best-practices/converters-and-encryption.mdx @@ -87,7 +87,7 @@ var myClient = await TemporalClient.ConnectAsync(new("localhost:7233") ``` - Data **encoding** is performed by the client using the converters and codecs provided by Temporal or your custom implementation when passing input to the Temporal Cluster. For example, plain text input is usually serialized into a JSON object, and can then be compressed or encrypted. -- Data **decoding** may be performed by your application logic during your Workflows or Activities as necessary, but decoded Workflow results are never persisted back to the Temporal Cluster. Instead, they are stored encoded on the Cluster, and you need to provide an additional parameter when using the [temporal workflow show](/cli/workflow#show) command or when browsing the Web UI to view output. +- Data **decoding** may be performed by your application logic during your Workflows or Activities as necessary, but decoded Workflow results are never persisted back to the Temporal Cluster. Instead, they are stored encoded on the Cluster, and you need to provide an additional parameter when using the [temporal workflow show](/cli/command-reference/workflow#show) command or when browsing the Web UI to view output. For reference, see the [Encryption](https://github.com/temporalio/samples-dotnet/tree/main/src/Encryption) sample. diff --git a/docs/develop/dotnet/client/temporal-client.mdx b/docs/develop/dotnet/client/temporal-client.mdx index fe8dbd7c31..714c44ab07 100644 --- a/docs/develop/dotnet/client/temporal-client.mdx +++ b/docs/develop/dotnet/client/temporal-client.mdx @@ -41,7 +41,7 @@ configuration. You can provide these options directly in code, or load them from configuration file for secure, repeatable configuration. When you’re running a Temporal Service locally (such as with the -[Temporal CLI dev server](https://docs.temporal.io/cli/server#start-dev)), the required options are minimal. If you +[Temporal CLI dev server](https://docs.temporal.io/cli/command-reference/server#start-dev)), the required options are minimal. If you don't specify a host/port, most connections default to `127.0.0.1:7233` and the `default` Namespace. diff --git a/docs/develop/dotnet/platform/observability.mdx b/docs/develop/dotnet/platform/observability.mdx index 4de025eb78..7df9d1f8b2 100644 --- a/docs/develop/dotnet/platform/observability.mdx +++ b/docs/develop/dotnet/platform/observability.mdx @@ -166,7 +166,7 @@ The steps to using custom Search Attributes are: - On the Client by calling `Describe` on a `WorkflowHandle`. - In the Workflow by looking at `WorkflowInfo`. - Query Workflow Executions by the Search Attribute using a [List Filter](/list-filter): - - [In the Temporal CLI](/cli/operator#list-2) + - [In the Temporal CLI](/cli/command-reference/operator#list-2) - In code by calling `ListWorkflowsAsync`. ### List Workflow Executions {#list-workflow-executions} diff --git a/docs/develop/environment-configuration.mdx b/docs/develop/environment-configuration.mdx index 883b8b3b27..ad028079df 100644 --- a/docs/develop/environment-configuration.mdx +++ b/docs/develop/environment-configuration.mdx @@ -97,7 +97,7 @@ MIIPrivateKeyDataHere... The Temporal CLI tool includes `temporal config` commands that allow you to read and write to the TOML configuration file. This provides a convenient way to manage your connection profiles without manually editing the file. Refer to -[Temporal CLI Reference - `temporal config`](../cli/config.mdx) for more details. +[Temporal CLI Reference - `temporal config`](../cli/command-reference/config.mdx) for more details. - `temporal config get `: Reads a specific value from the current profile. - `temporal config set `: Sets a property in the current profile. diff --git a/docs/develop/go/best-practices/data-handling/data-encryption.mdx b/docs/develop/go/best-practices/data-handling/data-encryption.mdx index 201a6e1059..2cddb30115 100644 --- a/docs/develop/go/best-practices/data-handling/data-encryption.mdx +++ b/docs/develop/go/best-practices/data-handling/data-encryption.mdx @@ -118,7 +118,7 @@ c, err := client.Dial(client.Options{ ``` - Data **encoding** is performed by the client using the converters and codecs provided by Temporal or your custom implementation when passing input to the Temporal Cluster. For example, plain text input is usually serialized into a JSON object, and can then be compressed or encrypted. -- Data **decoding** may be performed by your application logic during your Workflows or Activities as necessary, but decoded Workflow results are never persisted back to the Temporal Cluster. Instead, they are stored encoded on the Cluster, and you need to provide an additional parameter when using the [temporal workflow show](/cli/workflow#show) command or when browsing the Web UI to view output. +- Data **decoding** may be performed by your application logic during your Workflows or Activities as necessary, but decoded Workflow results are never persisted back to the Temporal Cluster. Instead, they are stored encoded on the Cluster, and you need to provide an additional parameter when using the [temporal workflow show](/cli/command-reference/workflow#show) command or when browsing the Web UI to view output. For reference, see the [Encryption](https://github.com/temporalio/samples-go/tree/main/encryption) sample. diff --git a/docs/develop/go/client/namespaces.mdx b/docs/develop/go/client/namespaces.mdx index 7a25df3078..2daef5ae86 100644 --- a/docs/develop/go/client/namespaces.mdx +++ b/docs/develop/go/client/namespaces.mdx @@ -45,7 +45,7 @@ Use a custom [Authorizer](/self-hosted-guide/security#authorizer-plugin) on your Use [`Register` API](https://pkg.go.dev/go.temporal.io/sdk/client#NamespaceClient) with the `NamespaceClient` interface to register a [Namespace](/namespaces) and set the [Retention Period](/temporal-service/temporal-server#retention-period) for the Workflow Execution Event History for the Namespace. -You can also [register Namespaces using the Temporal CLI command-line tool](/cli/operator#create). +You can also [register Namespaces using the Temporal CLI command-line tool](/cli/command-reference/operator#create). ```go client, err := client.NewNamespaceClient(client.Options{HostPort: ts.config.ServiceAddr}) @@ -67,7 +67,7 @@ Ensure that you wait for this registration to complete before starting the Workf To update your Namespace, use the [`Update` API](https://pkg.go.dev/go.temporal.io/sdk/client#NamespaceClient) with the `NamespaceClient`. -To update your Namespace using the Temporal CLI, use the [temporal operator namespace update](/cli/operator#update) command. +To update your Namespace using the Temporal CLI, use the [temporal operator namespace update](/cli/command-reference/operator#update) command. ### How to manage Namespaces {#manage-namespaces} @@ -89,7 +89,7 @@ Note that these APIs and Temporal CLI commands will not work with Temporal Cloud - Update information and configuration for a registered Namespace on your Temporal Service: - - With the Temporal CLI: [`temporal operator namespace update`](/cli/operator#update) + - With the Temporal CLI: [`temporal operator namespace update`](/cli/command-reference/operator#update) Example - Use the [`UpdateNamespace` API](https://pkg.go.dev/go.temporal.io/sdk/client#NamespaceClient) to update configuration on a Namespace. Example @@ -127,7 +127,7 @@ Note that these APIs and Temporal CLI commands will not work with Temporal Cloud - Get details for a registered Namespace on your Temporal Service: - - With the Temporal CLI: [`temporal operator namespace describe`](/cli/operator#describe) + - With the Temporal CLI: [`temporal operator namespace describe`](/cli/command-reference/operator#describe) - Use the [`DescribeNamespace` API](https://pkg.go.dev/go.temporal.io/sdk/client#NamespaceClient) to return information and configuration details for a registered Namespace. Example @@ -141,7 +141,7 @@ Note that these APIs and Temporal CLI commands will not work with Temporal Cloud - Get details for all registered Namespaces on your Temporal Service: - - With the Temporal CLI: [`temporal operator namespace list`](/cli/operator#list) + - With the Temporal CLI: [`temporal operator namespace list`](/cli/command-reference/operator#list) - Use the [`ListNamespace` API](https://github.com/temporalio/api/blob/f0350f8032ad2f0c60c539b3b61ea37f412f1cf7/temporal/api/operatorservice/v1/service.proto) to return information and configuration details for all registered Namespaces on your Temporal Service. Example diff --git a/docs/develop/go/client/temporal-client.mdx b/docs/develop/go/client/temporal-client.mdx index eb62dd5d43..42bd6013ce 100644 --- a/docs/develop/go/client/temporal-client.mdx +++ b/docs/develop/go/client/temporal-client.mdx @@ -67,7 +67,7 @@ Environment variable and configuration file support were added in Go SDK v1.28.0 ::: When you are running a Temporal Service locally, such as the -[Temporal CLI](https://docs.temporal.io/cli/server#start-dev), the connection options you must provide are minimal. +[Temporal CLI](https://docs.temporal.io/cli/command-reference/server#start-dev), the connection options you must provide are minimal. If you don't provide [`HostPort`](https://pkg.go.dev/go.temporal.io/sdk/internal#ClientOptions), the Client defaults the address and port number to `127.0.0.1:7233`, which is the port of the development Temporal Service. If you don't set a diff --git a/docs/develop/go/platform/observability.mdx b/docs/develop/go/platform/observability.mdx index f8b1d6f2bc..ca61e22e02 100644 --- a/docs/develop/go/platform/observability.mdx +++ b/docs/develop/go/platform/observability.mdx @@ -211,7 +211,7 @@ The steps to using custom Search Attributes are: - On the Client by calling `DescribeWorkflow`. - In the Workflow by looking at `WorkflowInfo`. - Query Workflow Executions by the Search Attribute using a [List Filter](/list-filter): - - [In the Temporal CLI](/cli/workflow#list). + - [In the Temporal CLI](/cli/command-reference/workflow#list). - In code by calling `ListWorkflowExecutions`. Here is how to query Workflow Executions: diff --git a/docs/develop/java/best-practices/converters-and-encryption.mdx b/docs/develop/java/best-practices/converters-and-encryption.mdx index 4b43119e0a..017357536f 100644 --- a/docs/develop/java/best-practices/converters-and-encryption.mdx +++ b/docs/develop/java/best-practices/converters-and-encryption.mdx @@ -159,7 +159,7 @@ WorkflowServiceStubs service = WorkflowServiceStubs.newLocalServiceStubs(); ``` - Data **encoding** is performed by the client using the converters and codecs provided by Temporal or your custom implementation when passing input to the Temporal Cluster. For example, plain text input is usually serialized into a JSON object, and can then be compressed or encrypted. -- Data **decoding** may be performed by your application logic during your Workflows or Activities as necessary, but decoded Workflow results are never persisted back to the Temporal Cluster. Instead, they are stored encoded on the Cluster, and you need to provide an additional parameter when using the [temporal workflow show](/cli/workflow#show) command or when browsing the Web UI to view output. +- Data **decoding** may be performed by your application logic during your Workflows or Activities as necessary, but decoded Workflow results are never persisted back to the Temporal Cluster. Instead, they are stored encoded on the Cluster, and you need to provide an additional parameter when using the [temporal workflow show](/cli/command-reference/workflow#show) command or when browsing the Web UI to view output. For reference, see the [Encryption](https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/encryptedpayloads) sample. diff --git a/docs/develop/java/client/namespaces.mdx b/docs/develop/java/client/namespaces.mdx index 2a9d901354..e02b4194c1 100644 --- a/docs/develop/java/client/namespaces.mdx +++ b/docs/develop/java/client/namespaces.mdx @@ -92,7 +92,7 @@ Note that these APIs and Temporal CLI commands will not work with Temporal Cloud - Update information and configuration for a registered Namespace on your Temporal Service: - - With the Temporal CLI: [`temporal operator namespace update`](/cli/operator#update) + - With the Temporal CLI: [`temporal operator namespace update`](/cli/command-reference/operator#update) Example - Use the [`UpdateNamespace` API](https://github.com/temporalio/api/blob/e5cf521c6fdc71c69353f3d2ac5506dd6e827af8/temporal/api/workflowservice/v1/service.proto) to update configuration on a Namespace. Example @@ -115,7 +115,7 @@ Note that these APIs and Temporal CLI commands will not work with Temporal Cloud - Get details for a registered Namespace on your Temporal Service: - - With the Temporal CLI: [`temporal operator namespace describe`](/cli/operator#describe) + - With the Temporal CLI: [`temporal operator namespace describe`](/cli/command-reference/operator#describe) - Use the [`DescribeNamespace` API](https://github.com/temporalio/api/blob/e5cf521c6fdc71c69353f3d2ac5506dd6e827af8/temporal/api/workflowservice/v1/service.proto) to return information and configuration details for a registered Namespace. Example @@ -132,7 +132,7 @@ Note that these APIs and Temporal CLI commands will not work with Temporal Cloud - Get details for all registered Namespaces on your Temporal Service: - - With the Temporal CLI: [`temporal operator namespace list`](/cli/operator#list) + - With the Temporal CLI: [`temporal operator namespace list`](/cli/command-reference/operator#list) - Use the [`ListNamespace` API](https://github.com/temporalio/api/blob/e5cf521c6fdc71c69353f3d2ac5506dd6e827af8/temporal/api/workflowservice/v1/service.proto) to return information and configuration details for all registered Namespaces on your Temporal Service. Example diff --git a/docs/develop/java/platform/observability.mdx b/docs/develop/java/platform/observability.mdx index 61ec2ab12d..58fc47229d 100644 --- a/docs/develop/java/platform/observability.mdx +++ b/docs/develop/java/platform/observability.mdx @@ -187,7 +187,7 @@ The steps to using custom Search Attributes are: - On the Client by calling `DescribeWorkflow`. - In the Workflow by looking at `WorkflowInfo`. - Query Workflow Executions by the Search Attribute using a [List Filter](/list-filter): - - [In the Temporal CLI](/cli/workflow#list). + - [In the Temporal CLI](/cli/command-reference/workflow#list). - In code by calling `ListWorkflowExecutions`. ### How to set custom Search Attributes {#custom-search-attributes} diff --git a/docs/develop/php/client/temporal-client.mdx b/docs/develop/php/client/temporal-client.mdx index 35eee92447..c7094331a3 100644 --- a/docs/develop/php/client/temporal-client.mdx +++ b/docs/develop/php/client/temporal-client.mdx @@ -44,7 +44,7 @@ However, it is acceptable and common to use a Temporal Client inside an Activity ::: -When you are running a Temporal Service locally (such as the [Temporal CLI](https://docs.temporal.io/cli/server#start-dev)), the number of connection options you must provide is minimal. +When you are running a Temporal Service locally (such as the [Temporal CLI](https://docs.temporal.io/cli/command-reference/server#start-dev)), the number of connection options you must provide is minimal. Many SDKs default to `127.0.0.1:7233`. In the PHP SDK, different client classes are responsible for different functional areas. diff --git a/docs/develop/php/platform/observability.mdx b/docs/develop/php/platform/observability.mdx index c72026f483..da4a5c0ec4 100644 --- a/docs/develop/php/platform/observability.mdx +++ b/docs/develop/php/platform/observability.mdx @@ -124,7 +124,7 @@ The steps to using custom Search Attributes are: - On the Client by calling `DescribeWorkflow`. - In the Workflow by looking at `WorkflowInfo`. - Query Workflow Executions by the Search Attribute using a [List Filter](/list-filter): - - [In the Temporal CLI](/cli/workflow#list). + - [In the Temporal CLI](/cli/command-reference/workflow#list). - In code by calling `ListWorkflowExecutions`. Here is how to query Workflow Executions: diff --git a/docs/develop/python/client/temporal-client.mdx b/docs/develop/python/client/temporal-client.mdx index 3582acbd01..fb67f66a33 100644 --- a/docs/develop/python/client/temporal-client.mdx +++ b/docs/develop/python/client/temporal-client.mdx @@ -51,7 +51,7 @@ options directly in code, load them from **environment variables**, or a **TOML configuration file for secure, repeatable configuration. When you’re running a Temporal Service locally (such as with the -[Temporal CLI dev server](https://docs.temporal.io/cli/server#start-dev)), the required options are minimal. If you +[Temporal CLI dev server](https://docs.temporal.io/cli/command-reference/server#start-dev)), the required options are minimal. If you don't specify a host/port, most connections default to `127.0.0.1:7233` and the `default` Namespace. diff --git a/docs/develop/python/platform/observability.mdx b/docs/develop/python/platform/observability.mdx index 026365fbfa..03ad9b54d9 100644 --- a/docs/develop/python/platform/observability.mdx +++ b/docs/develop/python/platform/observability.mdx @@ -160,7 +160,7 @@ The steps to using custom Search Attributes are: - On the Client by calling `DescribeWorkflow`. - In the Workflow by looking at `WorkflowInfo`. - Query Workflow Executions by the Search Attribute using a [List Filter](/list-filter): - - [In the Temporal CLI](/cli/operator#list-2) + - [In the Temporal CLI](/cli/command-reference/operator#list-2) - In code by calling `ListWorkflowExecutions`. Here is how to query Workflow Executions: diff --git a/docs/develop/ruby/best-practices/converters-and-encryption.mdx b/docs/develop/ruby/best-practices/converters-and-encryption.mdx index 21a0cdd95b..4cc0ca1f63 100644 --- a/docs/develop/ruby/best-practices/converters-and-encryption.mdx +++ b/docs/develop/ruby/best-practices/converters-and-encryption.mdx @@ -82,7 +82,7 @@ my_client = Temporalio::Client.connect( - Data **encoding** is performed by the client using the converters and codecs provided by Temporal or your custom implementation when passing input to the Temporal Cluster. For example, plain text input is usually serialized into a JSON object, and can then be compressed or encrypted. - Data **decoding** may be performed by your application logic during your Workflows or Activities as necessary, but decoded Workflow results are never persisted back to the Temporal Cluster. - Instead, they are stored encoded on the Cluster, and you need to provide an additional parameter when using the [temporal workflow show](/cli/workflow#show) command or when browsing the Web UI to view output. + Instead, they are stored encoded on the Cluster, and you need to provide an additional parameter when using the [temporal workflow show](/cli/command-reference/workflow#show) command or when browsing the Web UI to view output. diff --git a/docs/develop/ruby/client/temporal-client.mdx b/docs/develop/ruby/client/temporal-client.mdx index 46b7f6ea4e..e68a449f37 100644 --- a/docs/develop/ruby/client/temporal-client.mdx +++ b/docs/develop/ruby/client/temporal-client.mdx @@ -39,7 +39,7 @@ these options directly in code, load them from **environment variables**, or a * configuration file for secure, repeatable configuration. When you’re running a Temporal Service locally (such as with the -[Temporal CLI dev server](https://docs.temporal.io/cli/server#start-dev)), the required options are minimal. If you +[Temporal CLI dev server](https://docs.temporal.io/cli/command-reference/server#start-dev)), the required options are minimal. If you don't specify a host/port, most connections default to `127.0.0.1:7233` and the `default` Namespace. diff --git a/docs/develop/ruby/platform/observability.mdx b/docs/develop/ruby/platform/observability.mdx index fa3cf42edd..32783c2daa 100644 --- a/docs/develop/ruby/platform/observability.mdx +++ b/docs/develop/ruby/platform/observability.mdx @@ -155,7 +155,7 @@ The steps to using custom Search Attributes are: - On the Client by calling `describe` on a `WorkflowHandle`. - In the Workflow by looking at `Temporalio::Workflow.search_attributes`. - Query Workflow Executions by the Search Attribute using a [List Filter](/list-filter): - - [In the Temporal CLI](/cli/operator#list-2) + - [In the Temporal CLI](/cli/command-reference/operator#list-2) - In code by calling `list_workflows`. ### List Workflow Executions {#list-workflow-executions} diff --git a/docs/develop/typescript/best-practices/testing-suite.mdx b/docs/develop/typescript/best-practices/testing-suite.mdx index 2b2cfe8214..a1146e289d 100644 --- a/docs/develop/typescript/best-practices/testing-suite.mdx +++ b/docs/develop/typescript/best-practices/testing-suite.mdx @@ -533,7 +533,7 @@ To replay a single Event History, use [worker.runReplayHistory](https://typescri When an Event History is replayed and non-determinism is detected (that is, the Workflow code is incompatible with the History), [DeterminismViolationError](https://typescript.temporal.io/api/classes/workflow.DeterminismViolationError) is thrown. If replay fails for any other reason, [ReplayError](https://typescript.temporal.io/api/classes/worker.ReplayError) is thrown. -In the following example, a single Event History is loaded from a JSON file on disk (as obtained from the [Web UI](/web-ui) or the [Temporal CLI](/cli/workflow#show)): +In the following example, a single Event History is loaded from a JSON file on disk (as obtained from the [Web UI](/web-ui) or the [Temporal CLI](/cli/command-reference/workflow#show)): ```ts const filePath = './history_file.json'; diff --git a/docs/develop/typescript/platform/observability.mdx b/docs/develop/typescript/platform/observability.mdx index 826f4929c2..134c4c69f1 100644 --- a/docs/develop/typescript/platform/observability.mdx +++ b/docs/develop/typescript/platform/observability.mdx @@ -455,7 +455,7 @@ The steps to using custom Search Attributes are: - On the Client by calling `DescribeWorkflow`. - In the Workflow by looking at `WorkflowInfo`. - Query Workflow Executions by the Search Attribute using a [List Filter](/list-filter): - - [With the Temporal CLI](/cli/workflow#list). + - [With the Temporal CLI](/cli/command-reference/workflow#list). - In code by calling `ListWorkflowExecutions`. Here is how to query Workflow Executions: diff --git a/docs/encyclopedia/activities/activity-operations.mdx b/docs/encyclopedia/activities/activity-operations.mdx index be4768469d..8e9875636a 100644 --- a/docs/encyclopedia/activities/activity-operations.mdx +++ b/docs/encyclopedia/activities/activity-operations.mdx @@ -24,29 +24,33 @@ This page discusses the following: - [Update Options](#update-options) - [Observability](#observability) -Activity Operations are deliberate actions you perform on a specific [Activity Execution](/activity-execution), as opposed to lifecycle behaviors like [retries](/encyclopedia/retry-policies) and [timeouts](/encyclopedia/detecting-activity-failures) which happen automatically. +Activity Operations are deliberate actions you perform on a specific [Activity Execution](/activity-execution), as +opposed to lifecycle behaviors like [retries](/encyclopedia/retry-policies) and +[timeouts](/encyclopedia/detecting-activity-failures) which happen automatically. -You can perform Activity Operations through the [CLI](/cli/activity), the UI, or directly via the gRPC API. -Not all operations are available in all interfaces yet - see the [summary table](#operations-summary) for current support. -Activity Operations don't apply to [Local Activities](/local-activity) or [Standalone Activities](/standalone-activity). +You can perform Activity Operations through the [CLI](/cli/command-reference/activity), the UI, or directly via the gRPC +API. Not all operations are available in all interfaces yet - see the [summary table](#operations-summary) for current +support. Activity Operations don't apply to [Local Activities](/local-activity) or +[Standalone Activities](/standalone-activity). :::note Public Preview Activity Operations are in [Public Preview](/evaluate/development-production-features/release-stages#public-preview). Pause, Unpause, and Reset are available in Server v1.28.0+. Self-hosted UI requires v2.47.0+. -Activity Operations aren't available as SDK client methods. They're operational controls designed for the CLI, UI, and gRPC API - not for programmatic use in Workflow or Activity code. +Activity Operations aren't available as SDK client methods. They're operational controls designed for the CLI, UI, and +gRPC API - not for programmatic use in Workflow or Activity code. ::: ## Operations summary -| Operation | What it does | CLI | -|-----------|-------------|-----| -| [Pause](#pause) | Stops retries. In-flight execution continues unless the Activity uses Heartbeat. | [`temporal activity pause`](/cli/activity#pause) | -| [Unpause](#unpause) | Resumes a Paused Activity. The next execution starts immediately. | [`temporal activity unpause`](/cli/activity#unpause) | -| [Reset](#reset) | Clears retry state (attempts, backoff) and schedules a new execution. | [`temporal activity reset`](/cli/activity#reset) | -| [Update Options](#update-options) | Changes timeouts, Retry Policy, or Task Queue without restarting the Activity. | [`temporal activity update-options`](/cli/activity#update-options) | +| Operation | What it does | CLI | +| --------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| [Pause](#pause) | Stops retries. In-flight execution continues unless the Activity uses Heartbeat. | [`temporal activity pause`](/cli/command-reference/activity#pause) | +| [Unpause](#unpause) | Resumes a Paused Activity. The next execution starts immediately. | [`temporal activity unpause`](/cli/command-reference/activity#unpause) | +| [Reset](#reset) | Clears retry state (attempts, backoff) and schedules a new execution. | [`temporal activity reset`](/cli/command-reference/activity#reset) | +| [Update Options](#update-options) | Changes timeouts, Retry Policy, or Task Queue without restarting the Activity. | [`temporal activity update-options`](/cli/command-reference/activity#update-options) | ## Pause {#pause} @@ -54,19 +58,27 @@ Pause stops the Temporal Service from scheduling new retries of an [Activity Exe ### When to Pause -- An Activity is calling an external service that's experiencing issues, and you want to stop retries until the service recovers. +- An Activity is calling an external service that's experiencing issues, and you want to stop retries until the service + recovers. - You need to inspect or change configuration before the Activity retries. - You're rolling out a new Worker version and want to hold specific Activities until the deploy is complete. ### What happens when you Pause an Activity -- **Pausing an Activity doesn't affect the parent Workflow.** The Workflow continues Running, and [Signals, Queries, and Updates](/encyclopedia/workflow-message-passing) on the parent Workflow are unaffected. -- **No further retries are scheduled.** The Temporal Service stops scheduling retries. This is enforced server-side, not by the SDK. -- **Workflow code has no visibility into Activity Operations.** Pause doesn't produce an Event History event, so the Workflow can't detect or react to it. See [Observability](#observability). -- **[Heartbeating](/encyclopedia/detecting-activity-failures#activity-heartbeat) determines whether the in-flight execution is interrupted:** - - **Activities with Heartbeat** are interrupted on their next Heartbeat. The SDK raises a Pause-specific error, and the Activity can catch this to clean up resources before exiting. - - **Activities without Heartbeat** continue running to completion. If the execution succeeds, the result is delivered to the Workflow normally. If it fails, no retry is scheduled. Pause takes effect after the in-flight execution ends. -- **Pause is idempotent.** Pausing an already-Paused Activity has no effect. Pausing a completed Activity returns an error. +- **Pausing an Activity doesn't affect the parent Workflow.** The Workflow continues Running, and + [Signals, Queries, and Updates](/encyclopedia/workflow-message-passing) on the parent Workflow are unaffected. +- **No further retries are scheduled.** The Temporal Service stops scheduling retries. This is enforced server-side, not + by the SDK. +- **Workflow code has no visibility into Activity Operations.** Pause doesn't produce an Event History event, so the + Workflow can't detect or react to it. See [Observability](#observability). +- **[Heartbeating](/encyclopedia/detecting-activity-failures#activity-heartbeat) determines whether the in-flight + execution is interrupted:** + - **Activities with Heartbeat** are interrupted on their next Heartbeat. The SDK raises a Pause-specific error, and + the Activity can catch this to clean up resources before exiting. + - **Activities without Heartbeat** continue running to completion. If the execution succeeds, the result is delivered + to the Workflow normally. If it fails, no retry is scheduled. Pause takes effect after the in-flight execution ends. +- **Pause is idempotent.** Pausing an already-Paused Activity has no effect. Pausing a completed Activity returns an + error. ### CLI usage @@ -77,36 +89,42 @@ temporal activity pause \ --reason "Downstream API is down, pausing until recovery" ``` -See the [CLI reference for `temporal activity pause`](/cli/activity#pause) for all options. +See the [CLI reference for `temporal activity pause`](/cli/command-reference/activity#pause) for all options. ### Detect Pause in Activity code -Activities with Heartbeat can detect that an interruption was caused by Pause rather than a timeout or Workflow Cancellation. -A Paused Activity resumes later. A Cancelled Activity doesn't. -Your Activity code may need to handle these cases differently, for example releasing held resources on Pause while preserving them on Cancellation, or vice versa. +Activities with Heartbeat can detect that an interruption was caused by Pause rather than a timeout or Workflow +Cancellation. A Paused Activity resumes later. A Cancelled Activity doesn't. Your Activity code may need to handle these +cases differently, for example releasing held resources on Pause while preserving them on Cancellation, or vice versa. -| SDK | Version | How to detect Pause | -|-----|---------|---------------------| -| Go | v1.34.0+ | Catch `activity.ErrActivityPaused` | -| Java | v1.29.0+ | Catch `ActivityPausedException` | -| TypeScript | v1.12.3+ | Check `cancellationDetails.paused === true` | -| Python | v1.12.0+ | Check `cancellation_details().paused` on `asyncio.CancelledError` | -| .NET | v1.7.0+ | Check `CancellationDetails.IsPaused` on `OperationCanceledException` | +| SDK | Version | How to detect Pause | +| ---------- | -------- | -------------------------------------------------------------------- | +| Go | v1.34.0+ | Catch `activity.ErrActivityPaused` | +| Java | v1.29.0+ | Catch `ActivityPausedException` | +| TypeScript | v1.12.3+ | Check `cancellationDetails.paused === true` | +| Python | v1.12.0+ | Check `cancellation_details().paused` on `asyncio.CancelledError` | +| .NET | v1.7.0+ | Check `CancellationDetails.IsPaused` on `OperationCanceledException` | ### Interaction with Workflow Pause -[Workflow Pause](/cli/workflow#pause) and Activity Pause are independent. Both stop Activity retries, but they must be Unpaused separately. +[Workflow Pause](/cli/command-reference/workflow#pause) and Activity Pause are independent. Both stop Activity retries, +but they must be Unpaused separately. - Workflow Pause blocks retries but doesn't interrupt in-flight executions via Heartbeat. Activity Pause does. - If both are active, both must be Unpaused before the Activity resumes. ### Important considerations -- **A Paused Activity can still time out.** Pause doesn't stop or extend the [Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout). Use [`update-options`](#update-options) to adjust the timeout if needed. -- **Pause won't interrupt an Activity that doesn't Heartbeat.** The current execution runs to completion, which could take up to the full [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout). +- **A Paused Activity can still time out.** Pause doesn't stop or extend the + [Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout). Use + [`update-options`](#update-options) to adjust the timeout if needed. +- **Pause won't interrupt an Activity that doesn't Heartbeat.** The current execution runs to completion, which could + take up to the full [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout). + ### Limitations -- **Pause operates on individual Activities by ID within a single Workflow.** Unlike Unpause, Reset, and Update Options, there's no `--query` flag. To pause multiple Activities, issue separate commands for each Activity ID. +- **Pause operates on individual Activities by ID within a single Workflow.** Unlike Unpause, Reset, and Update Options, + there's no `--query` flag. To pause multiple Activities, issue separate commands for each Activity ID. - **No Namespace-wide query for Paused Activities.** You must know the Workflow Id. See [Observability](#observability). ## Unpause {#unpause} @@ -121,11 +139,14 @@ Unpause resumes a Paused Activity Execution. ### What happens when you Unpause an Activity -- **The Activity is rescheduled immediately.** Any remaining retry backoff is discarded. The next execution starts right away. -- **Attempt count and Heartbeat data are preserved by default.** The Activity resumes from where it left off. Use `--reset-attempts` or `--reset-heartbeats` on the CLI to clear these, or use [Reset](#reset) to restart from attempt 1. +- **The Activity is rescheduled immediately.** Any remaining retry backoff is discarded. The next execution starts right + away. +- **Attempt count and Heartbeat data are preserved by default.** The Activity resumes from where it left off. Use + `--reset-attempts` or `--reset-heartbeats` on the CLI to clear these, or use [Reset](#reset) to restart from + attempt 1. -Unpause is idempotent. Unpausing an Activity that isn't Paused has no effect. -Unpausing an Activity that has already completed returns an error. +Unpause is idempotent. Unpausing an Activity that isn't Paused has no effect. Unpausing an Activity that has already +completed returns an error. ### CLI usage @@ -135,15 +156,25 @@ temporal activity unpause \ --activity-id my-activity ``` -See the [CLI reference for `temporal activity unpause`](/cli/activity#unpause) for all options, including `--reset-attempts` and `--reset-heartbeats` to clear state on resume. +See the [CLI reference for `temporal activity unpause`](/cli/command-reference/activity#unpause) for all options, +including `--reset-attempts` and `--reset-heartbeats` to clear state on resume. ### Important considerations -- **Unpausing many Activities at once can overwhelm downstream services.** If you Paused multiple Activities because a service was down, Unpausing them all at the same time sends all retries simultaneously. Consider Unpausing in batches to avoid overwhelming a recovering service. -- **Unpausing doesn't override Workflow Pause.** If the parent Workflow is also Paused, Unpausing the Activity alone isn't enough. Both must be Unpaused before the Activity resumes. See [Interaction with Workflow Pause](#interaction-with-workflow-pause). -- **Unpausing doesn't reset the attempt count.** The Activity retries from its current attempt number. Use [Reset](#reset) to restart from attempt 1. -- **A Paused Activity can time out before you Unpause it.** The [Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout) isn't stopped or extended while Paused. Use [`update-options`](#update-options) to extend the timeout before Unpausing if needed. -- **Unpause doesn't interrupt or duplicate an in-flight execution.** If an Activity without Heartbeat is still running when you Unpause, it continues to completion. The Temporal Service doesn't schedule a concurrent execution. If the in-flight execution fails, the next retry proceeds normally. +- **Unpausing many Activities at once can overwhelm downstream services.** If you Paused multiple Activities because a + service was down, Unpausing them all at the same time sends all retries simultaneously. Consider Unpausing in batches + to avoid overwhelming a recovering service. +- **Unpausing doesn't override Workflow Pause.** If the parent Workflow is also Paused, Unpausing the Activity alone + isn't enough. Both must be Unpaused before the Activity resumes. See + [Interaction with Workflow Pause](#interaction-with-workflow-pause). +- **Unpausing doesn't reset the attempt count.** The Activity retries from its current attempt number. Use + [Reset](#reset) to restart from attempt 1. +- **A Paused Activity can time out before you Unpause it.** The + [Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout) isn't stopped or + extended while Paused. Use [`update-options`](#update-options) to extend the timeout before Unpausing if needed. +- **Unpause doesn't interrupt or duplicate an in-flight execution.** If an Activity without Heartbeat is still running + when you Unpause, it continues to completion. The Temporal Service doesn't schedule a concurrent execution. If the + in-flight execution fails, the next retry proceeds normally. ## Reset {#reset} @@ -160,13 +191,24 @@ Reset clears an Activity's retry state and schedules a fresh execution. - **The attempt count resets to 1.** The Activity gets a full set of retry attempts regardless of how many it had used. - **Retry backoff is discarded.** If the Activity was in a backoff wait, it's rescheduled to run immediately. -- **If the Activity is Paused, Reset also Unpauses it.** Use `--keep-paused` to Reset the attempt count without resuming execution. With `--keep-paused`, the attempt count and Heartbeat data (if `--reset-heartbeats`) are reset, but the Activity stays Paused. No retry is scheduled until you [Unpause](#unpause) separately. -- **Resetting an Activity doesn't affect the parent Workflow.** The Workflow continues Running, and Signals, Queries, and Updates on the parent Workflow are unaffected. -- **Workflow code has no visibility into Activity Operations.** Reset doesn't produce an Event History event, so the Workflow can't detect or react to it. See [Observability](#observability). -- **[Heartbeating](/encyclopedia/detecting-activity-failures#activity-heartbeat) determines whether an in-flight execution is interrupted:** - - **Activities with Heartbeat** are interrupted on their next Heartbeat. The SDK may raise a Reset-specific error so the Activity can clean up before exiting. The next execution starts at attempt 1. - - **Activities without Heartbeat** continue running to completion. Reset doesn't cancel, interrupt, or schedule a concurrent execution. If the Activity was already retrying, the Temporal Service rejects the current execution's result because Reset changed the expected attempt number, and a fresh execution is scheduled after the [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) expires. If it was on its first execution, a successful result is still delivered to the Workflow normally. -- **Reset is idempotent.** Resetting an Activity that's already at attempt 1 with no backoff has no effect. Resetting a completed Activity returns an error. +- **If the Activity is Paused, Reset also Unpauses it.** Use `--keep-paused` to Reset the attempt count without resuming + execution. With `--keep-paused`, the attempt count and Heartbeat data (if `--reset-heartbeats`) are reset, but the + Activity stays Paused. No retry is scheduled until you [Unpause](#unpause) separately. +- **Resetting an Activity doesn't affect the parent Workflow.** The Workflow continues Running, and Signals, Queries, + and Updates on the parent Workflow are unaffected. +- **Workflow code has no visibility into Activity Operations.** Reset doesn't produce an Event History event, so the + Workflow can't detect or react to it. See [Observability](#observability). +- **[Heartbeating](/encyclopedia/detecting-activity-failures#activity-heartbeat) determines whether an in-flight + execution is interrupted:** + - **Activities with Heartbeat** are interrupted on their next Heartbeat. The SDK may raise a Reset-specific error so + the Activity can clean up before exiting. The next execution starts at attempt 1. + - **Activities without Heartbeat** continue running to completion. Reset doesn't cancel, interrupt, or schedule a + concurrent execution. If the Activity was already retrying, the Temporal Service rejects the current execution's + result because Reset changed the expected attempt number, and a fresh execution is scheduled after the + [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) expires. If it was on its + first execution, a successful result is still delivered to the Workflow normally. +- **Reset is idempotent.** Resetting an Activity that's already at attempt 1 with no backoff has no effect. Resetting a + completed Activity returns an error. ### CLI usage @@ -182,29 +224,40 @@ temporal activity reset \ --keep-paused ``` -See the [CLI reference for `temporal activity reset`](/cli/activity#reset) for all options, including `--reset-heartbeats` and bulk mode via `--query`. +See the [CLI reference for `temporal activity reset`](/cli/command-reference/activity#reset) for all options, including +`--reset-heartbeats` and bulk mode via `--query`. ### Detect Reset in Activity code -Activities with Heartbeat can detect that an interruption was caused by Reset rather than a timeout or Workflow Cancellation. -A Reset Activity is retried from attempt 1. A Cancelled Activity isn't. -Your Activity code may need to handle these cases differently, for example saving partial progress on Reset while discarding it on Cancellation. +Activities with Heartbeat can detect that an interruption was caused by Reset rather than a timeout or Workflow +Cancellation. A Reset Activity is retried from attempt 1. A Cancelled Activity isn't. Your Activity code may need to +handle these cases differently, for example saving partial progress on Reset while discarding it on Cancellation. -| SDK | How to detect Reset | -|-----|---------------------| -| Go | `activity.GetCancellationDetails(ctx).Cause()` returns `activity.ErrActivityReset` | -| Java | Catch `ActivityResetException` | -| TypeScript | Catch `ApplicationFailure` with `error.type === "ActivityReset"` | -| Python | Check `cancellation_details().reset` on `asyncio.CancelledError` | -| .NET | Check `CancellationDetails.IsReset` on `OperationCanceledException` | +| SDK | How to detect Reset | +| ---------- | ---------------------------------------------------------------------------------- | +| Go | `activity.GetCancellationDetails(ctx).Cause()` returns `activity.ErrActivityReset` | +| Java | Catch `ActivityResetException` | +| TypeScript | Catch `ApplicationFailure` with `error.type === "ActivityReset"` | +| Python | Check `cancellation_details().reset` on `asyncio.CancelledError` | +| .NET | Check `CancellationDetails.IsReset` on `OperationCanceledException` | ### Important considerations -- **A Reset Activity can still time out.** Reset doesn't restart the [Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout). The deadline is calculated from when the Activity was originally scheduled. Use [`update-options`](#update-options) to extend the timeout before or after Reset. -- **Heartbeat details are preserved by default.** If your Activity uses Heartbeat details for progress tracking and you want a clean restart, pass `--reset-heartbeats`. -- **Reset won't interrupt an Activity that doesn't Heartbeat.** The current execution runs to completion, which could take up to the full [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout). If the Activity had already retried (attempt > 1), the Temporal Service rejects the current execution's result because Reset changed the expected attempt number. The Activity waits for its Start-To-Close Timeout to expire before a new execution is scheduled. -- **`--restore-original-options` restores the Activity's original configuration.** It reverts timeouts, Retry Policy, and Task Queue to the values from when the Activity was first scheduled. -- **Bulk Reset can overwhelm downstream services.** When using `--query` to Reset Activities across many Workflows, use `--jitter` to stagger the restart times. +- **A Reset Activity can still time out.** Reset doesn't restart the + [Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout). The deadline is + calculated from when the Activity was originally scheduled. Use [`update-options`](#update-options) to extend the + timeout before or after Reset. +- **Heartbeat details are preserved by default.** If your Activity uses Heartbeat details for progress tracking and you + want a clean restart, pass `--reset-heartbeats`. +- **Reset won't interrupt an Activity that doesn't Heartbeat.** The current execution runs to completion, which could + take up to the full [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout). If the + Activity had already retried (attempt > 1), the Temporal Service rejects the current execution's result because Reset + changed the expected attempt number. The Activity waits for its Start-To-Close Timeout to expire before a new + execution is scheduled. +- **`--restore-original-options` restores the Activity's original configuration.** It reverts timeouts, Retry Policy, + and Task Queue to the values from when the Activity was first scheduled. +- **Bulk Reset can overwhelm downstream services.** When using `--query` to Reset Activities across many Workflows, use + `--jitter` to stagger the restart times. ## Update Options {#update-options} @@ -212,23 +265,31 @@ Update Options changes an Activity's runtime configuration without restarting it ### When to Update Options -- The [Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout) is about to expire on a Paused Activity, and you need to extend it before Unpausing. -- An Activity's [Retry Policy](/encyclopedia/retry-policies) needs tuning based on observed failure patterns (for example, increasing the backoff interval or maximum attempts). -- You want to move an Activity to a different [Task Queue](/task-queue) to route it to a specific set of [Workers](/workers). +- The [Schedule-To-Close Timeout](/encyclopedia/detecting-activity-failures#schedule-to-close-timeout) is about to + expire on a Paused Activity, and you need to extend it before Unpausing. +- An Activity's [Retry Policy](/encyclopedia/retry-policies) needs tuning based on observed failure patterns (for + example, increasing the backoff interval or maximum attempts). +- You want to move an Activity to a different [Task Queue](/task-queue) to route it to a specific set of + [Workers](/workers). - You need to restore an Activity's original configuration after a temporary override. ### What happens when you Update an Activity's Options -You can change [timeouts](/encyclopedia/detecting-activity-failures) (Schedule-To-Close, Start-To-Close, Schedule-To-Start, Heartbeat), Retry Policy (initial interval, maximum interval, backoff coefficient, maximum attempts), and Task Queue. -Only the fields you specify are changed. All other options remain unchanged. +You can change [timeouts](/encyclopedia/detecting-activity-failures) (Schedule-To-Close, Start-To-Close, +Schedule-To-Start, Heartbeat), Retry Policy (initial interval, maximum interval, backoff coefficient, maximum attempts), +and Task Queue. Only the fields you specify are changed. All other options remain unchanged. -- **If the Activity is waiting for retry (scheduled),** the new options take effect immediately. Any pending retry timer is regenerated with the updated configuration. -- **If the Activity is currently running,** the new options are stored but take effect on the next execution. The in-flight execution isn't interrupted. -- **If the Activity is Paused,** the new options are stored immediately. They take effect when the Activity is Unpaused and the next execution starts. -- **Workflow code has no visibility into Activity Operations.** Update Options doesn't produce an Event History event, so the Workflow can't detect or react to it. See [Observability](#observability). +- **If the Activity is waiting for retry (scheduled),** the new options take effect immediately. Any pending retry timer + is regenerated with the updated configuration. +- **If the Activity is currently running,** the new options are stored but take effect on the next execution. The + in-flight execution isn't interrupted. +- **If the Activity is Paused,** the new options are stored immediately. They take effect when the Activity is Unpaused + and the next execution starts. +- **Workflow code has no visibility into Activity Operations.** Update Options doesn't produce an Event History event, + so the Workflow can't detect or react to it. See [Observability](#observability). -Update Options is idempotent. Updating an Activity with the same values it already has produces no change. -Updating options on an Activity that has already completed returns an error. +Update Options is idempotent. Updating an Activity with the same values it already has produces no change. Updating +options on an Activity that has already completed returns an error. ### CLI usage @@ -239,12 +300,15 @@ temporal activity update-options \ --schedule-to-close-timeout 24h ``` -See the [CLI reference for `temporal activity update-options`](/cli/activity#update-options) for all options, including Retry Policy, Task Queue, and bulk mode via `--query`. +See the [CLI reference for `temporal activity update-options`](/cli/command-reference/activity#update-options) for all +options, including Retry Policy, Task Queue, and bulk mode via `--query`. ### Important considerations -- **Changes to a running Activity take effect on the next execution, not the current one.** If you need the change to apply immediately, the Activity must finish or fail its current execution first. -- **`--restore-original-options` is batch-only.** This flag only works with `--query`. It's silently ignored in single-workflow mode. It can't be combined with other option changes in the same command. +- **Changes to a running Activity take effect on the next execution, not the current one.** If you need the change to + apply immediately, the Activity must finish or fail its current execution first. +- **`--restore-original-options` is batch-only.** This flag only works with `--query`. It's silently ignored in + single-workflow mode. It can't be combined with other option changes in the same command. ### Limitations @@ -252,27 +316,28 @@ See the [CLI reference for `temporal activity update-options`](/cli/activity#upd ## Observability {#observability} -Activity Operations have a limited audit trail because they are not recorded in a Workflow's Event History. However, you can use the CLI and the UI to check Activity state and find Paused Activities for running Workflows. +Activity Operations have a limited audit trail because they are not recorded in a Workflow's Event History. However, you +can use the CLI and the UI to check Activity state and find Paused Activities for running Workflows. ### Check Activity state -`temporal workflow describe` shows the current state of each pending Activity, including whether it's Paused, its current attempt count, and last failure. -The UI shows who performed an operation, when, and why (if a `--reason` was provided). +`temporal workflow describe` shows the current state of each pending Activity, including whether it's Paused, its +current attempt count, and last failure. The UI shows who performed an operation, when, and why (if a `--reason` was +provided). ### Find Paused Activities The `TemporalPauseInfo` [Search Attribute](/search-attribute) is filterable within a Workflow. -There's no Namespace-wide query to find all Paused Activities across Workflows. -You must know the Workflow Id. +There's no Namespace-wide query to find all Paused Activities across Workflows. You must know the Workflow Id. ### Audit trail {#audit-trail} -Activity Operations don't produce Event History events. -There is no record of a Pause, Reset, or option change in the Workflow's [Event History](/workflow-execution/event#event-history). -Nothing that reads the Event History - Workflow code, Replays, or external tooling - will see that an Operation occurred. +Activity Operations don't produce Event History events. There is no record of a Pause, Reset, or option change in the +Workflow's [Event History](/workflow-execution/event#event-history). Nothing that reads the Event History - Workflow +code, Replays, or external tooling - will see that an Operation occurred. -Evidence of an Operation is gone when the Activity completes or the Workflow closes. -There's no persistent record that an Activity was Paused, Reset, or had its options changed. +Evidence of an Operation is gone when the Activity completes or the Workflow closes. There's no persistent record that +an Activity was Paused, Reset, or had its options changed. The only way to confirm the current state of an Activity is `temporal workflow describe` or the UI. diff --git a/docs/encyclopedia/data-conversion/dataconversion.mdx b/docs/encyclopedia/data-conversion/dataconversion.mdx index 6171458474..fd88ef34ae 100644 --- a/docs/encyclopedia/data-conversion/dataconversion.mdx +++ b/docs/encyclopedia/data-conversion/dataconversion.mdx @@ -39,7 +39,7 @@ Data Converter steps are followed when data is sent to a Temporal Service (as in Due to how Temporal provides access to Workflow output, this implementation is asymmetric: - Data encoding is performed automatically using the default converter provided by Temporal or your custom Data Converter when passing input to a Temporal Service. For example, plain text input is usually serialized into a JSON object. -- Data decoding may be performed by your application logic during your Workflows or Activities as necessary, but decoded Workflow results are never persisted back to the Temporal Service. Instead, they are stored encoded on the Temporal Service, and you need to provide an additional parameter when using [`temporal workflow show`](/cli/workflow#show) or when browsing the Web UI to view output. +- Data decoding may be performed by your application logic during your Workflows or Activities as necessary, but decoded Workflow results are never persisted back to the Temporal Service. Instead, they are stored encoded on the Temporal Service, and you need to provide an additional parameter when using [`temporal workflow show`](/cli/command-reference/workflow#show) or when browsing the Web UI to view output. Each piece of data (like a single argument or return value) is encoded as a [Payload](/dataconversion#payload), which consists of binary data and key-value metadata. diff --git a/docs/encyclopedia/namespaces/global-namespaces.mdx b/docs/encyclopedia/namespaces/global-namespaces.mdx index 2ba2d246fb..19f2c9fd17 100644 --- a/docs/encyclopedia/namespaces/global-namespaces.mdx +++ b/docs/encyclopedia/namespaces/global-namespaces.mdx @@ -18,8 +18,8 @@ This page provides an overview of Global Namespace. A Global Namespace is a [Namespace](/namespaces) that exists across Clusters when [Multi-Cluster Replication](/temporal-service/multi-cluster-replication) is set up. -- [How to register a Global Namespace](/cli/operator#create) -- [How to change the active Cluster for a Global Namespace](/cli/operator#update) +- [How to register a Global Namespace](/cli/command-reference/operator#create) +- [How to change the active Cluster for a Global Namespace](/cli/command-reference/operator#update) The Global Namespace feature enables Workflow Executions to progress through another Cluster in the event of a failover. diff --git a/docs/encyclopedia/nexus/nexus-registry.mdx b/docs/encyclopedia/nexus/nexus-registry.mdx index b5b6049df8..0c3a5924e0 100644 --- a/docs/encyclopedia/nexus/nexus-registry.mdx +++ b/docs/encyclopedia/nexus/nexus-registry.mdx @@ -42,7 +42,7 @@ Manage Endpoints using the Temporal UI, CLI, Terraform provider, or [Cloud Ops A - [Terraform support](/cloud/terraform-provider#manage-temporal-cloud-nexus-endpoints-with-terraform) for Temporal Cloud. - [tcld nexus](/cloud/tcld/nexus) for Temporal Cloud. -- [temporal operator nexus](/cli/operator#nexus) for self-hosted deployments. +- [temporal operator nexus](/cli/command-reference/operator#nexus) for self-hosted deployments. ::: ### Search for a Nexus Endpoint diff --git a/docs/encyclopedia/temporal-service/temporal-server.mdx b/docs/encyclopedia/temporal-service/temporal-server.mdx index 2bd33b3578..83708bb4e0 100644 --- a/docs/encyclopedia/temporal-service/temporal-server.mdx +++ b/docs/encyclopedia/temporal-service/temporal-server.mdx @@ -207,7 +207,7 @@ Ports are configurable in the Temporal Service configuration. Retention Period is the duration for which the Temporal Service stores data associated with closed Workflow Executions on a Namespace in the Persistence store. -- [How to set the Retention Period for a Namespace](/cli/operator#create) +- [How to set the Retention Period for a Namespace](/cli/command-reference/operator#create) - [How to set the Retention Period for a Namespace using the Go SDK](/develop/go/client/namespaces) - [How to set the Retention Period for a Namespace using the Java SDK](/develop/java/client/namespaces) @@ -220,10 +220,10 @@ On Temporal Service version 1.18 and later, the maximum Retention Period value f On Temporal Service versions 1.17 and earlier, the maximum Retention Period you can set is 30 days. Setting the Retention Period to 0 results in the error _A valid retention period is not set on request_. -If you don't set the Retention Period value when using the [`temporal operator namespace create`](/cli/operator#create) command, it defaults to 3 days. +If you don't set the Retention Period value when using the [`temporal operator namespace create`](/cli/command-reference/operator#create) command, it defaults to 3 days. If you don't set the Retention Period value when using the Register Namespace Request API, it returns an error. -When changing the Retention Period (with [`temporal operator namespace update`](/cli/operator#update) or the `UpdateNamespace` API), the new duration applies to Workflow Executions that close after the change is saved. +When changing the Retention Period (with [`temporal operator namespace update`](/cli/command-reference/operator#update) or the `UpdateNamespace` API), the new duration applies to Workflow Executions that close after the change is saved. :::info @@ -233,5 +233,5 @@ Changing the Retention Period does NOT affect existing closed Workflow Execution ### Manual cleanup of closed Workflow Executions -For cases where you need to remove closed Workflow Executions before their retention timer expires, you can use [`temporal workflow delete`](/cli/workflow#delete) or the `DeleteWorkflowExecution` command. +For cases where you need to remove closed Workflow Executions before their retention timer expires, you can use [`temporal workflow delete`](/cli/command-reference/workflow#delete) or the `DeleteWorkflowExecution` command. This is particularly useful along with reducing the Retention Period to clean up previously closed Workflow Executions to reduce storage costs. diff --git a/docs/encyclopedia/visibility/list-filter.mdx b/docs/encyclopedia/visibility/list-filter.mdx index 6b6a7a162a..206acb3abf 100644 --- a/docs/encyclopedia/visibility/list-filter.mdx +++ b/docs/encyclopedia/visibility/list-filter.mdx @@ -136,7 +136,7 @@ Continue until the page token becomes `null`/`nil`. #### List Filter examples -Here are examples of List Filters set with the [Temporal CLI](/cli/workflow#list): +Here are examples of List Filters set with the [Temporal CLI](/cli/command-reference/workflow#list): ``` WorkflowType = "main.YourWorkflowDefinition" and ExecutionStatus != "Running" and (StartTime > "2021-06-07T16:46:34.236-08:00" or CloseTime > "2021-06-07T16:46:34-08:00") diff --git a/docs/encyclopedia/workers/task-queues.mdx b/docs/encyclopedia/workers/task-queues.mdx index ce8d564802..b74b612672 100644 --- a/docs/encyclopedia/workers/task-queues.mdx +++ b/docs/encyclopedia/workers/task-queues.mdx @@ -78,7 +78,7 @@ There are five places where the name of the Task Queue can be set by the develop 1. A Task Queue must be set when spawning a Workflow Execution: - - [How to start a Workflow Execution using the Temporal CLI](/cli/workflow#start) + - [How to start a Workflow Execution using the Temporal CLI](/cli/command-reference/workflow#start) - [How to start a Workflow Execution using the Go SDK](/develop/go/client/temporal-client#start-workflow-execution) - [How to start a Workflow Execution using the Java SDK](/develop/java/client/temporal-client#start-workflow-execution) - [How to start a Workflow Execution using the PHP SDK](/develop/php/client/temporal-client#start-workflow-execution) diff --git a/docs/encyclopedia/workers/worker-versioning.mdx b/docs/encyclopedia/workers/worker-versioning.mdx index f536a9a313..7047d38c4e 100644 --- a/docs/encyclopedia/workers/worker-versioning.mdx +++ b/docs/encyclopedia/workers/worker-versioning.mdx @@ -45,7 +45,7 @@ To learn more about implementing Worker Versioning, see our [Worker Versioning i ### Pinned Workflows {#pinned} -A **Pinned** Workflow is guaranteed to complete on a single Worker Deployment Version. You can mark a Workflow Type as pinned when you register it by adding an additional Pinned parameter. If you need to move a pinned Workflow to a new version, use [`temporal workflow update-options`](/cli/workflow#update-options). +A **Pinned** Workflow is guaranteed to complete on a single Worker Deployment Version. You can mark a Workflow Type as pinned when you register it by adding an additional Pinned parameter. If you need to move a pinned Workflow to a new version, use [`temporal workflow update-options`](/cli/command-reference/workflow#update-options). ### Auto-Upgrade Workflows {#auto-upgrade} diff --git a/docs/encyclopedia/workflow-message-passing/sending-messages.mdx b/docs/encyclopedia/workflow-message-passing/sending-messages.mdx index 2c0943516d..2c70cf4fae 100644 --- a/docs/encyclopedia/workflow-message-passing/sending-messages.mdx +++ b/docs/encyclopedia/workflow-message-passing/sending-messages.mdx @@ -47,7 +47,7 @@ You can also Signal-With-Start to lazily initialize a Workflow while sending a S #### Send a Signal from a Temporal Client or the CLI - + @@ -176,7 +176,7 @@ Queries can be sent from a Temporal Client or the Temporal CLI to a Workflow Exe You can also send a built-in "Stack Trace Query" for debugging. - + diff --git a/docs/encyclopedia/workflow/schedule.mdx b/docs/encyclopedia/workflow/schedule.mdx index ada92a7955..015fb82f9b 100644 --- a/docs/encyclopedia/workflow/schedule.mdx +++ b/docs/encyclopedia/workflow/schedule.mdx @@ -21,7 +21,7 @@ A Schedule contains instructions for starting a [Workflow Execution](/workflow-e Schedules provide a more flexible and user-friendly approach than [Temporal Cron Jobs](/cron-job). - [How to enable Schedules](#limitations) -- [How to operate Schedules using the Temporal CLI](/cli/schedule) +- [How to operate Schedules using the Temporal CLI](/cli/command-reference/schedule) A Schedule has an identity and is independent of a Workflow Execution. This differs from a Temporal Cron Job, which relies on a cron schedule as a property of the Workflow Execution. @@ -167,7 +167,7 @@ For more operational control, embed the contents of the time zone database file A Schedule can be Paused. When a Schedule is Paused, the Spec has no effect. -However, you can still force manual actions by using the [temporal schedule trigger](/cli/schedule#trigger) command. +However, you can still force manual actions by using the [temporal schedule trigger](/cli/command-reference/schedule#trigger) command. To assist communication among developers and operators, a “notes” field can be updated on pause or resume to store an explanation for the current state. diff --git a/docs/encyclopedia/workflow/workflow-execution/workflow-execution.mdx b/docs/encyclopedia/workflow/workflow-execution/workflow-execution.mdx index 03b37d05ed..6d79ab547d 100644 --- a/docs/encyclopedia/workflow/workflow-execution/workflow-execution.mdx +++ b/docs/encyclopedia/workflow/workflow-execution/workflow-execution.mdx @@ -32,7 +32,7 @@ While the Workflow Definition is the code that defines the Workflow, the Workflo A Temporal Workflow Execution is a durable, reliable, and scalable function execution. It is the main unit of execution of a [Temporal Application](/temporal#temporal-application). -- [How to start a Workflow Execution using temporal](/cli/workflow#start) +- [How to start a Workflow Execution using temporal](/cli/command-reference/workflow#start) - [How to start a Workflow Execution using the Go SDK](/develop/go/client/temporal-client#start-workflow-execution) - [How to start a Workflow Execution using the Java SDK](/develop/java/client/temporal-client#start-workflow-execution) - [How to start a Workflow Execution using the PHP SDK](/develop/php/client/temporal-client#start-workflow-execution) diff --git a/docs/evaluate/temporal-cloud/limits.mdx b/docs/evaluate/temporal-cloud/limits.mdx index a166d8f8dd..d6a6d53d32 100644 --- a/docs/evaluate/temporal-cloud/limits.mdx +++ b/docs/evaluate/temporal-cloud/limits.mdx @@ -169,7 +169,7 @@ You can set the Retention Period between 1 and 90 days. ### Batch jobs -A Namespace can have just one [Batch job](/cli/batch) running at a time. +A Namespace can have just one [Batch job](/cli/command-reference/batch) running at a time. Each batch job operates on a maximum of 50 Workflow Executions per second. diff --git a/docs/evaluate/temporal-cloud/pricing.mdx b/docs/evaluate/temporal-cloud/pricing.mdx index efd0a887a4..54974f5aea 100644 --- a/docs/evaluate/temporal-cloud/pricing.mdx +++ b/docs/evaluate/temporal-cloud/pricing.mdx @@ -157,7 +157,7 @@ For additional storage within a calendar month, you are billed for Active and Re :::tip Storage costs are also affected by Temporal System Workflows that back features such as: - [Schedules](https://docs.temporal.io/schedule): Each Scheduled Workflow contributes to storage usage. Supplied inputs, outputs, and failures all account for the storage usage incurred from Scheduled Workflows. -- [Batch jobs](https://docs.temporal.io/cli/batch): Batch Workflow executions also consume storage. +- [Batch jobs](https://docs.temporal.io/cli/command-reference/batch): Batch Workflow executions also consume storage. These Workflow executions contribute to overall active and retained storage consumption. diff --git a/docs/production-deployment/index.mdx b/docs/production-deployment/index.mdx index fd2375cd57..488193373d 100644 --- a/docs/production-deployment/index.mdx +++ b/docs/production-deployment/index.mdx @@ -27,13 +27,13 @@ To take your application to production, you'll need to deploy the following comp :::tip Do you need a production Temporal Service? If you're still developing and testing your application locally, you may not need a production Temporal Service. Use the -[Temporal CLI development server](/cli/server#start-dev) — a single binary with no external dependencies: +[Temporal CLI development server](/cli/command-reference/server#start-dev) — a single binary with no external dependencies: `temporal server start-dev` This starts a complete Temporal Service with Web UI on your local machine. We recommend this for local development regardless of whether you plan to use Temporal Cloud or self-host in production. See the -[Temporal CLI server](/cli/server) page for configuration options. +[Temporal CLI server](/cli/command-reference/server) page for configuration options. ::: diff --git a/docs/production-deployment/self-hosted-guide/defaults.mdx b/docs/production-deployment/self-hosted-guide/defaults.mdx index 143d1c2aa8..45f4ee9d9c 100644 --- a/docs/production-deployment/self-hosted-guide/defaults.mdx +++ b/docs/production-deployment/self-hosted-guide/defaults.mdx @@ -64,7 +64,7 @@ These limits might apply specifically to each Workflow Execution and do not pert - `limit.numPendingSignals.error` - `limit.numPendingCancelRequests.error` - `limit.numPendingChildExecutions.error` - - By default, [Batch jobs](/cli/batch) are limited to one job at a time. + - By default, [Batch jobs](/cli/command-reference/batch) are limited to one job at a time. - [Custom Search Attributes limits](/search-attribute#custom-search-attribute-limits) For details on dynamic configuration keys, see [Dynamic configuration reference](/references/dynamic-configuration). diff --git a/docs/production-deployment/self-hosted-guide/index.mdx b/docs/production-deployment/self-hosted-guide/index.mdx index 1f9384360f..df7da962c8 100644 --- a/docs/production-deployment/self-hosted-guide/index.mdx +++ b/docs/production-deployment/self-hosted-guide/index.mdx @@ -20,13 +20,13 @@ software that orchestrates your durable applications. :::tip Do you need a production Temporal Service? If you're still developing and testing your application locally, you may not need a production Temporal Service. Use the -[Temporal CLI development server](/cli/server#start-dev) — a single binary with no external dependencies: +[Temporal CLI development server](/cli/command-reference/server#start-dev) — a single binary with no external dependencies: `temporal server start-dev` This starts a complete Temporal Service with Web UI on your local machine. We recommend this for local development regardless of whether you plan to use Temporal Cloud or self-host in production. See the -[Temporal CLI server](/cli/server) page for configuration options. +[Temporal CLI server](/cli/command-reference/server) page for configuration options. ::: diff --git a/docs/production-deployment/self-hosted-guide/namespaces.mdx b/docs/production-deployment/self-hosted-guide/namespaces.mdx index 388869b300..9f4c407c7b 100644 --- a/docs/production-deployment/self-hosted-guide/namespaces.mdx +++ b/docs/production-deployment/self-hosted-guide/namespaces.mdx @@ -32,7 +32,7 @@ execution history is kept. You can create Namespaces using: -- **Temporal CLI** (recommended): [`temporal operator namespace create`](/cli/operator#create) +- **Temporal CLI** (recommended): [`temporal operator namespace create`](/cli/command-reference/operator#create) - **Go SDK**: [`RegisterNamespace`](/develop/go/client/namespaces#register-namespace) - **Java SDK**: [`RegisterNamespace`](/develop/java/client/namespaces#register-namespace) - **TypeScript SDK**: [Namespace management](/develop/typescript/client/namespaces#register-namespace) @@ -42,7 +42,7 @@ You can create Namespaces using: If no Namespace is specified, SDKs and CLI use the `default` Namespace. You must register this Namespace before using it. -For local development, the [`temporal server start-dev`](/cli/server#start-dev) command automatically creates the +For local development, the [`temporal server start-dev`](/cli/command-reference/server#start-dev) command automatically creates the `default` Namespace. For all other deployment methods, create the `default` Namespace manually using the Temporal CLI: @@ -58,12 +58,12 @@ Namespace. Common namespace management operations: -| Operation | CLI Command | Description | -| --------- | ---------------------------------------------------------------- | ----------------------------------- | -| List | [`temporal operator namespace list`](/cli/operator#list) | List all registered Namespaces | -| Describe | [`temporal operator namespace describe`](/cli/operator#describe) | Get details for a Namespace | -| Update | [`temporal operator namespace update`](/cli/operator#update) | Update Namespace configuration | -| Delete | [`temporal operator namespace delete`](/cli/operator#delete) | Delete a Namespace and all its data | +| Operation | CLI Command | Description | +| --------- | ---------------------------------------------------------------------------------- | ----------------------------------- | +| List | [`temporal operator namespace list`](/cli/command-reference/operator#list) | List all registered Namespaces | +| Describe | [`temporal operator namespace describe`](/cli/command-reference/operator#describe) | Get details for a Namespace | +| Update | [`temporal operator namespace update`](/cli/command-reference/operator#update) | Update Namespace configuration | +| Delete | [`temporal operator namespace delete`](/cli/command-reference/operator#delete) | Delete a Namespace and all its data | For SDK-based namespace management: diff --git a/docs/production-deployment/self-hosted-guide/server-frontend-api-reference.mdx b/docs/production-deployment/self-hosted-guide/server-frontend-api-reference.mdx index e9634ba68c..6a8a5f6752 100644 --- a/docs/production-deployment/self-hosted-guide/server-frontend-api-reference.mdx +++ b/docs/production-deployment/self-hosted-guide/server-frontend-api-reference.mdx @@ -46,7 +46,7 @@ If you're not using an SDK Client (rare), you can generate gRPC client stubs by: To query the API manually via command line or a GUI, first: -- If you don't already have a Server to connect to, run [`temporal server start-dev`](/cli/server#start-dev) +- If you don't already have a Server to connect to, run [`temporal server start-dev`](/cli/command-reference/server#start-dev) - Clone this repo: ```shell diff --git a/docs/production-deployment/self-hosted-guide/visibility.mdx b/docs/production-deployment/self-hosted-guide/visibility.mdx index 1748b1042c..21a0e2818d 100644 --- a/docs/production-deployment/self-hosted-guide/visibility.mdx +++ b/docs/production-deployment/self-hosted-guide/visibility.mdx @@ -870,7 +870,7 @@ When you are ready to deprecate your primary store, follow these steps. To manage custom Search Attributes on Temporal Cloud, use the [`tcld`](/cloud/tcld/namespace#search-attributes) CLI tool. With Temporal Cloud, you can create and rename custom Search Attributes. If you need to delete a custom Search Attribute, contact Support at [support.temporal.io](https://support.temporal.io). -To manage custom Search Attributes on a self-hosted Temporal Service, use the [Temporal CLI](/cli/operator#search-attribute). +To manage custom Search Attributes on a self-hosted Temporal Service, use the [Temporal CLI](/cli/command-reference/operator#search-attribute). With a self-hosted Temporal Service, you can create and remove custom Search Attributes. If you're self-hosting, verify whether your [Visibility database](/self-hosted-guide/visibility#supported-databases) version supports custom Search Attributes before proceeding. diff --git a/sidebars.js b/sidebars.js index 33c1ad0e1e..8675ff4743 100644 --- a/sidebars.js +++ b/sidebars.js @@ -160,10 +160,7 @@ module.exports = { type: 'doc', id: 'develop/go/client/index', }, - items: [ - 'develop/go/client/temporal-client', - 'develop/go/client/namespaces' - ], + items: ['develop/go/client/temporal-client', 'develop/go/client/namespaces'], }, { type: 'category', @@ -173,10 +170,7 @@ module.exports = { type: 'doc', id: 'develop/go/nexus/index', }, - items: [ - 'develop/go/nexus/quickstart', - 'develop/go/nexus/feature-guide', - ], + items: ['develop/go/nexus/quickstart', 'develop/go/nexus/feature-guide'], }, { type: 'category', @@ -186,10 +180,7 @@ module.exports = { type: 'doc', id: 'develop/go/platform/index', }, - items: [ - 'develop/go/platform/observability', - 'develop/go/platform/enriching-ui', - ], + items: ['develop/go/platform/observability', 'develop/go/platform/enriching-ui'], }, { type: 'category', @@ -278,9 +269,7 @@ module.exports = { type: 'doc', id: 'develop/java/workers/index', }, - items: [ - 'develop/java/workers/run-worker-process', - ], + items: ['develop/java/workers/run-worker-process'], }, { type: 'category', @@ -290,10 +279,7 @@ module.exports = { type: 'doc', id: 'develop/java/client/index', }, - items: [ - 'develop/java/client/temporal-client', - 'develop/java/client/namespaces', - ], + items: ['develop/java/client/temporal-client', 'develop/java/client/namespaces'], }, { type: 'category', @@ -303,10 +289,7 @@ module.exports = { type: 'doc', id: 'develop/java/nexus/index', }, - items: [ - 'develop/java/nexus/quickstart', - 'develop/java/nexus/feature-guide', - ], + items: ['develop/java/nexus/quickstart', 'develop/java/nexus/feature-guide'], }, { type: 'category', @@ -316,10 +299,7 @@ module.exports = { type: 'doc', id: 'develop/java/platform/index', }, - items: [ - 'develop/java/platform/observability', - 'develop/java/platform/enriching-ui', - ], + items: ['develop/java/platform/observability', 'develop/java/platform/enriching-ui'], }, { type: 'category', @@ -343,9 +323,7 @@ module.exports = { type: 'doc', id: 'develop/java/integrations/index', }, - items: [ - 'develop/java/integrations/spring-boot', - ], + items: ['develop/java/integrations/spring-boot'], }, ], }, @@ -378,7 +356,7 @@ module.exports = { 'develop/php/workflows/timers', 'develop/php/workflows/side-effects', 'develop/php/workflows/versioning', - ] + ], }, { type: 'category', @@ -393,7 +371,7 @@ module.exports = { 'develop/php/activities/execution', 'develop/php/activities/timeouts', 'develop/php/activities/asynchronous-activity', - ] + ], }, { type: 'category', @@ -403,9 +381,7 @@ module.exports = { type: 'doc', id: 'develop/php/workers/index', }, - items: [ - 'develop/php/workers/run-worker-process', - ] + items: ['develop/php/workers/run-worker-process'], }, { type: 'category', @@ -415,9 +391,7 @@ module.exports = { type: 'doc', id: 'develop/php/client/index', }, - items: [ - 'develop/php/client/temporal-client', - ], + items: ['develop/php/client/temporal-client'], }, { type: 'category', @@ -427,10 +401,7 @@ module.exports = { type: 'doc', id: 'develop/php/platform/index', }, - items: [ - 'develop/php/platform/observability', - 'develop/php/platform/enriching-ui', - ], + items: ['develop/php/platform/observability', 'develop/php/platform/enriching-ui'], }, { type: 'category', @@ -440,10 +411,7 @@ module.exports = { type: 'doc', id: 'develop/php/best-practices/index', }, - items: [ - 'develop/php/best-practices/testing-suite', - 'develop/php/best-practices/debugging' - ] + items: ['develop/php/best-practices/testing-suite', 'develop/php/best-practices/debugging'], }, ], }, @@ -475,7 +443,7 @@ module.exports = { 'develop/python/workflows/schedules', 'develop/python/workflows/timers', 'develop/python/workflows/versioning', - ] + ], }, { type: 'category', @@ -502,10 +470,7 @@ module.exports = { type: 'doc', id: 'develop/python/workers/index', }, - items: [ - 'develop/python/workers/run-worker-process', - 'develop/python/workers/interceptors', - ], + items: ['develop/python/workers/run-worker-process', 'develop/python/workers/interceptors'], }, { type: 'category', @@ -515,9 +480,7 @@ module.exports = { type: 'doc', id: 'develop/python/client/index', }, - items: [ - 'develop/python/client/temporal-client', - ], + items: ['develop/python/client/temporal-client'], }, { type: 'category', @@ -527,10 +490,7 @@ module.exports = { type: 'doc', id: 'develop/python/nexus/index', }, - items: [ - 'develop/python/nexus/quickstart', - 'develop/python/nexus/feature-guide', - ], + items: ['develop/python/nexus/quickstart', 'develop/python/nexus/feature-guide'], }, { type: 'category', @@ -540,10 +500,7 @@ module.exports = { type: 'doc', id: 'develop/python/platform/index', }, - items: [ - 'develop/python/platform/observability', - 'develop/python/platform/enriching-ui', - ], + items: ['develop/python/platform/observability', 'develop/python/platform/enriching-ui'], }, { type: 'category', @@ -642,10 +599,7 @@ module.exports = { type: 'doc', id: 'develop/typescript/workers/index', }, - items: [ - 'develop/typescript/workers/run-worker-process', - 'develop/typescript/workers/interceptors', - ], + items: ['develop/typescript/workers/run-worker-process', 'develop/typescript/workers/interceptors'], }, { type: 'category', @@ -655,10 +609,7 @@ module.exports = { type: 'doc', id: 'develop/typescript/client/index', }, - items: [ - 'develop/typescript/client/temporal-client', - 'develop/typescript/client/namespaces' - ], + items: ['develop/typescript/client/temporal-client', 'develop/typescript/client/namespaces'], }, { type: 'category', @@ -668,10 +619,7 @@ module.exports = { type: 'doc', id: 'develop/typescript/nexus/index', }, - items: [ - 'develop/typescript/nexus/quickstart', - 'develop/typescript/nexus/feature-guide' - ], + items: ['develop/typescript/nexus/quickstart', 'develop/typescript/nexus/feature-guide'], }, { type: 'category', @@ -681,10 +629,7 @@ module.exports = { type: 'doc', id: 'develop/typescript/platform/index', }, - items: [ - 'develop/typescript/platform/observability', - 'develop/typescript/platform/enriching-ui', - ], + items: ['develop/typescript/platform/observability', 'develop/typescript/platform/enriching-ui'], }, { type: 'category', @@ -742,7 +687,7 @@ module.exports = { 'develop/dotnet/workflows/timers', 'develop/dotnet/workflows/dynamic-workflow', 'develop/dotnet/workflows/versioning', - ] + ], }, { type: 'category', @@ -760,7 +705,7 @@ module.exports = { 'develop/dotnet/activities/dynamic-activity', 'develop/dotnet/activities/benign-exceptions', 'develop/dotnet/activities/standalone-activities', - ] + ], }, { type: 'category', @@ -770,9 +715,7 @@ module.exports = { type: 'doc', id: 'develop/dotnet/workers/index', }, - items: [ - 'develop/dotnet/workers/run-worker-process', - ] + items: ['develop/dotnet/workers/run-worker-process'], }, { type: 'category', @@ -782,9 +725,7 @@ module.exports = { type: 'doc', id: 'develop/dotnet/client/index', }, - items: [ - 'develop/dotnet/client/temporal-client', - ], + items: ['develop/dotnet/client/temporal-client'], }, { type: 'category', @@ -794,10 +735,7 @@ module.exports = { type: 'doc', id: 'develop/dotnet/nexus/index', }, - items: [ - 'develop/dotnet/nexus/quickstart', - 'develop/dotnet/nexus/feature-guide', - ], + items: ['develop/dotnet/nexus/quickstart', 'develop/dotnet/nexus/feature-guide'], }, { type: 'category', @@ -807,10 +745,7 @@ module.exports = { type: 'doc', id: 'develop/dotnet/platform/index', }, - items: [ - 'develop/dotnet/platform/observability', - 'develop/dotnet/platform/enriching-ui', - ], + items: ['develop/dotnet/platform/observability', 'develop/dotnet/platform/enriching-ui'], }, { type: 'category', @@ -825,7 +760,7 @@ module.exports = { 'develop/dotnet/best-practices/testing-suite', 'develop/dotnet/best-practices/debugging', 'develop/dotnet/best-practices/converters-and-encryption', - ] + ], }, ], }, @@ -859,7 +794,7 @@ module.exports = { 'develop/ruby/workflows/futures', 'develop/ruby/workflows/dynamic-workflow', 'develop/ruby/workflows/versioning', - ] + ], }, { type: 'category', @@ -876,7 +811,7 @@ module.exports = { 'develop/ruby/activities/asynchronous-activity', 'develop/ruby/activities/dynamic-activity', 'develop/ruby/activities/benign-exceptions', - ] + ], }, { type: 'category', @@ -886,9 +821,7 @@ module.exports = { type: 'doc', id: 'develop/ruby/workers/index', }, - items: [ - 'develop/ruby/workers/run-worker-process', - ] + items: ['develop/ruby/workers/run-worker-process'], }, { type: 'category', @@ -898,9 +831,7 @@ module.exports = { type: 'doc', id: 'develop/ruby/client/index', }, - items: [ - 'develop/ruby/client/temporal-client', - ], + items: ['develop/ruby/client/temporal-client'], }, { type: 'category', @@ -910,10 +841,7 @@ module.exports = { type: 'doc', id: 'develop/ruby/platform/index', }, - items: [ - 'develop/ruby/platform/observability', - 'develop/ruby/platform/enriching-ui', - ], + items: ['develop/ruby/platform/observability', 'develop/ruby/platform/enriching-ui'], }, { type: 'category', @@ -923,9 +851,7 @@ module.exports = { type: 'doc', id: 'develop/ruby/integrations/index', }, - items: [ - 'develop/ruby/integrations/rails-integration', - ], + items: ['develop/ruby/integrations/rails-integration'], }, { type: 'category', @@ -940,7 +866,7 @@ module.exports = { 'develop/ruby/best-practices/testing-suite', 'develop/ruby/best-practices/debugging', 'develop/ruby/best-practices/converters-and-encryption', - ] + ], }, ], }, @@ -1217,16 +1143,45 @@ module.exports = { }, items: [ 'cli/setup-cli', - 'cli/activity', - 'cli/batch', - 'cli/config', - 'cli/env', - 'cli/operator', - 'cli/schedule', - 'cli/server', - 'cli/task-queue', - 'cli/worker', - 'cli/workflow', + 'cli/cloud', + 'cli/cli-basics', + { + type: 'category', + label: 'Command reference', + collapsed: true, + link: { type: 'doc', id: 'cli/command-reference/index' }, + items: [ + 'cli/command-reference/activity', + 'cli/command-reference/batch', + { + type: 'category', + label: 'cloud', + collapsed: true, + link: { type: 'doc', id: 'cli/command-reference/cloud/index' }, + items: [ + 'cli/command-reference/cloud/account', + 'cli/command-reference/cloud/apikey', + 'cli/command-reference/cloud/connectivity', + 'cli/command-reference/cloud/login', + 'cli/command-reference/cloud/logout', + 'cli/command-reference/cloud/namespace', + 'cli/command-reference/cloud/nexus', + 'cli/command-reference/cloud/user', + 'cli/command-reference/cloud/user-group', + 'cli/command-reference/cloud/whoami', + ], + }, + 'cli/command-reference/cmd-options', + 'cli/command-reference/config', + 'cli/command-reference/env', + 'cli/command-reference/operator', + 'cli/command-reference/schedule', + 'cli/command-reference/server', + 'cli/command-reference/task-queue', + 'cli/command-reference/worker', + 'cli/command-reference/workflow', + ], + }, ], }, { diff --git a/vercel.json b/vercel.json index cf17b54fd2..9bd76d6af5 100644 --- a/vercel.json +++ b/vercel.json @@ -5,6 +5,61 @@ "silent": true }, "redirects": [ + { + "source": "/cli/activity", + "destination": "/cli/command-reference/activity", + "permanent": true + }, + { + "source": "/cli/batch", + "destination": "/cli/command-reference/batch", + "permanent": true + }, + { + "source": "/cli/cmd-options", + "destination": "/cli/command-reference/cmd-options", + "permanent": true + }, + { + "source": "/cli/config", + "destination": "/cli/command-reference/config", + "permanent": true + }, + { + "source": "/cli/env", + "destination": "/cli/command-reference/env", + "permanent": true + }, + { + "source": "/cli/operator", + "destination": "/cli/command-reference/operator", + "permanent": true + }, + { + "source": "/cli/schedule", + "destination": "/cli/command-reference/schedule", + "permanent": true + }, + { + "source": "/cli/server", + "destination": "/cli/command-reference/server", + "permanent": true + }, + { + "source": "/cli/task-queue", + "destination": "/cli/command-reference/task-queue", + "permanent": true + }, + { + "source": "/cli/worker", + "destination": "/cli/command-reference/worker", + "permanent": true + }, + { + "source": "/cli/workflow", + "destination": "/cli/command-reference/workflow", + "permanent": true + }, { "source": "/develop/go/data-handling/large-payload-storage", "destination": "/develop/go/data-handling/external-storage",