# Set your scrape configuration targets to the ports exposed on your endpoints in the SDK.
scrape_configs:
  - job_name: 'temporalsdkmetrics'
    metrics_path: /metrics
    scheme: http
    static_configs:
      - targets:
          # This is the scrape endpoint where Prometheus listens for SDK metrics.
          - localhost:8077
        # You can have multiple targets here, provided they are set up in your application code.
```

See the [Prometheus documentation](https://prometheus.io/docs/introduction/first_steps/) for more details on how you can run Prometheus locally or using Docker.

Note that Temporal Cloud exposes metrics through a [Prometheus HTTP API endpoint](https://prometheus.io/docs/prometheus/latest/querying/api/) (not a scrape endpoint) that can be configured as a data source in Grafana.
The Prometheus configuration described here is for scraping metrics data on endpoints for SDK metrics only.

To check whether Prometheus is receiving metrics from your SDK target, go to [http://localhost:9090](http://localhost:9090) and navigate to **Status&nbsp;> Targets**.
The status of your target endpoint defined in your configuration appears here.

## Grafana data sources configuration {#grafana-data-sources-configuration}

**How to configure data sources for Temporal Cloud and SDK metrics in Grafana.**

Depending on how you use Grafana, you can either install and run it locally, run it as a Docker container, or log in to Grafana Cloud to set up your data sources.

If you have installed and are running Grafana locally, go to [http://localhost:3000](http://localhost:3000) and sign in.

You must configure your Temporal Cloud and SDK metrics data sources separately in Grafana.

To add the Temporal Cloud Prometheus HTTP API endpoint that we generated in the [Temporal Cloud metrics setup](/cloud/metrics/general-setup) section, do the following:

1. Go to **Configuration&nbsp;> Data sources**.
1. Select **Add data source&nbsp;> Prometheus**.
1. Enter a name for your Temporal Cloud metrics data source, such as _Temporal Cloud metrics_.
1. In the **Connection** section, paste the URL that was generated in the Observability section on the Temporal Cloud UI.
1. The **Authentication** section may be left as **No Authentication**.
1. In the **TLS Settings** section, select **TLS Client Authentication**:
   - Leave **ServerName** blank. This is not required.
   - Paste in your end-entity certificate and key.
   - Note that the end-entity certificate used here must be part of the certificate chain with the root CA certificates used in your [Temporal Cloud observability setup](/cloud/metrics/general-setup).
     <ZoomingImage src="/img/cloud/prometheus/add-prometheus-api-endpoint.png" alt="Data source configuration in Grafana" />
1. Click **Save and test** to verify that the data source is working.

If you see issues in setting this data source, verify your CA certificate chain and ensure that you are setting the correct certificates in your Temporal Cloud observability setup and in the TLS authentication in Grafana.

To add the SDK metrics Prometheus endpoint that we configured in the [SDK metrics setup](#sdk-metrics-setup) and [Prometheus configuration for SDK metrics](#prometheus-configuration) sections, do the following:

1. Go to **Configuration&nbsp;> Data sources**.
2. Select **Add data source&nbsp;> Prometheus**.
3. Enter a name for your Temporal Cloud metrics data source, such as _Temporal SDK metrics_.
4. In the **HTTP** section, enter your Prometheus endpoint in the URL field.
   If running Prometheus locally as described in the examples in this article, enter `http://localhost:9090`.
5. For this example, enable **Skip TLS Verify** in the **Auth** section.
6. Click **Save and test** to verify that the data source is working.

If you see issues in setting this data source, check whether the endpoints set in your SDKs are showing metrics.
If you don't see your SDK metrics at the scrape endpoints defined, check whether your Workers and Workflow Executions are running.
If you see metrics on the scrape endpoints, but Prometheus shows your targets are down, then there is an issue with connecting to the targets set in your SDKs.
Verify your Prometheus configuration and restart Prometheus.

If you're running Grafana as a container, you can set your SDK metrics Prometheus data source in your Grafana configuration.
See the example Grafana configuration described in the [Prometheus and Grafana setup for open-source Temporal Service](/self-hosted-guide/monitoring#grafana) article.

### Grafana dashboards setup

To set up dashboards in Grafana, you can use the UI or configure them directly in your Grafana deployment.

:::tip

Temporal provides community-driven example dashboards for [Temporal Cloud](https://github.com/temporalio/dashboards/tree/master/cloud) and [Temporal SDKs](https://github.com/temporalio/dashboards/tree/master/sdk) that you can customize to meet your needs.

:::

To import a dashboard in Grafana:

1. In the left-hand navigation bar, select **Dashboards** > **Import dashboard**.
2. You can either copy and paste the JSON from the [Temporal Cloud](https://github.com/temporalio/dashboards/tree/master/cloud) and [Temporal SDK](https://github.com/temporalio/dashboards/tree/master/sdk) sample dashboards, or import the JSON files into Grafana.
3. Save the dashboard and review the metrics data in the graphs.

To configure dashboards with the UI:

1. Go to **Create > Dashboard** and add an empty panel.
2. On the **Panel configuration** page, in the **Query** tab, select the "Temporal Cloud metrics" or "Temporal SDK metrics" data source that you configured earlier.
   If you need to add multiple queries from both data sources, choose `–Mixed–`.
3. Add your metrics queries:
   - For Temporal Cloud metrics, expand the **Metrics browser** and select the metrics you want.
     You can also select associated labels and values to sort the query data.
     The [Cloud metrics documentation](/cloud/metrics/reference) lists all metrics emitted from Temporal Cloud.
   - For Temporal SDK metrics, expand the **Metrics browser** and select the metrics you want.
     A list of Worker performance metrics is described in the [Developer's Guide - Worker performance](/develop/worker-performance).
     All SDK-related metrics are listed in the [SDK metrics](/references/sdk-metrics) reference.
4. The graph should now display data based on your selected queries.
   Note that SDK metrics will only show if you have Workflow Execution data and running Workers.
   If you don't see SDK metrics, run your Worker and Workflow Executions, then monitor the dashboard.

---

## PromQL Metrics

:::tip

Need to scrape metrics into your observability stack? Try out the new [OpenMetrics endpoint](/cloud/metrics/openmetrics).

:::

Metrics for all Namespaces in your account are available from your metrics endpoint. Keep in mind that your Temporal Cloud metrics lag real-time performance by about one minute. Temporal Cloud also only retains raw metrics for seven days.

To ensure security of your metrics, a CA certificate dedicated to observability is required.
Only clients that use certificates signed by that CA, or that chain up to the CA, can query the metrics endpoint.
For more information about CA certificates in Temporal Cloud, see [Certificate requirements](/cloud/certificates#certificate-requirements).

- [General setup](/cloud/metrics/general-setup)
- [Available metrics](/cloud/metrics/reference)
- [Prometheus & Grafana setup](/cloud/metrics/prometheus-grafana)
- [Datadog setup](/cloud/metrics/datadog)

---

## Temporal Cloud metrics reference

A metric is a measurement or data point that provides insights into the performance and health of a system.
This document describes the metrics available on the Temporal Cloud platform.
Temporal Cloud metrics help you monitor performance and troubleshoot errors.
They provide insights into different aspects of the Service.

This document describes:

- **[Available Temporal Cloud metrics](#available-metrics)**:
  The metrics emitted by Temporal Cloud include counts of gRPC errors, requests, successful task matches to a poller, and more.
- **[Metrics labels](#metrics-labels)**:
  Temporal Cloud metrics labels can filter metrics and help categorize and differentiate results.
- **[Operations](#metrics-operations)**:
  An operation is a special type of label that categorizes the type of operation being performed when the metric was collected.

:::info SDK METRICS

This document discusses metrics emitted by [Temporal Cloud](/cloud).
Temporal SDKs also emit metrics, sourced from Temporal Clients and Worker processes.
You can find information about Temporal SDK metrics on its [dedicated page](/references/sdk-metrics).

Please note:

- SDK metrics start with the phrase `temporal_`.
- Temporal Cloud metrics start with `temporal_cloud_`.

:::

## Available Temporal Cloud metrics {#available-metrics}

**What metrics are emitted from Temporal Cloud?**

The following metrics are emitted for your Namespaces:

### Frontend Service metrics {#frontend}

#### temporal_cloud_v0_frontend_service_error_count

This is a count of gRPC errors returned aggregated by operation.
Labels: temporal_account, temporal_namespace, operation, temporal_service_type

#### temporal_cloud_v0_frontend_service_request_count

This is a count of gRPC requests received aggregated by operation.
Labels: temporal_account, temporal_namespace, operation, temporal_service_type

#### temporal_cloud_v0_resource_exhausted_error_count

gRPC requests received that were rate-limited by Temporal Cloud, aggregated by cause.
Labels: temporal_account, temporal_namespace, resource_exhausted_cause

#### temporal_cloud_v0_state_transition_count

Count of state transitions for each Namespace.

#### temporal_cloud_v0_total_action_count

Approximate count of Temporal Cloud Actions.
Labels: temporal_account, temporal_namespace, is_background, namespace_mode

### Poll metrics {#poll}

#### temporal_cloud_v0_poll_success_count

Tasks that are successfully matched to a poller.
Labels: temporal_account, temporal_namespace, operation, task_type, temporal_service_type

#### temporal_cloud_v0_poll_success_sync_count

Tasks that are successfully sync matched to a poller.
Labels: temporal_account, temporal_namespace, operation, task_type, temporal_service_type

#### temporal_cloud_v0_poll_timeout_count

When no tasks are available for a poller before timing out.
Labels: temporal_account, temporal_namespace, operation, task_type, temporal_service_type

### Replication lag metrics {#replication-lag}

#### temporal_cloud_v0_replication_lag_bucket

A histogram of [replication lag](/cloud/high-availability/monitoring#replication-lag-metric) during a specific time interval for a Namespace with high availability.
Labels: temporal_account, temporal_namespace, le

#### temporal_cloud_v0_replication_lag_count

The [replication lag](/cloud/high-availability/monitoring#replication-lag-metric) count during a specific time interval for a Namespace with high availability.
Labels: temporal_account, temporal_namespace

#### temporal_cloud_v0_replication_lag_sum

The sum of [replication lag](/cloud/high-availability/monitoring#replication-lag-metric) during a specific time interval for a Namespace with high availability.
Labels: temporal_account, temporal_namespace

### Schedule metrics {#schedule}

#### temporal_cloud_v0_schedule_action_success_count

Successful execution of a Scheduled Workflow.
Labels: temporal_account, temporal_namespace

#### temporal_cloud_v0_schedule_buffer_overruns_count

When average schedule run length is greater than average schedule interval while a `buffer_all` overlap policy is configured.
Labels: temporal_account, temporal_namespace

#### temporal_cloud_v0_schedule_missed_catchup_window_count

Skipped Scheduled executions when Workflows were delayed longer than the catchup window.
Labels: temporal_account, temporal_namespace

#### temporal_cloud_v0_schedule_rate_limited_count

Workflows that were delayed due to exceeding a rate limit.
Labels: temporal_account, temporal_namespace

### Service latency metrics {#service-latency}

#### temporal_cloud_v0_service_latency_bucket

Latency for `SignalWithStartWorkflowExecution`, `SignalWorkflowExecution`, `StartWorkflowExecution` operations.
Labels: temporal_account, temporal_namespace, le, operation, temporal_service_type

#### temporal_cloud_v0_service_latency_count

Count of latency observations for `SignalWithStartWorkflowExecution`, `SignalWorkflowExecution`, `StartWorkflowExecution` operations.
Labels: temporal_account, temporal_namespace, operation, temporal_service_type

#### temporal_cloud_v0_service_latency_sum

Sum of latency observation time for `SignalWithStartWorkflowExecution`, `SignalWorkflowExecution`, `StartWorkflowExecution` operations.
Labels: temporal_account, temporal_namespace, operation, temporal_service_type

### Workflow metrics {#workflow}

#### temporal_cloud_v0_workflow_cancel_count

Workflows canceled before completing execution.
Labels: temporal_account, temporal_namespace, operation, temporal_service_type

#### temporal_cloud_v0_workflow_continued_as_new_count

Workflow Executions that were Continued-As-New from a past execution.
Labels: temporal_account, temporal_namespace, operation, temporal_service_type

#### temporal_cloud_v0_workflow_failed_count

Workflows that failed before completion.
Labels: temporal_account, temporal_namespace, operation, temporal_service_type

#### temporal_cloud_v0_workflow_success_count

Workflows that successfully completed.
Labels: temporal_account, temporal_namespace, operation, temporal_service_type

#### temporal_cloud_v0_workflow_terminate_count

Workflows terminated before completing execution.
Labels: temporal_account, temporal_namespace, operation, temporal_service_type

#### temporal_cloud_v0_workflow_timeout_count

Workflows that timed out before completing execution.
Labels: temporal_account, temporal_namespace, operation, temporal_service_type

## Metrics labels {#metrics-labels}

**What labels can you use to filter metrics?**

Temporal Cloud metrics include key-value pairs called labels in their associated metadata.
Labels help you categorize and differentiate metrics for precise filtering, querying, and aggregation.
Use labels to specific attributes or compare values, such as numeric buckets in histograms.
This added context enhances the monitoring and analysis capabilities, providing deeper insights into your data.

Use the following labels to filter metrics:

| Label                      | Explanation                                                                                                                                                                                                                                                                                |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `le`                       | Less than or equal to (`le`) is used in histograms to categorize observations into buckets based on their value being less than or equal to a predefined upper limit.                                                                                                                      |
| `operation`                | This includes gRPC operations and general Cloud operations such as:SignalWorkflowExecutionStartBatchOperationStartWorkflowExecutionTaskQueueMgrTerminateWorkflowExecutionUpdateNamespaceUpdateSchedule See: [Metric Operations](#metrics-operations) and [Temporal Cloud Operation reference](/references/operation-list)|
| `resource_exhausted_cause` | Cause for resource exhaustion.                                                                                                                                                                                                                                                             |
| `task_type`                | Activity, Workflow, or Nexus.                                                                                                                                                                                                                                                              |
| `temporal_account`         | Temporal Account.                                                                                                                                                                                                                                                                          |
| `temporal_namespace`       | Temporal Namespace.                                                                                                                                                                                                                                                                        |
| `temporal_service_type`    | Frontend or Matching or History or Worker.                                                                                                                                                                                                                                                 |
| `is_background`            | This label on `temporal_cloud_v0_total_action_count` indicates when actions are produced by a Temporal background job, for example: hourly Workflow Export.                                                                                                                                |
| `namespace_mode`           | This label on `temporal_cloud_v0_total_action_count` indicates if actions are produced by an active vs a standby Namespace. For a regular Namespace, `namespace_mode` will always be “active”.                                                                                             |

The following is an example of how you can filter metrics using labels:

```text
temporal_cloud_v0_poll_success_count{__rollup__="true", operation="TaskQueueMgr", task_type="Activity", temporal_account="12345", temporal_namespace="your_namespace.12345", temporal_service_type="matching"}
```

## Operations {#metrics-operations}

**What operation labels are captured by Temporal Cloud?**

Operations are a special class of metrics label.
They describe the context during which a metric was captured.
Temporal Cloud includes the following operations labels:

- AdminDescribeMutableState
- AdminGetWorkflowExecutionRawHistory
- AdminGetWorkflowExecutionRawHistoryV2
- AdminReapplyEvents
- CountWorkflowExecutions
- CreateSchedule
- DeleteSchedule
- DeleteWorkflowExecution
- DescribeBatchOperation
- DescribeNamespace
- DescribeSchedule
- DescribeTaskQueue
- DescribeWorkflowExecution
- GetWorkerBuildIdCompatibility
- GetWorkerTaskReachability
- GetWorkflowExecutionHistory
- GetWorkflowExecutionHistoryReverse
- ListBatchOperations
- ListClosedWorkflowExecutions
- OperatorDeleteNamespace
- PatchSchedule
- PollActivityTaskQueue
- PollNexusTaskQueue
- PollWorkflowExecutionHistory
- PollWorkflowExecutionUpdate
- PollWorkflowTaskQueue
- QueryWorkflow
- RecordActivityTaskHeartbeat
- RecordActivityTaskHeartbeatById
- RegisterNamespace
- RequestCancelWorkflowExecution
- ResetStickyTaskQueue
- ResetWorkflowExecution
- RespondActivityTaskCanceled
- RespondActivityTaskCompleted
- RespondActivityTaskCompletedById
- RespondActivityTaskFailed
- RespondActivityTaskFailedById
- RespondNexusTaskCompleted
- RespondNexusTaskFailed
- RespondQueryTaskCompleted
- RespondWorkflowTaskCompleted
- RespondWorkflowTaskFailed
- SignalWithStartWorkflowExecution
- SignalWorkflowExecution
- StartBatchOperation
- StartWorkflowExecution
- StopBatchOperation
- TerminateWorkflowExecution
- UpdateNamespace
- UpdateSchedule
- UpdateWorkerBuildIdCompatibility
- UpdateWorkflowExecution

As the following table shows, certain [metrics groups](#available-metrics) support [operations](#metrics-operations) for aggregation and filtering:

| Metrics Group / Operations                      | All Operations | SignalWithStartWorkflowExecution / SignalWorkflowExecution / StartWorkflowExecution | TaskQueueMgr | CompletionStats |
| ----------------------------------------------- | -------------- | ----------------------------------------------------------------------------------- | ------------ | --------------- |
| **[Frontend Service Metrics](#frontend)**       | X              |                                                                                     |              |                 |
| **[Service Latency Metrics](#service-latency)** |                | X                                                                                   |              |                 |
| **[Poll Metrics](#poll)**                       |                |                                                                                     | X            |                 |
| **[Workflow Metrics](#workflow)**               |                |                                                                                     |              | X               |

---

## Automated Migration

Automated migration is designed to provide a zero-downtime, secure means of migrating to Temporal Cloud. This guide outlines the current process
for transitioning workflows from a self-hosted setup to one hosted within Temporal Cloud.

:::tip Support, stability, and dependency info

Automated migration is currently in [Pre-release](/evaluate/development-production-features/release-stages#pre-release).

:::

### Solution overview

As illustrated below, there are 2 components that support automated migrations:

1. Migration proxy - The [s2s proxy](https://hub.docker.com/r/temporalio/s2s-proxy/tags) provides a security layer between the self-hosted server
   and the migration server. The customer-side proxy is installed on your infrastructure, while the cloud-side proxy is managed by Temporal. Communications to the
   proxies are secured via [mutual TLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/) (mTLS).
2. Migration server - A Temporal service (server) enables secure connections between your self-hosted setup and Temporal Cloud. It provides the core
   functionality of the service.

![Temporal automated migration components](/img/cloud/migration/auto-migration-components.png)

### Process overview

The migration process is separated into several phases, part of which involves coordinating with Temporal to create necessary cloud-side resources.

Migration involves the following phases:

1. Prepare - Preparing for a migration will require you to deploy a customer-side migration proxy, and will also involve coordinating with Temporal to
   configure a migration server.
2. Initiate - Use the _[StartMigrationRequest](https://pkg.go.dev/github.com/temporalio/tcld#readme-start-a-migration)_ API to specify namespaces for migration along with endpoint
   details.
   A corresponding namespace is created in Temporal Cloud with a “non-active” status. You will configure permissions and access controls during this phase.
3. Monitor - The _[GetMigrationResponse](https://pkg.go.dev/github.com/temporalio/tcld#readme-get-a-migration)_ API allows you to track replication progress, including workflows
   replicated, remaining workflows, and estimated
   time for completion.
4. Handover - Once replication is complete, you may use the _[HandoverNamespaceRequest](https://pkg.go.dev/github.com/temporalio/tcld#readme-perform-handover-during-a-migration)_ API to switch traffic between your source namespace (self-hosted)
   and target namespace (cloud). This is the opportunity to validate functionality within Temporal Cloud prior to finalizing the migration.
5. Finalize - Use _[ConfirmMigrationRequest](https://pkg.go.dev/github.com/temporalio/tcld#readme-confirm-a-migration)_ API to finalize the migration. In the event of issues, you may use
   the _[AbortMigrationRequest](https://pkg.go.dev/github.com/temporalio/tcld#readme-abort-a-migration)_ to
   roll-back changes without impacting your workflows. These APIs provide granular control over every step of the process, ensuring transparency and flexibility.

### Current limitations

The following are known limitations for the Pre-release phase of this service.

- OSS server versions 1.22 or newer are required. Refer to the [upgrade](https://docs.temporal.io/self-hosted-guide/upgrade-server#upgrade-server) procedure as needed.
- History shard counts must be a multiple of two.
- Enabling payload encryption as part of migration is not yet supported. If payloads are already [encrypted](https://docs.temporal.io/payload-codec#encryption) in your self-hosted server
  via data converter, then they will remain encrypted during and after migration.
- If you are using multi-cluster replication in your self-hosted setup and have previously failed over namespaces, then this may impact your eligibility for automated migration.
- If you have multiple self-hosted servers and they are all configured with the same cluster name (by default Temporal uses 'active' as cluster name), they cannot be connected to
  a single migration server simultaneously due to cluster name collision. There are 2 available options:
  1. Migrate one server at a time using a single migration server.
  2. Create multiple migration servers (one for each self-hosted server) if you need to migrate all servers simultaneously.
- OSS supports cross-namespace commands (e.g., parent-child, SignalExternal, CancelExternal) through the `system.enableCrossNamespaceCommands` configuration. This
  configuration is disabled on Temporal Cloud. If cross-namespace calls exist within workflow code, they must be updated or removed prior to migration.

### Getting started

To prepare for migration, you must first provide qualification details to Temporal via a support ticket. If eligible, the Temporal team will work with you to facilitate your migration.

Submit a support ticket with the following details:

- A list of your Temporal accounts
- Target Temporal Cloud service regions
- For each cluster, provide the server configuration by running `temporal operator cluster describe --address <frontend:7233> --output json` (see [notes](#alternative-commands-for-versions-1281-and-prior) for Temporal server version 1.28.1 and prior).
- Metrics for the namespaces to be migrated:
  - number of open/closed workflows
  - storage used
  - retention policy
  - any custom search attributes
  - peak request per second (RPS) and action per second (APS) - refer to [this document](https://docs.google.com/document/d/151xjeI53SBfJ94X1toi5krPp4oeyzJ6wVUrOBhgK714) for instructions on fetching these metrics
- If you use a SQL-based datastore for visibility, and you use custom search attributes, provide _CustomSearchAttributeAliases_ of your namespace by running
  temporal operator namespace describe using the [latest Temporal CLI](https://github.com/temporalio/cli).

:::warning

Proceed only when your request has been approved by Temporal.

:::

### Create cloud-side resources

Cloud-side resources must be in place prior to starting a migration. Complete the following procedure.

1. Create one or more empty namespaces in Temporal Cloud to serve as the migration targets. Since migration cannot proceed into a namespace that's already in use, these namespaces should
   remain empty (no workflows).
2. Create a support ticket requesting these namespaces be configured with [system limits](https://docs.temporal.io/cloud/limits)
   (including APS/RPS) matching your existing self-hosted workload.
3. Verify that a migration endpoint has been created in Temporal Cloud (e.g., `your-endpoint.{your-acct}.tmprl.cloud`). If you don't have one, request one via a support ticket.
4. Create any required custom search attributes used by your workflow.
5. If you need [private connectivity](https://docs.temporal.io/cloud/connectivity) for the namespace in Temporal Cloud, then prepare this setup in advance.

### Prepare your self-hosted service

1. Set the following [dynamic configurations](https://docs.temporal.io/references/dynamic-configuration) settings and then restart the Temporal frontend.

   ```yaml
   frontend.keepAliveMaxConnectionAge:
   - value: "2h"
   ```

2. If not already enabled, enable _GlobalNamspace_ by updating the _clusterMetadata_ and the _dcRedirectionPolicy_ in your [server config yaml file](https://github.com/temporalio/temporal/tree/main/config) to
   the following and restart all Temporal services (frontend, history, matching, worker), starting with the frontend.

   ```yaml
   dcRedirectionPolicy:
      policy: "all-apis-forwarding"

   clusterMetadata:
   enableGlobalNamespace: true # add this
   failoverVersionIncrement: 1000000 # to match failoverVersionIncrement in our migration server
   masterClusterName: _NO_CHANGE_
   currentClusterName: _NO_CHANGE_
   clusterInformation:
      _NO_CHANGE_:
         enabled: true
         initialFailoverVersion: [1,100] # pick a unique number between 1 and 100 for each server 
         rpcName: _NO_CHANGE_
         rpcAddress: _NO_CHANGE_
   ```

3. Run `temporal operator cluster describe` to check the output. The following output is expected:

   ```yaml
   "failoverVersionIncrement": "1000000",
   "initialFailoverVersion": "the number you picked"
   "isGlobalNamespaceEnabled": true
   ```

4. Create a CA certificate as a PEM file and share it in your support ticket. This is required for [mutual TLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/) (mTLS)
   between your s2s-proxy (as client) and the Temporal s2s-proxy (as server). Note that this differs from the CA used for [accessing namespace](https://docs.temporal.io/cloud/certificates)
   in Temporal Cloud.

### Deploying the self-hosted s2s proxy

Complete the following steps in order to deploy and test the self-hosted s2s proxy. The proxy needs to be accessible from your server and requires a public internet connection to connect
to the Temporal s2s-proxy via migration endpoint.

1. Obtain the latest Docker image from the [temporalio/s2s-proxy repository](https://hub.docker.com/r/temporalio/s2s-proxy/tags).
2. Gather the CA certificate generated in the previous steps.
3. Deploy 1 replica of the s2s-proxy (minimum 4 CPU and 512mb memory) and configure s2s-proxy using our [helm chart example](https://github.com/temporalio/s2s-proxy/blob/main/charts/s2s-proxy/README.md) as a reference.
4. Test access by running `temporal operator cluster describe --address {the-outbound-external-address-of-your-proxy}`. It should display the information of the migration server.
5. Request the Temporal team to perform a similar test to verify that the migration server can access your server.

Proceed only when you have received confirmation from Temporal that connectivity tests have passed.

### Migration process

Once all prerequisites have been completed, migration may commence.

#### Migration start

A Temporal operator will initiate the following migration commands on your behalf. The migration proceeds through these phases:

1. Start migration - Your self-hosted namespace remains active while the cloud namespace becomes passive. Workflows are replicated from the self-hosted namespace to the cloud namespace.
   Once cloud namespace is in-sync with self-hosted namespace, migration is ready for handover.
2. Handover to the Cloud - The cloud namespace becomes active and the self-hosted namespace becomes passive. Workflows are then replicated from the cloud namespace to the self-hosted server.
3. Confirm migration completion - Workflow replication from the cloud namespace to the self-hosted server stops.

Before the final step, it is possible to hand over the namespace back to the self-hosted server or abort the migration process completely. After this step, migrating namespaces from the cloud
back to a self-hosted server is an unsupported operation.

#### Transfer to cloud

There are two options for switching Temporal clients to the cloud:

- Option 1 (recommended) - Deploy two sets of Temporal clients: one pointing to your Temporal server and one to the Cloud namespace endpoint. This is the recommended option since your workflows will
  continue to make progress during the handover, even if your cloud Temporal client is unable to access the cloud (due to misconfiguration, for example). The process is as follows:
  1. Direct your cloud-based Temporal clients to the cloud namespace endpoint. Initially, these clients will connect and send Poll requests but will not receive any tasks.
  2. Start migration. Your self-hosted namespace is active while your cloud namespace is passive (or standby). Your cloud Temporal clients can begin receiving tasks, but all requests
     from cloud clients to the Cloud namespace will automatically forward from the cloud to your self-hosted server.
  3. Hand over namespace to the cloud. Your cloud namespace becomes active and your self-hosted namespace becomes passive. All requests from your self-hosted Temporal clients will
     automatically forward from your server to the cloud.
  4. Complete migration. Your self-hosted Temporal clients will no longer receive any tasks from your server, allowing you to stop these clients.

- Option 2 - Deploy one set of Temporal clients and switch the namespace endpoint during migration. With this option, if your workers are misconfigured during the switch, then it is
  possible that workflows can stop making progress. It is important to ensure that all workers maintain connectivity to cloud to avoid this scenario.
  The process is as follows:
  1. Start migration.
  2. Switch your Temporal clients to point to the cloud namespace endpoint. Requests from your Temporal clients will automatically forward from the cloud to your server. Alternatively, you may
     switch Temporal clients to the cloud namespace endpoint after handover.
  3. Hand over namespace to the cloud. Requests from your Temporal clients will now be served by the cloud and will not be forwarded to your server.
  4. Confirm migration completion.

#### Final Validation

Before failing over your namespace to Temporal Cloud, review the following production readiness checklist. These steps help ensure a smooth transition and minimize surprises in production.

- Understand how to access metrics for your namespace on Temporal Cloud.
- General workflow monitoring metrics (schedule to start latency, start v.s. completion rate, sync match rate, etc).
- Learn how capacity management works in Temporal Cloud, including how to request capacity increases.
- Plan for a worker tuning session - performance change between Temporal Cloud v.s. self-hosted cluster, which could lead to unexpected symptoms and optimizations.
- Know how to reach out to your Temporal Solutions Architect (SA) and Account Executive (AE) for assistance.

### Additional Notes

#### Special dynamic configuration for Version 1.22.x-1.23.x
Temporal versions 1.22.x and 1.23.x include support for stream-based replication, but it is disabled by default. Since those releases, stream-based replication has been validated as more reliable than the poll-based replication that remained the default in 1.22 and 1.23. 

When preparing for an S2C migration on these versions, configure the following dynamic settings to enable stream-based replication:

```yaml
history.enableReplicationStream:
  - value: true
```

Enabling this configuration will require a restart of your history pods. 

#### Alternative Commands for Versions 1.28.1 and Prior
The `temporal operator cluster describe` command is missing some details needed for migration when run against Version 1.28.1 or older. If you are running that version of Temporal or older, then substitute the below
commands for the "temporal operator cluster describe" command cited in this document. 

If you are using tctl, then substitute the following command: `tctl --address <frontend:7233> admin cluster describe`

If you are not a tctl user, then use the following alternative:
`grpcurl -v -plaintext <your temporal address and port> temporal.server.api.adminservice.v1.AdminService.DescribeCluster`

---

## Migrate

Learn how to migrate your Temporal workflows with zero downtime:

- [Automated Migration](/cloud/migrate/automated) - This process enables seamless transitions from self-hosted Temporal instances to Temporal Cloud.
- [Manual Migration](/cloud/migrate/manual) - This process enables transitions from self-hosted Temporal instances to Temporal Cloud by updating clients
  and workflows to utilize new resources within Temporal Cloud.
- [Migrate between regions](/cloud/migrate/migrate-within-cloud) - This process allows you to migrate a Temporal Cloud Namespace between regions or providers.

---

## Manual Migration

Migrating to Temporal Cloud from a self-hosted Temporal Service will have different requirements depending on your usage.
This guide provides some guidance based on our experience helping customers of all sizes successfully migrate.

### What to expect from a migration

Depending on your Workflows' requirements, the migration process may be as simple as changing a few parameters, or may require more extensive code changes.
There are two aspects to consider when migrating: your Temporal Client connection code and your Workflow Executions.
Here's a high-level overview of what you can expect:

- **Introduce another Temporal Client to your Starter and Worker Processes:** Configure and deploy a new Temporal Client so that Temporal Cloud becomes responsible for new Workflow Executions.
- **Migrate Workflow Executions:** There are different approaches for new, running, and completed Workflow Executions.
  - **New Workflow Executions:** When you no longer need to send Signals or Queries to your self-hosted Temporal Service, you can deprecate your old Client code. Until then, your self-hosted Temporal Service can receive relevant traffic, while new Workflow Executions are sent to Temporal Cloud.
  - **Running Workflow Executions:** Short-running Workflows can often be drained and then started again on Temporal Cloud. Long-running Workflows that cannot be drained might require you to implement more code changes to pass the state of the currently running Workflow to Temporal Cloud.
  - **Completed Workflow Executions:** Completed Workflow Execution History cannot be automatically migrated to Temporal Cloud. Refer to [Multi-Cluster Replication](#multi-cluster-replication) for more information.

### Updating Client connection code in your Workers

Whether you're self-hosting Temporal or using Temporal Cloud, you manage runtime of your code.
To migrate your Workflows to Temporal Cloud, you need to change some parameters in the Client connection code, such as updating the namespace and gRPC endpoint.

The changes needed to direct your Workflow to your Temporal Cloud
Namespace are only a few lines of code, including:

- [Add your SSL certificate and private key](/cloud/saml) associated with your Namespace.
- [Copy the Cloud-hosted endpoint](/cloud/namespaces#temporal-cloud-grpc-endpoint) from the Namespace detail Web page.
  The endpoint uses this format: `<namespace_id>.<account_id>.tmprl.cloud:port`.
- [Connect to Temporal Cloud](/cloud/get-started) with your Client.
- [Configure tcld, the Cloud CLI](/cloud/tcld), with the same address, Namespace, and
  certificate used to create a Client through code.

### Migrating your Workflow Executions

A Temporal Service stores the complete Event History for the entire lifecycle of a
Workflow Execution.
To migrate from a self-hosted Temporal Service to Temporal Cloud, take into account the current state, Event History, and any future expectations of your Workflow Executions.

**New Workflows are automatically executed on Temporal Cloud.**
Once you've made the code changes in Step 1, and your new code is deployed, new Workflow Executions will be sent to Temporal Cloud.
Existing Workflows must receive Signals to migrate and re-execute on Cloud.
If you maintain your self-hosted instance, you will still be able to use it to access any execution history from before your migration.
You can also export JSON from your previous execution history, that you can then import into your own analytics system.

**Running Workflows can either be drained or migrated.**
If your Workflow can be completed before any compelling event which drives a move to Temporal Cloud, those Workflows can be automatically restarted on Temporal Cloud.
If your Workflows need to run continuously, you must migrate Workflows while they are running.
To accomplish this migration, cancel your current Workflow and pass the current state to a new Workflow in Temporal Cloud.
Refer to [this repository](https://github.com/temporalio/temporal-migration) for an example of migrating running Workflows in Java.

When performing a live migration, make sure your Worker capacity can support the migration load.
Both a [Signal](/sending-messages#sending-signals) and a [Query](/sending-messages#sending-queries) will be executed during the course of the migration.
Also, the Query API loads the entire history of Workflows into Workers to compute the result (if they are not already cached).
That means that your self-hosted Temporal Service Worker capacity will need to support having those executions in memory to serve those requests.
The volume of these requests might be high to execute against all the matches to a `ListFilter`.

### Considerations when resuming Workflows on a new Temporal Service or Namespace

- **Skipping Steps:** If your Workflow steps cannot guarantee idempotency, determine whether you need to skip those steps when resuming the execution in the target Namespace.
- **Elapsed Time:** If your Workflow is “resuming sleep” when in the target Namespace, determine how you will calculate the delta for the sleep invocation in the new execution.
- **Child Relationships:** If your Workflow has Child Workflow relationships (other than Detached Parent Close Policy children), determine how you can pass the state of those children into the parent to execute the child in a resumed state.
- **Heartbeat state:** If you have long running activities relying on heartbeat state, determine how you can resume these activities in the target Namespace.
- Child Workflows with the same type as their Parent types are returned in List Filters used to gather relevant executions. Unless these are Detached `ParentClosePolicy` children, this is not what you want since the Parent/Child relationship will not be carried over to the target Namespace.
- Long running activities that use heartbeat details will not receive the latest details in the target Namespace.
- Duration between Awaitables inside a Workflow definition needs to be considered for elapsed time accuracy when resuming in the target Namespace.
- When Signaling directly from one Workflow to another, make sure to handle `NotFound` executions in the target Namespace. The Workflows may resume out of order.

### Other considerations when migrating

- Have you added an mTLS certificate to your Temporal Namespace? Review our [documentation for adding a certificate to your Temporal Cloud account](/cloud/certificates) for more information.
- There are differences in how metrics are generated in self-hosted Temporal and Temporal Cloud. Review the [documentation on Temporal Cloud metrics](/cloud/metrics/) for more information.
- Consider the implications for [security and access to your Temporal Service](/cloud/security).
- Review your current load (actions per second) and speak to your Account Executive and Solutions Architect so we can set appropriate [Namespace limits](/cloud/limits).

### Multi-Cluster Replication

[Multi-Cluster Replication](/self-hosted-guide/multi-cluster-replication) is an experimental feature which asynchronously replicates Workflow Executions from active Clusters to other passive Clusters for backup and state reconstruction.
Migrating Execution History from a self-hosted Temporal Service to Temporal Cloud is not currently supported.
However, a migration tool based on Multi-Cluster Replication, which will enable this, is currently in development for Temporal Cloud.
If you have used this feature locally or you are interested in using it to migrate to Temporal Cloud, [create a support ticket](https://docs.temporal.io/cloud/support) or watch this space for more information about public availability.

---

## Migrate between regions

Temporal Cloud's [High Availability features](/cloud/high-availability) allow you to migrate a Temporal Cloud Namespace from one region or cloud provider to another with zero downtime.

## Preparing to migrate

Namespaces using Export will need to stop Export and migrate the region configuration to the new region for Export jobs to continue after migration. 
See [failover scenarios](/cloud/export#failover-scenarios) for details.

[Using High Availability features affects pricing](/cloud/pricing#high-availability-features).

## Steps to migrate

1. Add a Namespace replica in the region you want to migrate to. See [regions](/cloud/regions) for a list of available regions and supported multi-region and multi-cloud configurations.

<CaptionedImage
    src="/img/cloud/high-availability/migrate/1-add-replica.png"
    title="Add a namespace replica"
    zoom="true"
/>

<CaptionedImage
    src="/img/cloud/high-availability/migrate/2-choose-region.png"
    title="Choose the region for the replica"
    zoom="true"
/>

2. Wait for the replica to become active. The Cloud UI will display a time estimate, and namespace admins will receive an email when the replica is active.
3. If your workers are using API key authentication: ensure your workers (and all other client code) are updated to [use the regional endpoint of the new replica](/cloud/namespaces#access-namespaces).
4. Trigger a failover to the new region.

<CaptionedImage
    src="/img/cloud/high-availability/migrate/3-failover.png"
    title="Initiate failover to the new region"
    zoom="true"
/>

5. Remove the Namespace replica in the region you are migrating from.

:::note
If using [API keys](/cloud/api-keys) for worker authentication, you must open a [support ticket](/cloud/support#support-ticket) to remove the replica.

:::

<CaptionedImage
    src="/img/cloud/high-availability/migrate/4-remove-replica.png"
    title="Remove the replica for the original region"
    zoom="true"
/>

:::note
All replica changes are subject to a [cooldown period](/cloud/high-availability/enable#changing) before further replica changes can be made.

:::

---

## Nexus

:::tip SUPPORT, STABILITY, and DEPENDENCY INFO

Temporal Nexus is now [Generally Available](/evaluate/development-production-features/release-stages#general-availability).
Learn why you should use Nexus in the [evaluation guide](/evaluate/nexus).

:::

[Temporal Nexus](/nexus) allows you to connect Temporal Applications across (and within) isolated Namespaces.
This provides all the benefits of Durable Execution across team and application boundaries with improved modularity, security, debugging, and fault isolation.
Nexus supports cross-team, cross-domain, cross-namespace, multi-region, and multi-cloud use cases.

<CaptionedImage
    src="/img/cloud/nexus/nexus-overview-short.png"
    title="Nexus Overview"
/>

Temporal Cloud support is built on top of the [core Nexus experience](/nexus) and adds a global Nexus Registry within an Account, enhanced security, and multi-region connectivity within and across AWS and GCP.

:::tip RELATED

- [Evaluate](/evaluate/nexus) why you should use Nexus and learn more about [Nexus use cases](/evaluate/nexus#use-cases).
- [Learn Nexus concepts](/nexus) in the Encyclopedia.

:::

## Global Nexus Registry

The Nexus Registry in Temporal Cloud is scoped to an Account.
Workers in any Namespace can host Nexus Services for others to use within an Account.

## Built-in access controls

Temporal Cloud has built-in Endpoint access controls to restrict which callers can use a Nexus Endpoint.

## Audit logging

Temporal Cloud supports audit log streaming for Nexus Registry actions to create, update, or delete Endpoints.

## Multi-region connectivity

Nexus requests in Temporal Cloud are routed across Namespaces, within and across AWS and GCP, using a global mTLS-secured Envoy mesh.
Built-in Nexus Machinery provides reliable at-least-once execution and Workflow policy can deduplicate requests for exactly-once execution, even across multi-region boundaries.

## Terraform support

The [Terraform provider for Temporal Cloud](/cloud/terraform-provider#manage-temporal-cloud-nexus-endpoints-with-terraform) supports managing Nexus Endpoints.

## Learn more

- [Evaluate](/evaluate/nexus) why you should use Nexus and watch the [Nexus keynote and demo](https://youtu.be/qqc2vsv1mrU?feature=shared&t=2082).
- [Learn key Nexus concepts](/nexus) and how Nexus works in the [Nexus deep dive talk](https://www.youtube.com/watch?v=izR9dQ_eIe4&t=934s)
- Explore [additional resources](/evaluate/nexus#learn-more) to learn more about Nexus.

---

## Latency and Availability - Temporal Nexus

:::tip SUPPORT, STABILITY, and DEPENDENCY INFO

Temporal Nexus is now [Generally Available](/evaluate/development-production-features/release-stages#general-availability).
Learn why you should use Nexus in the [evaluation guide](/evaluate/nexus).

:::

Nexus requests (commands, polling) have the same latency SLOs and error rate SLAs as other Worker requests in both the caller and handler Namespaces.

## Latency metrics

Nexus supports various [latency metrics](/nexus/metrics).

## Worker to Temporal Cloud interactions

Nexus interactions between a Worker and Temporal Cloud use the Worker's Namespace gRPC endpoint.
Nexus-related Worker interactions with Temporal Cloud have the same [latency SLOs](/cloud/service-availability#latency) and [availability SLAs](/cloud/sla) as other calls to a Namespaces's gRPC endpoint.

<CaptionedImage
    src="/img/cloud/nexus/nexus-workers-short.png"
    title="Interaction between Workers and Temporal Cloud"
/>

This applies to the following Nexus-related interactions between a Worker and Temporal Cloud:

- Caller Namespace
  - RespondWorkflowTaskCompleted \- schedule a Nexus Operation.
- Handler Namespace
  - PollNexusTaskQueue \- get a [Nexus Task](/tasks#nexus-task) to process, for example to start a Nexus Operation.
  - RespondNexusTaskCompleted \- report the Nexus Task was successful.
  - RespondNexusTaskFailed \- report the Nexus Task failed.

## Nexus connectivity across Namespaces

Nexus connectivity in Temporal Cloud is provided by a global mTLS secured Envoy mesh.
The cross-namespace latency between the caller's Nexus Machinery and the handler's Nexus Machinery varies based on the locality of the caller and handler Namespaces, which may be placed in different regions.

Communication between Namespaces in the same region will have lower latency.
Communication across different regions will have higher latency.
Consult the cross-region latency tables for your cloud provider(s) to estimate the latency for Nexus communication across Namespaces in Temporal Cloud.

---

## Limits - Temporal Nexus

:::tip SUPPORT, STABILITY, and DEPENDENCY INFO

Temporal Nexus is now [Generally Available](/evaluate/development-production-features/release-stages#general-availability).
Learn why you should use Nexus in the [evaluation guide](/evaluate/nexus).

:::

Temporal Cloud has default limits for several aspects of Nexus.
Many of these defaults are configurable, so if you need them changed please open a support ticket.

## Rate Limiting

Nexus requests (commands, polling) are counted as part of the overall Namespace RPS limit in both the caller and handler Namespaces.
Default Namespace RPS limits are set at 1600 and automatically adjust based on recent usage (over prior 7 days).

## Operational Limits

Nexus has operational limits for thing like the maximum number of Nexus Endpoints and the maximum request handler timeout.

### Max Nexus Endpoints

By default, each account is provisioned with a max of 100 Nexus Endpoints.
You can request further increases beyond the initial 100 Endpoint limit by opening a support ticket.

### Workflow Max Nexus Operations

A single Workflow Execution can have a maximum of 30 in-flight Nexus Operations.

See the Nexus Encyclopedia entry for [additional details](/workflow-execution/limits#workflow-execution-nexus-operation-limits).

### Nexus Request Handler Timeout

Nexus Operation handlers have less than 10 seconds to process a single Nexus start or cancel request.
Handlers should observe the context deadline and ensure they do not exceed it.
This includes fully processing a synchronous Nexus operation and starting an asynchronous Nexus operation, for example one that starts a Workflow.
If a handler doesn’t respond within a context deadline, a context deadline exceeded error will be tracked in the caller Workflow’s pending Nexus operations, and the Nexus Machinery will retry the Nexus request with an exponential backoff policy.

### Nexus Operation Maximum Duration

Each Nexus Operation has a maximum ScheduleToClose duration of 60 days, which is most applicable to asynchronous Nexus Operations that are completed with an asynchronous callback using a separate Nexus request from the handler back to the caller Namespace.
The 60 day maximum is a limit we will look to increase at some point in the future.
While the caller of a Nexus Operation can configure the ScheduleToClose duration to be shorter than 60 days, the maximum duration can not be extended beyond 60 days and will be capped by the server to 60 days.

---

## Obserability - Temporal Nexus

:::tip SUPPORT, STABILITY, and DEPENDENCY INFO

Temporal Nexus is now
[Generally Available](/evaluate/development-production-features/release-stages#general-availability). Learn why you
should use Nexus in the [evaluation guide](/evaluate/nexus).

:::

Nexus provides metrics and audit log streaming, in addition to integrated
[execution debugging](/nexus/execution-debugging).

## Metrics

Nexus provides the following metrics:

- [SDK metrics](/nexus/metrics#sdk-metrics) \- emitted by a Worker.
- [Cloud metrics](/nexus/metrics#cloud-metrics) \- emitted by Temporal Cloud.

## Audit Logging

The following Nexus control plane actions are sent to the [Audit Logging](/cloud/audit-logs) integrations:

- Create Nexus Endpoint: `CreateNexusEndpoint`
- Update Nexus Endpoint: `UpdateNexusEndpoint`
- Delete Nexus Endpoint: `DeleteNexusEndpoint`

---

## Pricing for Temporal Nexus

:::tip SUPPORT, STABILITY, and DEPENDENCY INFO

Temporal Nexus is now [Generally Available](/evaluate/development-production-features/release-stages#general-availability).
Learn why you should use Nexus in the [evaluation guide](/evaluate/nexus).

:::

The pricing for [Temporal Nexus](/evaluate/nexus) is:

- **One Action to start or cancel a Nexus Operation** in the caller Namespace.
  The underlying Temporal primitives such as Workflows, Activities, Signals created by a Nexus Operation handler (directly or indirectly) result in the normal Actions for those primitives.
  This includes retries for underlying Temporal primitives like Activities.
- **No Action results for handling or retrying the Nexus Operation itself**.
  However, while the retry of the Nexus Operation incurs no charge, any billable action initiated by the handler (such as an Activity) will be charged if it fails and is subsequently retried.

See [Pricing](/cloud/pricing) for additional details.

## Learn more

- [Evaluate](/evaluate/nexus) why you should use Nexus and watch the [Nexus keynote and demo](https://youtu.be/qqc2vsv1mrU?feature=shared&t=2082).
- Learn how Nexus works in the [Nexus deep dive talk](https://www.youtube.com/watch?v=izR9dQ_eIe4) and [Encyclopedia](/nexus).
- [Additional resources](/evaluate/nexus#learn-more) to learn more about Nexus.

---

## Notifications

## Get notified about Temporal Cloud status {#cloud-status}

In the event of an incident, Temporal updates the [Temporal Cloud status page](https://status.temporal.io/) with important updates.
Users can subscribe to updates in their preferred mode (e.g. email, Slack, SMS, etc.) by visiting this page.

## Get notified about administrative events {#admin-notifications}

Temporal Cloud sends emails to notify users of important administrative events.

| Reason for email | Who receives email |
|------------------ | -------------------|
| Certificate Expiring in 15 days | Global Administrator, Namespace Administrator, Account Owner |
| Certificate Expiring in 10 days | Global Administrator, Namespace Administrator, Account Owner |
| Certificate Expiring in 5 days  | Global Administrator, Namespace Administrator, Account Owner |
| API Key Expiring in 30 days     | Global Administrator, Account Owner, individual user (if API Key has an owner) |
| API Key Expiring in 20 days     | Global Administrator, Account Owner, individual user (if API Key has an owner) |
| API Key Expiring in 10 days     | Global Administrator, Account Owner, individual user (if API Key has an owner) |
| Sign up credit expiring in 30 days | Account Owner, Finance Administrator |
| Sign up credit expiring in 14 days | Account Owner, Finance Administrator |
| Sign up credit expiring in  7 days | Account Owner, Finance Administrator |
| Sign up credit expiring in  1 days | Account Owner, Finance Administrator |
| Sign up credit is 50% consumed     | Account Owner, Finance Administrator |
| Sign up credit is 90% consumed     | Account Owner, Finance Administrator |
| Account plan type changed          | Global Administrator, Account Owner, Finance Administrator |
| Namespace Failover Completed/Failed | Global Administrator, Namespace Administrator, Account Owner |

To ensure that you receive email notifications, configure your junk-email filters to permit email from
`noreply@temporal.io`.

To provide feedback on notifications or request changes, [create a support ticket](/cloud/support#support-ticket).

---

## Cloud Ops API

:::tip Support, stability, and dependency info

The Temporal Cloud Operations API is in [Public Preview](/evaluate/development-production-features/release-stages#public-preview).

:::

The Temporal Cloud Operations API, or the Cloud Ops API, is an open source, public [HTTP API](https://saas-api.tmprl.cloud/docs/httpapi.html#description/introduction) and [gRPC API](https://github.com/temporalio/cloud-api/tree/main) for programmatically managing Temporal Cloud control plane resources, including [Namespaces](/cloud/namespaces), [Users](/cloud/users), [Service Accounts](/cloud/service-accounts), [API keys](/cloud/api-keys), and others. The Temporal Cloud [Terraform Provider](/cloud/terraform-provider), [tcld CLI](/cloud/tcld), and Web UI all use the Cloud Ops API.

## Develop applications with the Cloud Ops API

You can use the HTTP API or the gRPC API depending on how you need to integrate with your platform. The URL to access both the HTTP and gRPC Cloud Ops API is `saas-api.tmprl.cloud`.

### Prerequisites

These prerequisites are required for using either HTTP or gRPC.

- [Temporal Cloud user account](/cloud/get-started)
- [API Key](/cloud/tcld/apikey#create) for authentication

### Use cases

Some common reasons you might use the API are to:

- Provision Namespaces per environment or tenant via pipelines.
- Bootstrap new projects by creating users, assigning roles, and creating Namespaces via custom scripts.
- Rotate service account keys on a schedule with a job.
- Audit and report access across orgs with scheduled HTTP requests.

### Using HTTP

[The HTTP API](https://saas-api.tmprl.cloud/docs/httpapi.html#description/introduction) supports the same operations as the [gRPC API](#using-grpc), but it's usable via standard HTTP methods and authentication. This may be a more convenient option if you are writing automation scripts for CI/CD or you can't use gRPC due to network policies, proxies, tooling gaps, or language/runtime constraints. Since it's standard HTTP, it's language agnostic giving you the ability to run cloud operations consistently.

:::note
This *does not* allow interaction with individual Workflows or Activities via HTTP.
:::

### Using gRPC

*For Go developers:*
- Use the [Go SDK](https://github.com/temporalio/cloud-sdk-go) for the simplest setup experience

*For other programming languages:*
- Basic familiarity with gRPC and Protocol Buffers (protobuf)
- [Protocol Buffers](https://github.com/protocolbuffers/protobuf/releases)
- [gRPC](https://grpc.io/docs/languages/) in your preferred programming language

You can use the provided proto files to generate client libraries in your desired programming language, and then use that client to access the gRPC API. You can also find the [full gRPC docs on Buf](https://buf.build/temporalio/cloud-api/docs/main:temporal.api.cloud.cloudservice.v1#temporal.api.cloud.cloudservice.v1.CloudService).

#### Using the Go SDK

If you're developing in Go, we recommend using the [Go SDK](https://github.com/temporalio/cloud-sdk-go) which provides pre-compiled Go bindings and a more idiomatic interface. The Go SDK handles all the protobuf compilation and provides ready-to-use Go types and client interfaces. You can also use the [Go samples](https://github.com/temporalio/cloud-samples-go) to help you get started with the Cloud Ops API using the Go SDK.

To start using the Go SDK with the Cloud Ops API, follow these steps:

1. Install the Go SDK:
   ```go
   go get github.com/temporalio/cloud-sdk-go
   ```

2. Import and use the SDK:
   ```go

       "github.com/temporalio/cloud-sdk-go/client"
   )
   ```

3. The Go SDK provides pre-built client interfaces that handle authentication and connection setup. Refer to the [Go samples](https://github.com/temporalio/cloud-samples-go) for detailed usage examples.

The Go SDK eliminates the need to work directly with generated protobuf files and provides a more idiomatic Go experience.

#### Compile the API and use the generated code (For other languages)

For programming languages other than Go, download the gRPC protobufs from the [Cloud Ops API repository](https://github.com/temporalio/cloud-api/tree/main/temporal/api/cloud) and compile them manually.

Use [gRPC](https://grpc.io/docs/) to compile and generate code in your preferred [programming language](https://grpc.io/docs/#official-support). The steps below use Python as an example and require [Python's gRPC tools](https://grpc.io/docs/languages/python/quickstart/#grpc-tools) to be installed, but the approach can be adapted for other supported programming languages.

1. Clone the Temporal Cloud API repository:

   ```command
   git clone https://github.com/temporalio/cloud-api.git
   cd cloud-api
   ```

2. Copy Protobuf files:

   - Navigate to the `temporal` directory.
   - Copy the protobuf files to your project directory.

3. Compile the Protobuf files:

   ```python
   python -m grpc_tools.protoc -I./ --python_out=./ --grpc_python_out=./ *.proto
   ```
   - `-I` specifies the directory of the `.proto` files.
   - `--python_out=` sets the output directory for generated Python classes.
   - `--grpc_python_out=` sets the output directory for generated gRPC service classes.
   - `*.proto` processes all `.proto` files.

   After compiling the Protobuf files, you will have generated code files in your project directory.
   These files enable interaction with the Temporal Cloud API in your chosen programming language.

4. Import the Generated Files:

   - Locate the Python files (.py) generated in your project directory.
   - Import these files into your Python application where you intend to interact with the Temporal Cloud API.

2. Use the API:
   - Use the classes and methods defined in the imported files to communicate with the Temporal Cloud services.
   - Ensure to handle any required authentication or configuration as needed for Temporal Cloud.

This approach can be adapted for other programming languages by following their respective import and usage conventions for the generated code files.

## Usage guidelines

When interacting with the Temporal Cloud Ops API, follow these guidelines:

- API version header:
   - Always include the `temporal-cloud-api-version` header in your requests, specifying the API version identifier.
   - The current API version can be found [here](https://github.com/temporalio/cloud-api/blob/main/VERSION#L1C1-L1C14).
- Connection URL:
   - Connect to the Temporal Cloud using the gRPC URL: `saas-api.tmprl.cloud:443`.
- Engagement steps:
   - Generate API key:
     - Obtain an [API Key for authentication](/cloud/api-keys#manage-api-keys). Note that many operations may require Admin privileges.
   - Set up client:
     - Establish a secure connection to the Temporal Cloud. Refer to the example [Client setup in Go](https://github.com/temporalio/cloud-samples-go/blob/main/client/temporal/client.go) for guidance.
   - Execute operations:
     - For operation specifics, refer to the `cloudservice/v1/request_response.proto` for gRPC messages and `cloudservice/v1/service.proto` for gRPC services.

These steps provide a structured approach to using the Temporal Cloud Ops API effectively, ensuring proper authentication and connection setup.

## Rate limits

The Temporal Cloud Operations API implements rate limiting to ensure system stability and fair usage across all users. Rate limits are applied based on identity type, with different limits for users and service accounts.

### Account-level rate limit

**Total rate limit: 160 requests per second (RPS)**

This limit applies to all requests made to the Temporal Cloud control plane by any client (tcld, UI, Cloud Ops API) or identity type (user, service account) within your account. The total account throughput cannot exceed the limit regardless of the number of users or service accounts making requests.

### Per-identity rate limits

**User rate limit: 40 RPS per user**

This limit applies to all requests made by each user through any client (tcld, UI, Cloud Ops API), regardless of the authentication method used (SSO or API keys).

**Service account rate limit: 80 RPS per service account**

This limit applies to all requests made by each service account through any client (tcld, Cloud Ops API).

### Important considerations

- Rate limits are enforced across all Temporal Cloud control plane operations
- Multiple clients used by the same identity (user or service account) share the same rate limit
- Authentication method (SSO, API keys) does not affect rate limiting
- These limits help ensure system stability and prevent any single account or identity from overwhelming the service

### Request limit increases

If your use case requires higher rate limits, you can request an increase by [submitting a support ticket](/cloud/support#support-ticket). When requesting a limit increase, please provide:

- Your current usage patterns and requirements
- The specific limits you need increased
- A description of your use case and why higher limits are necessary

### Provide feedback

Your input is valuable!

You can provide feedback through the following channels:

- Submit request or feedback through a [support ticket](/cloud/support#support-ticket)
- Open an issue in the [GitHub Repo](https://github.com/temporalio/cloud-api)

---

## Awsregions

### Asia Pacific - Tokyo (`ap-northeast-1`)

- **Cloud API Code**: `aws-ap-northeast-1`
- **Regional Endpoint**: `aws-ap-northeast-1.region.tmprl.cloud`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.ap-northeast-1.vpce-svc-08f34c33f9fb8a48a`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `aws-ap-northeast-2`
  - `aws-ap-south-1`
  - `aws-ap-south-2`
  - `aws-ap-southeast-1`
  - `aws-ap-southeast-2`
- **Multi-Cloud Replication**:
  - `gcp-asia-south1`

### Asia Pacific - Seoul (`ap-northeast-2`)

- **Cloud API Code**: `aws-ap-northeast-2`
- **Regional Endpoint**: `aws-ap-northeast-2.region.tmprl.cloud`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.ap-northeast-2.vpce-svc-08c4d5445a5aad308`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `aws-ap-northeast-1`
  - `aws-ap-south-1`
  - `aws-ap-south-2`
  - `aws-ap-southeast-1`
  - `aws-ap-southeast-2`
- **Multi-Cloud Replication**:
  - `gcp-asia-south1`

### Asia Pacific - Mumbai (`ap-south-1`)

- **Cloud API Code**: `aws-ap-south-1`
- **Regional Endpoint**: `aws-ap-south-1.region.tmprl.cloud`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.ap-south-1.vpce-svc-0ad4f8ed56db15662`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `aws-ap-northeast-1`
  - `aws-ap-northeast-2`
  - `aws-ap-south-2`
  - `aws-ap-southeast-1`
  - `aws-ap-southeast-2`
- **Multi-Cloud Replication**:
  - `gcp-asia-south1`

### Asia Pacific - Hyderabad (`ap-south-2`)

- **Cloud API Code**: `aws-ap-south-2`
- **Regional Endpoint**: `aws-ap-south-2.region.tmprl.cloud`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.ap-south-2.vpce-svc-08bcf602b646c69c1`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `aws-ap-northeast-1`
  - `aws-ap-northeast-2`
  - `aws-ap-south-1`
  - `aws-ap-southeast-1`
  - `aws-ap-southeast-2`
- **Multi-Cloud Replication**:
  - `gcp-asia-south1`

### Asia Pacific - Singapore (`ap-southeast-1`)

- **Cloud API Code**: `aws-ap-southeast-1`
- **Regional Endpoint**: `aws-ap-southeast-1.region.tmprl.cloud`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.ap-southeast-1.vpce-svc-05c24096fa89b0ccd`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `aws-ap-northeast-1`
  - `aws-ap-northeast-2`
  - `aws-ap-south-1`
  - `aws-ap-south-2`
  - `aws-ap-southeast-2`
- **Multi-Cloud Replication**:
  - `gcp-asia-south1`

### Asia Pacific - Sydney (`ap-southeast-2`)

- **Cloud API Code**: `aws-ap-southeast-2`
- **Regional Endpoint**: `aws-ap-southeast-2.region.tmprl.cloud`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.ap-southeast-2.vpce-svc-0634f9628e3c15b08`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `aws-ap-northeast-1`
  - `aws-ap-northeast-2`
  - `aws-ap-south-1`
  - `aws-ap-south-2`
  - `aws-ap-southeast-1`
- **Multi-Cloud Replication**:
  - `gcp-asia-south1`

### Europe - Frankfurt (`eu-central-1`)

- **Cloud API Code**: `aws-eu-central-1`
- **Regional Endpoint**: `aws-eu-central-1.region.tmprl.cloud`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.eu-central-1.vpce-svc-073a419b36663a0f3`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `aws-eu-west-1`
  - `aws-eu-west-2`
- **Multi-Cloud Replication**:
  - `gcp-europe-west3`

### Europe - Ireland (`eu-west-1`)

- **Cloud API Code**: `aws-eu-west-1`
- **Regional Endpoint**: `aws-eu-west-1.region.tmprl.cloud`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.eu-west-1.vpce-svc-04388e89f3479b739`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `aws-eu-central-1`
  - `aws-eu-west-2`
- **Multi-Cloud Replication**:
  - `gcp-europe-west3`

### Europe - London (`eu-west-2`)

- **Cloud API Code**: `aws-eu-west-2`
- **Regional Endpoint**: `aws-eu-west-2.region.tmprl.cloud`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.eu-west-2.vpce-svc-0ac7f9f07e7fb5695`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `aws-eu-central-1`
  - `aws-eu-west-1`
- **Multi-Cloud Replication**:
  - `gcp-europe-west3`

### North America - Central Canada (`ca-central-1`)

- **Cloud API Code**: `aws-ca-central-1`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.ca-central-1.vpce-svc-080a781925d0b1d9d`
- **Regional Endpoint**: `aws-ca-central-1.region.tmprl.cloud`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `aws-us-east-1`
  - `aws-us-east-2`
  - `aws-us-west-2`
- **Multi-Cloud Replication**:
  - `gcp-us-central1`
  - `gcp-us-west1`
  - `gcp-us-east4`

### North America - Northern Virginia (`us-east-1`)

- **Cloud API Code**: `aws-us-east-1`
- **Regional Endpoint**: `aws-us-east-1.region.tmprl.cloud`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.us-east-1.vpce-svc-0822256b6575ea37f`
- **Same Region Replication**:  Available
- **Multi-Region Replication**:
  - `aws-ca-central-1`
  - `aws-us-east-2`
  - `aws-us-west-2`
- **Multi-Cloud Replication**:
  - `gcp-us-central1`
  - `gcp-us-west1`
  - `gcp-us-east4`

### North America - Ohio (`us-east-2`)

- **Cloud API Code**: `aws-us-east-2`
- **Regional Endpoint**: `aws-us-east-2.region.tmprl.cloud`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.us-east-2.vpce-svc-01b8dccfc6660d9d4`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `aws-ca-central-1`
  - `aws-us-east-1`
  - `aws-us-west-2`
- **Multi-Cloud Replication**:
  - `gcp-us-central1`
  - `gcp-us-west1`
  - `gcp-us-east4`

### North America - Oregon (`us-west-2`)

- **Cloud API Code**: `aws-us-west-2`
- **Regional Endpoint**: `aws-us-west-2.region.tmprl.cloud`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.us-west-2.vpce-svc-0f44b3d7302816b94`
- **Same Region Replication**:  Available
- **Multi-Region Replication**:
  - `aws-ca-central-1`
  - `aws-us-east-1`
  - `aws-us-east-2`
- **Multi-Cloud Replication**:
  - `gcp-us-central1`
  - `gcp-us-west1`
  - `gcp-us-east4`

### South America - São Paulo (`sa-east-1`)

- **Cloud API Code**: `aws-sa-east-1`
- **Regional Endpoint**: `aws-sa-east-1.region.tmprl.cloud`
- **PrivateLink Endpoint Service**: `com.amazonaws.vpce.sa-east-1.vpce-svc-0ca67a102f3ce525a`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - None
- **Multi-Cloud Replication**:
  - None

---

## Gcpregions

### North America - Iowa (`us-central1`)

- **Cloud API Code**: `gcp-us-central1`
- **Regional Endpoint**: `gcp-us-central1.region.tmprl.cloud`
- **Private Service Connect Service Attachment URI**: `projects/prod-d9ch6v2ybver8d2a8fyf7qru9/regions/us-central1/serviceAttachments/pl-5xzng`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `gcp-us-west1`
  - `gcp-us-east4`
- **Multi-Cloud Replication**:
  - `aws-ca-central-1`
  - `aws-us-east-1`
  - `aws-us-east-2`
  - `aws-us-west-2`

### North America - Oregon (`us-west1`)

- **Cloud API Code**: `gcp-us-west1`
- **Regional Endpoint**: `gcp-us-west1.region.tmprl.cloud`
- **Private Service Connect Service Attachment URI**: `projects/prod-rbe76zxxzydz4cbdz2xt5b59q/regions/us-west1/serviceAttachments/pl-94w0x`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `gcp-us-central1`
  - `gcp-us-east4`
- **Multi-Cloud Replication**:
  - `aws-ca-central-1`
  - `aws-us-east-1`
  - `aws-us-east-2`
  - `aws-us-west-2`

### North America - Northern Virginia (`us-east4`)

- **Cloud API Code**: `gcp-us-east4`
- **Regional Endpoint**: `gcp-us-east4.region.tmprl.cloud` 
- **Private Service Connect Service Attachment URI**: `projects/prod-y399cvr9c2b43es2w3q3e4gvw/regions/us-east4/serviceAttachments/pl-8awsy`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - `gcp-us-central1`
  - `gcp-us-west1`
- **Multi-Cloud Replication**:
  - `aws-ca-central-1`
  - `aws-us-east-1`
  - `aws-us-east-2`
  - `aws-us-west-2`

### Europe - Frankfurt (`europe-west3`)

- **Cloud API Code**: `gcp-europe-west3`
- **Regional Endpoint**: `gcp-europe-west3.region.tmprl.cloud`
- **Private Service Connect Service Attachment URI**: `projects/prod-kwy7d4faxp6qgrgd9x94du36g/regions/europe-west3/serviceAttachments/pl-acgsh`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - None
- **Multi-Cloud Replication**:
  - `aws-eu-central-1`
  - `aws-eu-west-1`
  - `aws-eu-west-2`

### Asia Pacific - Mumbai (`asia-south1`)

- **Cloud API Code**: `gcp-asia-south1`
- **Regional Endpoint**: `gcp-asia-south1.region.tmprl.cloud`
- **Private Service Connect Service Attachment URI**: `projects/prod-d5spc2sfeshws33bg33vwdef7/regions/asia-south1/serviceAttachments/pl-7w7tw`
- **Same Region Replication**:  Not Available
- **Multi-Region Replication**:
  - None
- **Multi-Cloud Replication**:
  - `aws-ap-northeast-1`
  - `aws-ap-northeast-2`
  - `aws-ap-south-1`
  - `aws-ap-south-2`
  - `aws-ap-southeast-1`
  - `aws-ap-southeast-2`

---

## Private Service

| Region                 | Private Service Connect Service Name                                                      |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| `asia-south1`          | `projects/prod-d5spc2sfeshws33bg33vwdef7/regions/asia-south1/serviceAttachments/pl-7w7tw` |
| `us-central1`          | `projects/prod-d9ch6v2ybver8d2a8fyf7qru9/regions/us-central1/serviceAttachments/pl-5xzn`   |
| `us-west1   `          | `projects/prod-rbe76zxxzydz4cbdz2xt5b59q/regions/us-west1/serviceAttachments/pl-94w0x`    |

---

## RPO and RTO

When a cloud outage disrupts a Namespace, Temporal Cloud takes measures to maintain the Namespace's availability and data durability. The time it takes to recover from the outage is called the "recovery time." The amount of data (event histories) lost is called the "recovery point." A durable system should have a low recovery time and recovery point.

To help users plan for keeping critical Workflows available during a cloud outage, Temporal Cloud publishes goals for the recovery time and recovery point for each kind of outage. These goals are called the Recovery Time Objective (RTO) and Recovery Point Objective (RPO). These objectives are complementary to Temporal Cloud's [Service Level Agreement (SLA)](/cloud/sla).

To achieve the lowest RPO and RTO, Temporal Cloud offers [High Availability](/cloud/high-availability) features that keep Workflows operational with minimal downtime. When High Availability is enabled on a Namespace, the user chooses a region to place a "replica" that will take over in the event of a failure. The location of the replica determines the type of replication used and the type of outages that can be handled. Multi-region Replication is when the active and replica are in different regions on the same cloud (e.g., AWS us-east-1 and AWS us-west-2). Multi-cloud Replication is when the active and replica are in different clouds (e.g., AWS and GCP). Same-region Replication is when the active and replica are in the same region. Temporal always places the active and replica in different [cells](/cloud/overview#cell-based-infrastructure).

As Workflows progress in the active region, history events are asynchronously replicated to the replica.
Because replication is asynchronous, High Availability does not impact the latency or throughput of Workflow Executions in the active region.
If an outage hits the active region or cell, Temporal Cloud will fail over to the replica so that existing Workflow Executions will continue to run and new Workflow Executions can be started.

The Recovery Point Objective and Recovery Time Objective for Temporal Cloud depend on the type of outage and which [High Availability](/cloud/high-availability) feature your Namespace has enabled. Temporal Cloud can only set an RPO and RTO for cases where it has the ability to mitigate the outage. Therefore, the below RPOs and RTOs apply to Namespaces that have the corresponding type of replication and have enabled Temporal-initiated failovers, which comes enabled by default.

1. **Availability zone outage**:
    1. _Applicable Namespaces:_ All Namespaces
    2. _Goals:_ Zero RPO and near-zero RTO
    3. _More details:_ Historically, these have been the most common type of outage in the cloud. Temporal Cloud replicates every Namespace across three availability zones. The failure of a single availability zone is handled automatically by Temporal Cloud behind the scenes, with no potential for data loss, and little-to-no observable downtime to the end user.
2. **Cell outage**: 
    1. _Applicable Namespaces:_ Namespaces with Same-region Replication, Multi-region Replication, or Multi-cloud Replication
    2. _Goals:_ 1-minute RPO and 20-minute RTO
    3. _More details:_ Temporal Cloud runs on a [cell architecture](/cloud/sla). Each cell contains the software and services necessary to host a Namespace. While unlikely, it's possible for a cell to experience a disruption due to uncaught software bugs or sub-component failures (e.g., an outage in the underlying database).
3. **Regional outage**: 
    1. _Applicable Namespaces:_ Namespaces with Multi-region Replication or Multi-cloud Replication
    2. _Goals:_ 1-minute RPO and 20-minute RTO
    3. _More details:_ On [rare occasions](https://temporal.io/blog/how-devs-kept-running-during-the-aws-us-east-1-oct-20-2025), an entire region within a cloud provider will be degraded. Since Namespaces depend on the cloud provider's infrastructure, Temporal Cloud is not immune to these outages.
4. **Cloud-wide outage**: 
    1. _Applicable Namespaces:_ Namespaces with Multi-cloud Replication
    2. _Goals:_ 1-minute RPO and 20-minute RTO
    3. _More details:_ An entire cloud provider has an outage across most or all regions. Since cloud providers strive to keep cloud regions de-coupled, these are the rarest outages of all. Still, they [have happened](https://status.cloud.google.com/incidents/ow5i3PPK96RduMcb1SsW) in the past.

Notes:

- The above goals are only applicable to Namespaces that have enabled Temporal-initiated failovers, which comes enabled by default. Temporal-initiated failovers are initiated by Temporal's tooling and/or on-call engineers without user action. Users can always initiate a failover on their Namespace, even when Temporal-initiated failovers are enabled. In an outage, a user-initiated failover will not cancel out or accidentally reverse a Temporal-initiated failover.

:::note

Temporal highly recommends keeping Temporal-initiated failovers enabled. When Temporal-initiated failovers are _disabled,_ Temporal Cloud cannot set an RPO and RTO for that Namespace, because it cannot control when or if the user will trigger a failover.

:::

- The above goals are for unplanned cloud outages. They do not apply to user-initiated failovers during healthy periods (e.g., for DR drills). Read about [triggering a failover](/cloud/high-availability/failovers) to see how a Namespace failover should perform during healthy periods.

- As soon as a cloud outage resolves, Temporal's on-call engineers will work to restore service to Namespaces that were not protected by High Availability. A cloud outage can leave lingering effects in Temporal's systems and applications, even after the cloud provider restores the underlying service. Because of this, affected Namespaces may not be immediately available when the underlying service is restored. An affected Namespace's outage may last longer than the cloud provider's outage.

- All Namespaces are backed up every 4 hours. If an outage causes data loss on a Namespace that was not protected by High Availability, then Temporal will use the backup to restore as much data as feasible.

## Minimizing the Recovery Point

Temporal has put extensive work into tools and processes that minimize the recovery point and achieve its RPO for Temporal-initiated failovers, including:

- Best-in-class [data replication technology](https://youtu.be/mULBvv83dYM?si=RDeWb3gVsEtgGM4z&t=334) that keeps the replica up to date with the active.

- Monitoring, alerting, and internal SLOs on the replication lag for every Temporal Cloud Namespace.

However, user actions on a Namespace can affect the recovery point. For example, suddenly spiking into much higher throughput than a Namespace has seen before could create a period of replication lag where the replica falls behind the active. 

Temporal provides a [replication lag](/cloud/high-availability/monitoring#replication-lag-metric) metric for each Namespace. This metric approximates the recovery point the Namespace would achieve in a worst case failure at that given moment.

:::note

Temporal recommends monitoring the replication lag and alerting should it rise too high, e.g., above 1 minute.

:::

## Minimizing the Recovery Time

Temporal has put extensive work into tools and processes that minimize the recovery time and achieve its RTO for Temporal-initiated failovers, including:

- History events are replicated _asynchronously_. This ensures that the Namespace can still run workflows in the active region even if there are networking blips or outages with the replica region.

- Outages are detected automatically. We have extensive internal alerting to detect disruptions to Namespaces, and are ever improving this system.

- Battle-tested Temporal Workflows that execute failovers of all Temporal Cloud Namespaces in a given region quickly.

- Regular drills where we fail over our internal Namespaces to test our tooling.

- Expert engineers on-call 24/7 monitoring Temporal Cloud Namespaces and ready to assist should an outage occur.

To achieve the lowest possible recovery times, Temporal recommends that you:

- Keep Temporal-initiated failovers enabled on your Namespace (the default)
- Invest in a process to detect outages and trigger a manual failover.

Users can trigger manual failovers on their Namespaces even if Temporal-initiated failovers are enabled. There are several benefits to combining a manual failover process with Temporal-initiated failovers:

- You can detect outages that Temporal doesn't. In the cloud, regional outages don't affect all services equally. It's possible that Temporal--and the services it depends on--are unaffected by the outage, even while your Workers or other cloud infrastructure are disrupted. If you [monitor services in your critical path](https://sre.google/sre-book/monitoring-distributed-systems/) and alert on unusual error rates, you may catch outages before Temporal Cloud does.

- You can sequence your failovers in a particular order. Your cloud infrastructure probably contains more pieces than just your Temporal Namespace: Temporal Workers, compute pools, data stores, and other cloud services. If you manually fail over, you can choose the order in which these pieces switch to the replica region. You can then test that ordering with failover drills and ensure it executes smoothly without data consistency issues or bottlenecks.

- You can proactively fail over more aggressively than Temporal. While the 20-minute RTO should be sufficient for most use cases, some may strive to hit an even lower RTO. For workloads like high frequency trading, auctions, or popular sporting events, an outage at the wrong time could cause tremendous lost revenue per minute. You can adopt a posture that fails over more eagerly than Temporal does. For example, you could trigger a manual failover at the first sign of a possible disruption, before knowing whether there's a true regional outage. 

- Even if you have robust tooling to detect an outage and trigger a failover, leaving Temporal-initiated failovers enabled provides a "safety net" in case your automation misses an outage. It also gives Temporal leeway to preemptively fail over your Namespace if we detect that it may be disrupted soon, e.g., by a rolling failure that has impacted other Namespaces but not yours, yet.

## Understanding Temporal's RTO vs. SLA

Temporal has both a Recovery Time Objective (RTO) and a Service Level Agreement (SLA). They serve complementary purposes and apply in different situations.

| Aspect                            | RTO                                                                                                                                                                                                                                                                     | SLA                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| What is it?                       | An objective, or high-priority goal, for the total time that an outage disrupts a Namespace.                                                                                                                                                                            | A contractual agreement that sets an upper bound on the service error rate, with financial repercussions.                                                                                                                                                                                                                                                                                                                                                                      |
| How is it measured?               | The achieved recovery time is measured in terms of minutes per outage.                                                                                                                                                                                              | The achieved service error rate is measured in terms of error rate per month.                                                                                                                                                                                                                                                                                                                                                                                              |
| How is the calculation performed? | The achieved recovery time in a given outage is the total time between when a disruption to a Namespace began and when the Namespace was restored to full functionality, either after a failover to a healthy region or after the outage has been mitigated. | Temporal measures the percentage of requests to Temporal Cloud that fail, and applies a [formula](/cloud/sla) to get the final percentage for the month.                                                                                                                                                                                                                                                                                                                       |
| Do partial degradations count?    | Most outages contain periods of __partial degradation__ where some percentage of Namespace operations fail while the rest complete as normal. When they disrupt a Namespace, periods of partial degradation count in the calculation of the recovery time.                       | Partial degradations only partially count for the service error rate calculation. A 5-minute window with a 10% error rate would count less than a 5-minute window with a 100% error rate.                                                                                                                                                                                                                                                                                      |
| What is excluded?                 | For partial degradations, what counts as a disruption to a Namespace is subject to Temporal's expert judgment, but a good rule of thumb is a service error rate >=10%.                                                                                                | We exclude outages that are out of Temporal's control to mitigate, e.g., a failure of the underlying cloud provider infrastructure that affects a Namespace without High Availability and Temporal-initiated failovers enabled. If a Namespace has the relevant High Availability feature and has Temporal-initiated failovers enabled, then Temporal can act to mitigate the outage and it does usually count against the SLA. Full exclusions on the [SLA page](/cloud/sla). |

The following examples illustrate the RTO and SLA calculations for different types of in a regional outage. These hypothetical Namespaces are based on actual Temporal Cloud performance in a [real-world outage](https://temporal.io/blog/how-devs-kept-running-during-the-aws-us-east-1-oct-20-2025).

Suppose that region `middle-earth-1` experienced a cascading failure starting at 10:00:00 UTC, causing various instances and machines to fail over time. Temporal's automatic failover triggered for all Namespaces and completed at 10:15:00 UTC. 

- Namespace 0 was in the region but its cell was not affected by the outage. The only downtime it had was for a few seconds during the failover operation. It experienced a near-zero Recovery Time, and its service error rate was neglible.  Graceful failover was successful, and this Namespace achieved a recovery point of 0.

- Namespace 1_A was in the region and its cell experienced a partial degradation that caused 10% of requests to fail in the first 5 minutes, 25% in the second five minutes, and 50% in the third five minutes. Since it was significantly impacted from 10:00:00 to 10:15:00, its Recovery Time was 15 minutes. If it had no other service errors that month, then its service error rate for the month would be: ( (1 - 10%) + (1 - 25%) + (1 - 50%) + 8925 * 100% ) / 8928  = 99.990%. (Note: there are 8928 5-minute periods in a 31-day month.)  Graceful failover was successful, and this Namespace achieved a recovery point of 0.

- Namespace 1_B was in the same cell as Namespace 2_A, so it also experienced a partial degradation that caused 10% of requests to fail. However, its owner detected the outage via their own tooling and decided to manually fail over at 10:05:00. This Namespace achieved a recovery time of 5 minutes and a service error rate of ( 1 * (1 - 10%) + 8927 * 100% ) / 8928 = 99.998%. Graceful failover was successful, and this Namespace achieved a recovery point of 0.

- Namespace 2_A was in the region and its cell was fully network partitioned at the start of the outage, causing 100% of requests to fail. Since it was significantly impacted from 10:00:00 to 10:15:00, its Recovery Time was 15 minutes. If it had no other service errors that month, then its service error rate for the month would be: ( 3 * (1 - 100%) + 8928 * 100% ) / 8640 5-minute periods per month = 99.97%. Because the Namespace was network partitioned, graceful failover did not succeed, and forced failover was used. The recovery point achieved was equal to the replication lag at the time of the network partition, which was a few seconds.

- Namespace 2_B was in the region and was fully network partitioned, causing 100% of requests to fail. However, its owner detected the outage via their own tooling and decided to manually fail over at 10:05:00. This Namespace achieved a recovery time of 5 minutes and a service error rate of ( 1 5-minute periods * (1 - 100%) + 8639 5-minute periods * 100% ) / 8640 5-minute periods per month = 99.99%. Because the Namespace was network partitioned, graceful failover did not succeed, and forced failover was used. The recovery point achieved was equal to the replication lag at the time of the network partition, which was a few seconds.

All of the above Namespaces were in the affected region and beat the 1-minute RPO. But they achieved varying recovery times and service error rates. 

- Notice how Namespace 1_A and Namespace 2_A were both automatically failed over with **the same recovery time but different service error rates**. Notice how Namespace 2_B and Namespace 1_A happen to have the **same service error rate but different recovery times**. This illustrates how RTO and SLA can differ, even in the same outage. Both are valuable tools for Temporal Cloud users to measure the availability of their Namespaces.

- Notice how the Namespaces that were manually failed over (Namespace 1_B and Namespace 2_B) achieved lower recovery times than the Namespaces that were automatically failed over (Namespace 1_A and Namespace 2_A). This illustrates how **proactive, aggressive manual failover can achieve a better recovery time than automatic failover**.

---

## SAML authentication

To authenticate the users of your Temporal Cloud account, you can connect an identity provider (IdP) to your account by
using Security Assertion Markup Language (SAML) 2.0.

:::info

SAML is a paid feature. See the [pricing page](/cloud/pricing) for details.

:::

## Integrate SAML with your Temporal Cloud account

1. Locate your [Temporal Cloud Account Id](/cloud/namespaces#temporal-cloud-account-id). Your Account Id can be viewed
   and copied from the Temporal Cloud user profile dropdown menu in the top right corner. Alternatively, find your
   [Namespace Id](/cloud/namespaces#temporal-cloud-namespace-id). The Account Id is the five or six characters following
   the period (.), such as `f45a2`. You will need the Account Id to construct your callback URL and your entity
   identifier.
1. Configure SAML with your IdP by following one of these sets of instructions:
   - [Microsoft Entra ID](#configure-saml-with-azure-ad)
   - [Okta](#configure-saml-with-okta)
1. [Share your connection information with us and test your connection.](#finish-saml-configuration)

## How to configure SAML with Microsoft Entra ID {#configure-saml-with-azure-ad}

If you want to use the general Microsoft login mechanism, you don't need to set up SAML with Entra ID. Just select
**Continue with Microsoft** on the Temporal Cloud sign-in page.

To use Entra ID as your SAML IdP, create a Microsoft Entra ID Enterprise application.

1. Sign in to the [Microsoft Entra ID](https://portal.azure.com/).
1. On the home page, under **Manage Microsoft Entra ID**, select **View**.
1. On the **Overview** page near the top, select **Add > Enterprise application**.
1. On the **Browse Microsoft Entra ID Gallery** page near the top, select **Create your own application**.
1. In the **Create your own application** pane, provide a name for your application (such as `temporal-cloud`) and
   select **Integrate any other application you don't find in the gallery**.
1. Select **Save**.
1. In the **Getting Started** section, select **2. Set up single sign on**.
1. On the **Single sign-on** page, select **SAML**.
1. In the **Basic SAML Configuration** section of the **SAML-based Sign-on** page, select **Edit**.
1. In **Identifier (Entity ID)**, enter the following entity identifier, including your Account Id where indicated:

   ```bash
   urn:auth0:prod-tmprl:ACCOUNT_ID-saml
   ```

   A correctly formed entity identifier looks like this:

   ```bash
   urn:auth0:prod-tmprl:f45a2-saml
   ```

1. In **Reply URL (Assertion Consumer Service URL)**, enter the following callback URL, including your Account Id where
   indicated:

   ```bash
   https://login.tmprl.cloud/login/callback?connection=ACCOUNT_ID-saml
   ```

   A correctly formed callback URL looks like this:

   ```bash
   https://login.tmprl.cloud/login/callback?connection=f45a2-saml
   ```

1. In **Sign on URL**, enter the following login url, including your Account Id where indicated:

   ```bash
   https://cloud.temporal.io/login/saml?connection=ACCOUNT_ID-saml
   ```

   A correctly formed login URL looks like this:

   ```bash
   https://cloud.temporal.io/login/saml?connection=f45a2-saml
   ```

1. You can leave the other fields blank. Near the top of the pane, select **Save**.
1. In the **Attributes & Claims** section, select **Edit**. Configure the following settings. Under **Required claim**:

   - Set **Unique User Identifier (NameID)** to `user.userprincipalname`
   - Set the **NameID format** to `emailAddress`

   These are the default settings for Microsoft Entra ID. Then under **Additional claims**, ensure **Email** and
   **Name** are present.

1. Collect information that you need to send to us:
   - In the **SAML Certificates** section of the **SAML-based Sign-on** page, select the download link for **Certificate
     (Base64)**.
   - In the **Set up _APPLICATION_NAME_** section of the **SAML-based Sign-on** page, copy the value of **Login URL**.

To finish setting up Microsoft Entra ID as your SAML IdP, see [Finish SAML configuration](#finish-saml-configuration).

## How to configure SAML with Okta {#configure-saml-with-okta}

To use Okta as your SAML IdP, configure a new Okta application integration.

1. Sign in to the [Okta Admin Console](https://www.okta.com/login/).
1. In the left navigation pane, select **Applications > Applications**.
1. On the **Applications** page, select **Create App Integration**.
1. In the **Create a new app integration** dialog, select **SAML 2.0** and then select **Next**.
1. On the **Create SAML Integration** page in the **General Settings** section, provide a name for your application
   (such as `temporal-cloud`) and then select **Next**.
1. In the **Configure SAML** section in **Single sign on URL**, enter the following callback URL, including your Account
   Id where indicated:

   ```bash
   https://login.tmprl.cloud/login/callback?connection=ACCOUNT_ID-saml
   ```

   A correctly formed callback URL looks like this:

   ```bash
   https://login.tmprl.cloud/login/callback?connection=f45a2-saml
   ```

1. In **Audience URI (SP Entity ID)**, enter the following entity identifier, including your Account Id where indicated:

   ```bash
   urn:auth0:prod-tmprl:ACCOUNT_ID-saml
   ```

   A correctly formed entity identifier looks like this:

   ```bash
   urn:auth0:prod-tmprl:f45a2-saml
   ```

1. We require the user's full email address when connecting to Temporal.
   - In **Name ID format**, select `EmailAddress`.
   - In **Attribute Statements**, set **email** and **name**.
1. Select **Next**.
1. In the **Feedback** section, select **Finish**.
1. On the **Applications** page, select the name of the application integration you just created.
1. On the application integration page, select the **Sign On** tab.
1. Under **SAML Setup**, select **View SAML setup instructions**.
1. Collect information that you need to send to us:
   - Copy the IdP settings.
   - Download the active certificate.

To finish setting up Okta as your SAML IdP, see the next section,
[Finish SAML configuration](#finish-saml-configuration).

## How to finish your SAML configuration {#finish-saml-configuration}

After you configure SAML with your IdP, we can finish the configuration on our side.
[Create a support ticket](/cloud/support#support-ticket) that includes the following information:

- The sign-in URL from your application
- The X.509 SAML sign-in certificate in PEM format
- One or more IdP domains to map to the SAML connection

Generally, the provided IdP domain is the same as the domain for your email address. You can provide multiple IdP
domains.

When you receive confirmation from us that we have finished configuration, log in to Temporal Cloud. This time, though,
enter your email address in **Enterprise identity** and select **Continue**. Do not select **Continue with Google** or
**Continue with Microsoft**. You will be redirected to the authentication page of your IdP.

---

## SCIM user management

[SCIM](https://scim.cloud/) lets you integrate your identity provider (IdP) with Temporal Cloud to automate user provisioning and access. Once SCIM is configured, changes in your IdP are automatically reflected in Temporal Cloud, including:

- User creation / onboarding
- User deletion / offboarding
- User membership in groups

You can map SCIM groups to Temporal Cloud [roles and permissions](/cloud/users#account-level-roles-and-namespace-level-permissions), so users automatically get the Temporal Cloud access they need based on the groups they belong to.

:::info

SCIM is a paid feature. See the [pricing page](/cloud/pricing) for details.

:::

## Supported IdP Vendors

Supported upstream IdP vendors include:
* [Okta](#configure-scim-with-okta)
* Microsoft Entra ID (Azure AD)
* Google Workspace
* OneLogin
* CyberArk
* JumpCloud
* PingFederate
* Any SCIM 2.0-compliant provider

## Preparing for SCIM

Before starting your work with SCIM, you'll need to complete this checklist:

1. Configure [SAML](/cloud/saml) SSO.
1. Identify your organization's **IdP administrator**, who is responsible for configuring and managing your SCIM integration.
   Specify their contact details when you reach out to support in the next stage of this process.

After completing these steps, you're ready to submit your [support ticket](/cloud/support#support-ticket) to enable SCIM.

:::tip Adding and removing users

When SCIM is enabled for user management, you can still add and remove users outside of SCIM using the Temporal Cloud interface, until you disable user lifecycle management.
You can always change a user's or group's Account Role from the Temporal Cloud interface.

:::

## Onboarding with SCIM and Okta {#configure-scim-with-okta}

1. Temporal Support enables the SCIM integration on your account.
   Enabling integration automatically emails a configuration link to your Okta administrator.
   This authorizes them to set up the integration.
1. Your Okta administrator opens the supplied link.
   The link leads to step-by-step instructions for configuring the integration.
1. Once configured in Okta, Temporal Cloud will begin to receive SCIM messages and automatically onboard and offboard the users and groups configured in Okta.

Some points to note:

- User and group change events are applied within 10 minutes of them being made in Okta.
- User lifecycle management with SCIM also allows user roles to be derived from group membership.
- Once a group has been synced in Temporal Cloud, you can use `tcld` to assign roles to the group.
  For instructions, see the [User Group Management](https://github.com/temporalio/tcld?tab=readme-ov-file#user-group-management) page.

---

## Monitor Temporal Cloud

Temporal Cloud metrics help monitor production deployments.
This documentation covers best practices for monitoring Temporal Cloud.

## Monitor availability issues

When you see a sudden drop in Worker resource utilization, verify whether Temporal Cloud's API is showing increased latency and error rates.

### Reference Metrics

- [temporal\_cloud\_v1\_service\_latency\_p99](/cloud/metrics/openmetrics/metrics-reference#temporal_cloud_v1_service_latency_p99)

This metric measures latency for `SignalWithStartWorkflowExecution`, `SignalWorkflowExecution`, `StartWorkflowExecution` operations.
These operations are mission critical and never [throttled](/cloud/service-availability#throughput).
This metric is a good indicator of your lowest possible latency for the 99th percentile of requests.

## Monitor Temporal Service errors

Check for Temporal Service gRPC API errors.
Note that Service API errors are not equivalent to guarantees mentioned in the [Temporal Cloud SLA](/cloud/sla).

### Reference Metrics

- [temporal\_cloud\_v1\_frontend\_service\_error\_count](/cloud/metrics/openmetrics/metrics-reference#temporal_cloud_v1_service_error_count)
- [temporal\_cloud\_v1\_frontend\_service\_request\_count](/cloud/metrics/openmetrics/metrics-reference#temporal_cloud_v1_service_request_count)

### Prometheus Query for this Metric

Measure your daily average errors over 10-minute windows:

```
avg_over_time((
    (

        (
            sum(increase(temporal_cloud_v1_service_request_count{temporal_namespace=~"$namespace", operation=~"StartWorkflowExecution|SignalWorkflowExecution|SignalWithStartWorkflowExecution|RequestCancelWorkflowExecution|TerminateWorkflowExecution"}[10m]))
            -
            sum(increase(temporal_cloud_v1_service_error_count{temporal_namespace=~"$namespace", operation=~"StartWorkflowExecution|SignalWorkflowExecution|SignalWithStartWorkflowExecution|RequestCancelWorkflowExecution|TerminateWorkflowExecution"}[10m]))
        )
        /
        sum(increase(temporal_cloud_v1_service_request_count{temporal_namespace=~"$namespace", operation=~"StartWorkflowExecution|SignalWorkflowExecution|SignalWithStartWorkflowExecution|RequestCancelWorkflowExecution|TerminateWorkflowExecution"}[10m]))
    )

    or vector(1)

    )[1d:10m])
```

## Detecting Activity and Workflow Failures

The metrics `temporal_activity_execution_failed` and `temporal_cloud_v1_workflow_failed_count` together provide failure detection for Temporal applications. These metrics work in tandem to give you both granular component-level visibility and high-level workflow health insights.

Note that `temporal_activity_execution_failed` is an SDK metric that must be collected from the Worker.

### Activity failure cascade

If not using infinite retry policies, Activity failures can lead to Workflow failures:

```
Activity Failure --> Retry Logic --> More Activity Failures --> Workflow Decision --> Potential Workflow Failure
```

Activity failures are often recoverable and expected. Workflow failures represent terminal states requiring immediate attention.
A spike in activity failures may precede workflow failures.
Generally Temporal recommends that Workflows should be designed to always succeed. If an Activity fails more than its retry policy allows, we suggest having the Workflow handle Activity failure and take action to notify a human to take corrective action or be aware of the error.

### Ratio-based monitoring

#### Failure conversion rate

Monitor the ratio of workflow failures to activity failures:

```
workflow_failure_rate = temporal_cloud_v1_workflow_failed_count / temporal_activity_execution_failed
```

What to watch for:
- High ratio (greater than 0.1): Poor error handling - activities failing are causing workflow failures
- Low ratio (less than 0.01): Good resilience - activities fail but workflows recover
- Sudden spikes: May indicate systematic issues

#### Activity success rate

```
activity_success_rate = (total_activities - temporal_activity_execution_failed) / total_activities
```

Target: >95% for most applications. Lower success rate can be a sign of system troubles.
See also:
- [Crafting an Error Handling Strategy](https://learn.temporal.io/courses/errstrat/)
- [Temporal Failures reference](/references/failures)
- [Detecting Workflow failures](/encyclopedia/detecting-workflow-failures)

## Monitor replication lag for Namespaces with High Availability features

Replication lag refers to the transmission delay of Workflow updates and history events from the primary Namespace to the replica.
Always check the [metric replication lag](/cloud/metrics/openmetrics/metrics-reference#temporal_cloud_v1_replication_lag_p99) before initiating a failover.
A forced failover when there is a large replication lag has a higher likelihood of rolling back Workflow progress.

**Who owns the replication lag?**
Temporal owns replication lag.

**What guarantees are available?**
There is no SLA for replication lag.
Temporal recommends that customers do not trigger failovers except for testing or emergency situations.
High Availability feature's four-9 guarantee SLA means Temporal will handle failovers and ensure high availability.
Temporal also monitors replication lag.
Customer who decide to trigger failovers should look at this metric before moving forward.

**If the lag is high, what should you do?**
We don't expect users to failover.
Please contact Temporal support if you feel you have a pressing need.

**Where can you read more?**
See [operations and metrics](/cloud/high-availability) for Namespaces with High Availability features.

### Reference Metrics

- [temporal\_cloud\_v1\_replication\_lag\_p99](/cloud/metrics/openmetrics/metrics-reference#temporal_cloud_v1_replication_lag_p99)
- [temporal\_cloud\_v1\_replication\_lag\_p95](/cloud/metrics/openmetrics/metrics-reference#temporal_cloud_v1_replication_lag_p95)
- [temporal\_cloud\_v1\_replication\_lag\_p50](/cloud/metrics/openmetrics/metrics-reference#temporal_cloud_v1_replication_lag_p50)

## Detecting Resource Exhaustion

The Cloud metric `temporal_cloud_v1_resource_exhausted_error_count` is the primary indicator for Cloud-side throttling, signaling system limits
are exceeded and `ResourceExhausted` gRPC errors are occurring. This generally does not break workflow processing due to how resources are prioritized. 

Persistent non-zero values of this metric are unexpected.

## Monitoring Trends Against Limits {#rps-aps-rate-limits}

The set of [limit metrics](/cloud/metrics/openmetrics/metrics-reference#limit-metrics) provide a time series of values for limits. Use these 
metrics with their corresponding count metrics to monitor general trends against limits and set alerts when limits are exceeded. Use the corresponding throttle metrics
to determine the severity of any active rate limiting.
| Limit Metric | Count Metric | Throttle Metric |
| ------------ | ------------ | --------------- |
| `temporal_cloud_v1_action_limit` | `temporal_cloud_v1_total_action_count` | `temporal_cloud_v1_total_action_throttled_count` |
| `temporal_cloud_v1_service_request_limit` | `temporal_cloud_v1_service_request_count` | `temporal_cloud_v1_service_request_throttled_count` |
| `temporal_cloud_v1_operations_limit` | `temporal_cloud_v1_operations_count` | `temporal_cloud_v1_operations_throttled_count` |

The [Grafana dashboard example](https://github.com/grafana/jsonnet-libs/blob/master/temporal-mixin/dashboards/temporal-overview.json) includes a Usage & Quotas section
that creates demo charts for these limits and count metrics respectively.

The limit metrics, throttle metrics, and count metrics are already directly comparable as per second rates. Keep in mind that each `count` metric is represented as a per second rate averaged 
over each minute. For example, to get the total count of Actions, you must multiply this metric by 60.  
When setting alerts against limits, consider if your workload is spiky or sensitive to throttling (e.g. does latency matter?). If your workload is sensitive, consider alerting
for `temporal_cloud_v1_total_action_count` at a 50% threshold of the `temporal_cloud_v1_action_limit`. If your workload is not sensitive, consider an alert at 90% of this threshold
or directly when throttling is detected as a value greater than zero for `temporal_cloud_v1_total_action_throttled_count`. This logic can also be used to automatically scale [Temporal
Resource Units](/cloud/capacity-modes#provisioned-capacity) up or down as needed. Some workloads choose to exceed limits and accept throttling because they are not latency sensitive.

---

## tcld account command reference

The `tcld account` commands manage accounts in Temporal Cloud.

Alias: `a`

- [tcld account audit-log](#audit-log)
- [tcld account get](#get)
- [tcld account list-regions](#list-regions)
- [tcld account metrics](#metrics)

## audit-log

The `tcld account audit-log` command manage Audit Logs in Temporal Cloud.

Alias: `al`

- [tcld account audit-log kinesis](#kinesis)
- [tcld account audit-log pubsub](#pubsub)

### kinesis

The `tcld account audit-log kinesis` command manages Kinesis audit log sinks.

Alias: `k`

- [tcld account audit-log kinesis create](#create)
- [tcld account audit-log kinesis delete](#delete)
- [tcld account audit-log kinesis get](#account-audit-log-kinesis-get)
- [tcld account audit-log kinesis list](#list)
- [tcld account audit-log kinesis update](#update)
- [tcld account audit-log kinesis validate](#validate)

#### create

The `tcld account audit-log kinesis` command creates a Kinesis audit log sink.

Alias: `c`

##### --destination-uri

The destination URI of the audit log sink.

Alias: `du`

##### --region

The region to use for the request.

Alias: `re`

##### --role-name

The role name to use to write to the sink.

Alias: `rn`

##### --sink-name

Provide a name for the sink.

#### delete

The `tcld account audit-log kinesis delete` command deletes an audit log sink.

Alias: `d`

##### --resource-version

The resource-version (etag) to update from, if not set the cli will use the latest (optional).

Alias: `v`

##### --sink-name

Provide a name for the sink.

#### get {#account-audit-log-kinesis-get}

The `tcld account audit-log kinesis get` command gets an audit log sink.

Alias: `g`

##### --sink-name

Provide a name for the sink.

#### list

The `tcld account audit-log kinesis list` command lists audit log sinks on the account.

Alias: `l`

##### --page-size

The page size for list operations.

##### --page-token

The page token for list operations.

#### update

The `tcld account audit-log kinesis update` command updates an audit log sink.

Alias: `u`

##### --destination-uri

The destination URI of the audit log sink.

Alias: `du`

##### --enabled

Whether the sink is enabled.

##### --region

The region to use for the request.

Alias: `re`

##### --resource-version

The resource-version (etag) to update from, if not set the cli will use the latest (optional).

Alias: `v`

##### --role-name

The role name to use to write to the sink.

Alias: `rn`

##### --sink-name

Provide a name for the sink.

#### validate

The `tcld account audit-log kinesis validate` command verifies Temporal Cloud can write to a Kinesis sink.

Alias: `v`

##### --destination-uri

The destination URI of the audit log sink.

Alias: `du`

##### --region

The region to use for the request.

Alias: `re`

##### --role-name

The role name to use to write to the sink.

Alias: `rn`

##### --sink-name

Provide a name for the sink.

### pubsub

The `tcld account audit-log pubsub` command manages Pub/Sub audit log sinks.

Alias: `ps`

- [tcld account audit-log pubsub create](#create)
- [tcld account audit-log pubsub delete](#delete)
- [tcld account audit-log pubsub get](#account-audit-log-pubsub-get)
- [tcld account audit-log pubsub list](#list)
- [tcld account audit-log pubsub update](#update)
- [tcld account audit-log pubsub validate](#validate)

#### create

The `tcld account audit-log pubsub` command creates a Pub/Sub audit log sink.

Alias: `c`

##### --service-account-email

The service account email to impersonate to write to the sink.

Alias: `sae`

##### --sink-name

Provide a name for the sink.

##### --topic-name

The topic name to write to the sink.

Alias: `tn`

#### delete

The `tcld account audit-log pubsub delete` command deletes an audit log sink.

Alias: `d`

##### --resource-version

The resource-version (etag) to update from, if not set the cli will use the latest (optional).

Alias: `v`

##### --sink-name

Provide a name for the sink.

#### get {#account-audit-log-pubsub-get}

The `tcld account audit-log pubsub get` command gets an audit log sink.

Alias: `g`

##### --sink-name

Provide a name for the sink.

#### list

The `tcld account audit-log pubsub list` command lists audit log sinks on the account.

Alias: `l`

##### --page-size

The page size for list operations.

##### --page-token

The page token for list operations.

#### update

The `tcld account audit-log pubsub update` command updates an audit log sink.

Alias: `u`

##### --enabled

Whether the sink is enabled.

##### --resource-version

The resource-version (etag) to update from, if not set the cli will use the latest (optional).

Alias: `v`

##### --service-account-email

The service account email to impersonate to write to the sink.

Alias: `sae`

##### --sink-name

Provide a name for the sink.

##### --topic-name

The topic name to write to the sink.

Alias: `tn`

#### validate

The `tcld account audit-log pubsub validate` command verifies Temporal Cloud can write to a Pub/Sub sink.

Alias: `v`

##### --service-account-email

The service account email to impersonate to write to the sink.

Alias: `sae`

##### --sink-name

Provide a name for the sink.

##### --topic-name

The topic name to write to the sink.

Alias: `tn`

## get

The `tcld account get` command gets information about the Temporal Cloud account you are logged into.

Alias: `g`

`tcld account get`

The command has no modifiers.

## list-regions

The `tcld account list-regions` lists all regions where the account can provision namespaces.

Alias: `l`

## metrics

The `tcld account metrics` commands configure the metrics endpoint for the Temporal Cloud account that is currently logged in.

Alias: `m`

- [tcld account metrics enable](#enable)
- [tcld account metrics disable](#disable)
- [tcld account metrics accepted-client-ca](#accepted-client-ca)

### accepted-client-ca

The `tcld account metrics accepted-client-ca` commands manage the end-entity certificates for the metrics endpoint of the Temporal Cloud account that is currently logged in.

:::info

The end-entity certificates for the metrics endpoint must chain up to the CA certificate used for the account. For more information, see [Certificate requirements](/cloud/certificates#certificate-requirements).

:::

Alias: `ca`

- [tcld account metrics accepted-client-ca add](#add)
- [tcld account metrics accepted-client-ca list](#list)
- [tcld account metrics accepted-client-ca set](#set)
- [tcld account metrics accepted-client-ca remove](#remove)

#### add

The `tcld account metrics accepted-client-ca add` command adds end-entity certificates to the metrics endpoint of a Temporal Cloud account.

:::info

The end-entity certificates for the metrics endpoint must chain up to the CA certificate used for the account. For more information, see [Certificate requirements](/cloud/certificates#certificate-requirements).

:::

`tcld account metrics accepted-client-ca add --ca-certificate <value>`

Alias: `a`

The following modifiers control the behavior of the command.

##### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request identifier.

Alias: `-r`

**Example**

```bash
tcld account metrics accepted-client-ca add --request-id <request_id> --ca-certificate <encoded_certificate>
```

##### --resource-version

Specify a resource version (ETag) to update from. If not specified, the latest version is used.

Alias: `-v`

**Example**

```bash
tcld account metrics accepted-client-ca add --resource-version <etag> --ca-certificate <encoded_certificate>
```

##### --ca-certificate

_Required modifier unless `--ca-certificate-file` is specified_

Specify a base64-encoded string of a CA certificate PEM file.

If both `--ca-certificate` and `--ca-certificate-file` are specified, only `--ca-certificate` is used.

Alias: `-c`

**Example**

```bash
tcld account metrics accepted-client-ca add --ca-certificate <encoded_certificate>
```

##### --ca-certificate-file

_Required modifier unless `--ca-certificate` is specified_

Specify a path to a CA certificate PEM file.

If both `--ca-certificate` and `--ca-certificate-file` are specified, only `--ca-certificate` is used.

Alias: `-f`

**Example**

```bash
tcld account metrics accepted-client-ca add --ca-certificate-file <path>
```

#### list

The `tcld account metrics accepted-client-ca list` command lists the end-entity certificates that are currently configured for the metrics endpoint of a Temporal Cloud account.

`tcld account metrics accepted-client-ca list`

Alias: `l`

The command has no modifiers.

#### remove

The `tcld account metrics accepted-client-ca remove` command removes end-entity certificates from the metrics endpoint of a Temporal Cloud account.

`tcld account metrics accepted-client-ca remove --ca-certificate <value>`

Alias: `r`

The following modifiers control the behavior of the command.

##### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request identifier.

Alias: `-r`

**Example**

```bash
tcld account metrics accepted-client-ca remove --request-id <request_id> --ca-certificate <encoded_certificate>
```

##### --resource-version

Specify a resource version (ETag) to update from. If not specified, the latest version is used.

Alias: `-v`

**Example**

```bash
tcld account metrics accepted-client-ca remove --resource-version <etag> --ca-certificate <encoded_certificate>
```

##### --ca-certificate

_Required modifier unless `--ca-certificate-fingerprint` or `--ca-certificate-file` is specified_

Specify a base64-encoded string of a CA certificate PEM file.

If `--ca-certificate-fingerprint` is also specified, both `--ca-certificate` and `--ca-certificate-file` are ignored.

If `--ca-certificate-file` is also specified but `--ca-certificate-fingerprint` is not, only `--ca-certificate` is used.

Alias: `-c`

**Example**

```bash
tcld account metrics accepted-client-ca remove --ca-certificate <encoded_certificate>
```

##### --ca-certificate-file

_Required modifier unless `--ca-certificate-fingerprint` or `--ca-certificate` is specified_

Specify a path to a CA certificate PEM file.

If `--ca-certificate-fingerprint` is also specified, both `--ca-certificate-file` and `--ca-certificate` are ignored.

If `--ca-certificate` is also specified but `--ca-certificate-fingerprint` is not, only `--ca-certificate` is used.

Alias: `-f`

**Example**

```bash
tcld account metrics accepted-client-ca remove --ca-certificate-file <path>
```

##### --ca-certificate-fingerprint

_Required modifier unless `--ca-certificate` or `--ca-certificate-file` is specified_

Specify the fingerprint of a CA certificate.

If `--ca-certificate`, `--ca-certificate-file`, or both are also specified, they are ignored.

Alias: `--fp`

**Example**

```bash
tcld account metrics accepted-client-ca remove --ca-certificate-fingerprint <fingerprint>
```

#### set

The `tcld account metrics accepted-client-ca set` command sets the end-entity certificates for the metrics endpoint of a Temporal Cloud account.

:::info

The end-entity certificates for the metrics endpoint must chain up to the CA certificate used for the account. For more information, see [Certificate requirements](/cloud/certificates#certificate-requirements).

:::

`tcld account metrics accepted-client-ca set --ca-certificate <value>`

Alias: `s`

The following modifiers control the behavior of the command.

##### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request identifier.

Alias: `-r`

**Example**

```bash
tcld account metrics accepted-client-ca set --request-id <request_id> --ca-certificate <encoded_certificate>
```

##### --resource-version

Specify a resource version (ETag) to update from. If not specified, the latest version is used.

Alias: `-v`

**Example**

```bash
tcld account metrics accepted-client-ca set --resource-version <etag> --ca-certificate <encoded_certificate>
```

##### --ca-certificate

_Required modifier unless `--ca-certificate-file` is specified_

Specify a base64-encoded string of a CA certificate PEM file.

If both `--ca-certificate` and `--ca-certificate-file` are specified, only `--ca-certificate` is used.

Alias: `-c`

**Example**

```bash
tcld account metrics accepted-client-ca set --ca-certificate <encoded_certificate>
```

##### --ca-certificate-file

_Required modifier unless `--ca-certificate` is specified_

Specify a path to a CA certificate PEM file.

If both `--ca-certificate` and `--ca-certificate-file` are specified, only `--ca-certificate` is used.

Alias: `-f`

**Example**

```bash
tcld account metrics accepted-client-ca set --ca-certificate-file <path>
```

### enable

The `tcld account metrics enable` command enables the metrics endpoint for the Temporal Cloud account that is currently logged in.

:::info

The end-entity for the metrics endpoint _must_ be configured before the endpoint can be enabled. See the [tcld account metrics accepted-client-ca](#accepted-client-ca) commands.

:::

`tcld account metrics enable`

The command has no modifiers.

### disable

The `tcld account metrics disable` command disables the metrics endpoint for the Temporal Cloud account that is currently logged in.

`tcld account metrics disable`

The command has no modifiers.

---

## tcld apikey command reference

The `tcld apikey` commands manage API Keys in Temporal Cloud.

Alias: `ak`

- [tcld apikey create](#create)
- [tcld apikey get](#get)
- [tcld apikey list](#list)
- [tcld apikey delete](#delete)
- [tcld apikey disable](#disable)
- [tcld apikey enable](#enable)

## create

The `tcld apikey create` command creates an API Key in Temporal Cloud.

`tcld apikey create --name <name> --description <description> --duration <duration> --expiry <expiry> --request-id <request_id>`

The following options control the behavior of the command.

#### --name

_Required modifier_

Specify the display name of the API Key.

Alias: `-n`

**Example**

```bash
tcld apikey create --name <name>
```

#### --description

Specify a description for the API Key.

Alias: `-desc`

**Example**

```bash
tcld apikey create --name <name> --description "Your API Key"
```

#### --duration

Specify the duration from now when the API Key will expire.
This will be ignored if the expiry flag is set.

Example format: `24h` (default: 0s).

Alias: `-d`

**Example**

```bash
tcld apikey create --name <name> --duration 24h
```

#### --expiry

Specify the absolute timestamp (RFC3339) when the API Key will expire.

Example: `2023-11-28T09:23:24-08:00`.

Alias: `-e`

**Example**

```bash
tcld apikey create --name <name> --expiry '2023-11-28T09:23:24-08:00'
```

#### --request-id

Specify a request-id for the asynchronous operation.
If not set, the server will assign one.

Alias: `-r`

**Example**

```bash
tcld apikey create --name <name> --request-id <request_id>
```

## get

The `tcld apikey get` command retrieves the details of a specified API Key in Temporal Cloud.

`tcld apikey get --id <id>`

The following option controls the behavior of the command.

#### --id

_Required modifier_

Specify the ID of the API Key to retrieve.

Alias: `-i`

**Example**

```bash
tcld apikey get --id <apikey_id>
```

## list

The `tcld apikey list` command lists all API Keys in Temporal Cloud.

`tcld apikey list`

This command does not require any specific options.

Alias: `l`

**Example**

```bash
tcld apikey list
```

## delete

The `tcld apikey delete` command deletes an API Key in Temporal Cloud.

`tcld apikey delete --id <id> [--resource-version <version>] [--request-id <request_id>]`

The following options control the behavior of the command.

#### --id

_Required modifier_

Specify the ID of the API Key to delete.

Alias: `-i`

**Example**

```bash
tcld apikey delete --id <apikey_id>
```

#### --resource-version

Specify the resource-version (etag) to update from.
If not set, the CLI will use the latest.

Alias: `-v`

**Example**

```bash
tcld apikey delete --id <apikey_id> --resource-version <version>
```

#### --request-id

Specify a request-id for the asynchronous operation.
If not set, the server will assign one.

Alias: `-r`

**Example**

```bash
tcld apikey delete --id <apikey_id> --request-id <request_id>
```

## disable

The `tcld apikey disable` command disables an API Key in Temporal Cloud.

`tcld apikey disable --id <id> [--resource-version <version>] [--request-id <request_id>]`

The following options control the behavior of the command.

#### --id

_Required modifier_

Specify the ID of the API Key to disable.

Alias: `-i`

**Example**

```bash
tcld apikey disable --id <apikey_id>
```

#### --resource-version

Specify the resource-version (etag) to update from. If not set, the CLI will use the latest.

Alias: `-v`

**Example**

```bash
tcld apikey disable --id <apikey_id> --resource-version <version>
```

#### --request-id

Specify a request-id for the asynchronous operation. If not set, the server will assign one.

Alias: `-r`

**Example**

```bash
tcld apikey disable --id <apikey_id> --request-id <request_id>
```

## enable

The `tcld apikey enable` command enables a disabled API Key in Temporal Cloud.

`tcld apikey enable --id <id> [--resource-version <version>] [--request-id <request_id>]`

The following options control the behavior of the command.

#### --id

_Required modifier_

Specify the ID of the API Key to enable.

Alias: `-i`

**Example**

```bash
tcld apikey enable --id <apikey_id>
```

#### --resource-version

Specify the resource-version (etag) to update from.
If not set, the CLI will use the latest.

Alias: `-v`

**Example**

```bash
tcld apikey enable --id <apikey_id> --resource-version <version>
```

#### --request-id

Specify a request-id for the asynchronous operation.
If not set, the server will assign one.

Alias: `-r`

**Example**

```bash
tcld apikey enable --id <apikey_id> --request-id <request_id>
```

---

## tcld connectivity-rule command reference

The `tcld connectivity-rule` commands manage [connectivity rules](/cloud/connectivity#connectivity-rules) in Temporal Cloud.

Alias: `cr`

- [tcld connectivity-rule create](#create)
- [tcld connectivity-rule delete](#delete)
- [tcld connectivity-rule get](#get)
- [tcld connectivity-rule list](#list)

## create

The `tcld connectivity-rule create` command creates a connectivity rule.

Alias: `c`

#### --connection-id

The connection ID of the private connection.

Alias: `ci`

#### --connectivity-type

The type of connectivity, currently only support 'private' and 'public'.

Alias: `ct`

#### --gcp-project-id

The GCP project ID of the connection, required if the cloud provider is 'gcp'.

Alias: `gpi`

#### --region

The region of the connection.

Alias: `r`

## delete

The `tcld connectivity-rule delete` command deletes a connectivity rule.

Alias: `d`

#### --connectivity-rule-id

The connectivity rule ID.

Alias: `id`

## get

The `tcld connectivity-rule get` command gets a connectivity rule.

Alias: `g`

#### --connectivity-rule-id

The connectivity rule ID.

Alias: `id`

## list

The `tcld connectivity-rule list` command lists connectivity rules.

Alias: `l`

#### --namespace

The namespace hosted on temporal cloud.

Alias: `n`

---

## tcld feature command reference

The `tcld feature` commands manage features in Temporal Cloud.

Alias: `f`

- [tcld feature get](#get)
- [tcld feature toggle](#toggle)

## get

The `tcld feature get` command gets information about the Temporal Cloud features you've enabled.

Alias: `g`

`tcld feature get`

The command has no modifiers.

**Example**

`tcld feature get`

The following is an example output:

```json
[
  {
    "Name": "enable-apikey",
    "Value": true
  }
]
```

## toggle

The `tcld feature toggle-*` command turns on or off the `*` feature in Temporal Cloud.

:::note

The `*` symbol represents the name of the feature.
Replace `*` with the name of the available feature to toggle.

:::

Alias: `tak`

`tcld feature toggle-*`

The command has no modifiers.

**Example**

`tcld feature toggle-apikey`

The following is an example output:

```json
Feature flag enable-apikey is now true
```

:::note

The feature `apikey` is an example.
Update the feature name to toggle a different feature.

:::

---

## tcld generate-certificates command reference

The `tcld generate-certificates` commands generate certificate authority (CA) and end-entity TLS certificates for Temporal Cloud.

Alias: `gen`

- [tcld generate-certificates certificate-authority-certificate](#certificate-authority-certificate)
- [tcld generate-certificates end-entity-certificate](#end-entity-certificate)

## tcld generate-certificates certificate-authority-certificate {#certificate-authority-certificate}

The `tcld generate-certificates certificate-authority-certificate` command generates certificate authority (CA) certificates for Temporal Cloud.

`tcld generate-certificates certificate-authority-certificate <modifiers>`

Alias: `ca`

The following modifiers control the behavior of the command.

#### --organization

Specify an organization name for certificate generation.

Alias: `--org`

**Example**

```bash
tcld generate-certificates certificate-authority-certificate --organization <value>
```

#### --validity-period

Specify the duration for which the certificate is valid.
Format values as d/h (for example, `30d10h` for a certificate lasting 30 days and 10 hours).

Alias: `-d`

**Example**

```bash
tcld generate-certificates certificate-authority-certificate --validity-period <value>
```

#### --ca-certificate-file

Specify a path to a `.pem` file where the generated X.509 certificate file will be stored.

Alias: `--ca-cert`

**Example**

```bash
tcld generate-certificates certificate-authority-certificate --ca-certificate-file <path>
```

#### --ca-key-file

Specify a path to a `.key` file where the certificate's private key will be stored.

Alias: `--ca-key`

**Example**

```bash
tcld generate-certificates certificate-authority-certificate --ca-key-file <path>
```

#### --rsa-algorithm

When enabled, a 4096-bit RSA key pair is generated for the certificate instead of an ECDSA P-384 key pair.
Because an ECDSA P-384 key pair is the recommended default, this option is disabled.

Alias: `--rsa`

**Example**

```bash
tcld generate-certificates certificate-authority-certificate --rsa-algorithm <boolean>
```

## tcld generate-certificates end-entity-certificate {#end-entity-certificate}

The `tcld generate-certificates end-entity-certificate` command generates end-entity (leaf) certificates for Temporal Cloud.

`tcld generate-certificates end-entity-certificate <modifiers>`

Alias: `leaf`

The following modifiers control the behavior of the command.

#### --organization

Specify an organization name for certificate generation.

Alias: `--org`

**Example**

```bash
tcld generate-certificates end-entity-certificate --organization <value>
```

#### --organization-unit

Optional: Specify the name of the organization unit.

**Example**

```bash
tcld generate-certificates end-entity-certificate --organization-unit <value>
```

#### --validity-period

Specify the duration for which the certificate is valid.
Format values as d/h (for example, `30d10h` for a certificate lasting 30 days and 10 hours).

Alias: `-d`

**Example**

```bash
tcld generate-certificates end-entity-certificate --validity-period <value>
```

#### --ca-certificate-file

Specify the path of the X.509 CA certificate in a `.pem` file for the certificate authority.

Alias: `--ca-cert`

**Example**

```bash
tcld generate-certificates end-entity-certificate --ca-certificate-file <path>
```

#### --ca-key-file

Specify the path of the private key in a `.key` file for the certificate authority.

Alias: `--ca-key`

**Example**

```bash
tcld generate-certificates end-entity-certificate --ca-key-file <path>
```

#### --certificate-file

Specify a path to a `.pem` file where the generated X.509 leaf certificate file will be stored.

Alias: `--cert`

**Example**

```bash
tcld generate-certificates end-entity-certificate --certificate-file <path>
```

#### --key-file

Specify a path to a `.key` file where the leaf certificate's private key will be stored.

Alias: `--key`

**Example**

```bash
tcld generate-certificates end-entity-certificate --key-file <path>
```

---

## tcld command reference

The Temporal Cloud CLI (tcld) is a command-line tool that you can use to interact with Temporal Cloud.

- [How to install tcld](#install-tcld)

### tcld commands

- [tcld account](/cloud/tcld/account)
- [tcld apikey](/cloud/tcld/apikey)
- [tcld connectivity-rule](/cloud/tcld/connectivity-rule)
- [tcld feature](/cloud/tcld/feature)
- [tcld generate-certificates](/cloud/tcld/generate-certificates)
- [tcld login](/cloud/tcld/login)
- [tcld logout](/cloud/tcld/logout/)
- [tcld namespace](/cloud/tcld/namespace)
- [tcld nexus](/cloud/tcld/nexus)
- [tcld request](/cloud/tcld/request)
- [tcld user](/cloud/tcld/user)
- [tcld version](/cloud/tcld/version/)

### Global modifiers

#### --auto_confirm

Automatically confirm all prompts.

You can specify the value for this modifier by setting the AUTO_CONFIRM environment variable.
The default value is `false`.

## How to install tcld {#install-tcld}

You can install [tcld](/cloud/tcld) in two ways.

### Install tcld by using Homebrew

```bash
brew install temporalio/brew/tcld
```

### Build tcld from source

1. Verify that you have Go 1.18 or later installed.

   ```bash
   go version
   ```

   If Go 1.18 or later is not installed, follow the [Download and install](https://go.dev/doc/install) instructions on the Go website.

1. Clone the tcld repository and run make.

   ```bash
   git clone https://github.com/temporalio/tcld.git
   cd tcld
   make
   ```

1. Copy the tcld executable to any directory that appears in the PATH environment variable, such as `/usr/local/bin`.

   ```bash
   cp tcld /usr/local/bin/tcld
   ```

1. Verify that tcld is installed.

   ```bash
   tcld version
   ```

---

## tcld login command reference

The `tcld login` command logs in a user to Temporal Cloud.

Follow instructions in the browser to log in to your Temporal account.

Alias: `l`

`tcld login`

The command has no modifiers.

---

## tcld logout command reference

The `tcld logout` command logs a user out of Temporal Cloud.

Alias: `lo`

`tcld logout`

The following modifier controls the behavior of the command.

#### --disable-pop-up

Disables a browser pop-up if set to `true`. The default value is `false`.

---

## tcld namespace command reference

The `tcld namespace` commands enable [Namespace](/namespaces) operations in Temporal Cloud.

Alias: `n`

:::info Namespace ID Format

The `--namespace` flag accepts a **Namespace ID** in the format `<namespace_name>.<account_suffix>` (e.g., `your-namespace.a1b2c`). This is the full identifier shown in Temporal Cloud, not just the [Namespace Name](/cloud/namespaces#temporal-cloud-namespace-name). You can find your account suffix in the Temporal Cloud UI.

:::

- [tcld namespace add-region](#add-region)
- [tcld namespace create](#create)
- [tcld namespace delete](#delete)
- [tcld namespace failover](#failover)
- [tcld namespace get](#get)
- [tcld namespace list](#list)
- [tcld namespace export](#export)
- [tcld namespace accepted-client-ca](#accepted-client-ca)
- [tcld namespace certificate-filters](#certificate-filters)
- [tcld namespace search-attributes](#search-attributes)
- [tcld namespace retention](#retention)
- [tcld namespace update-codec-server](#update-codec-server)
- [tcld namespace update-high-availability](#update-high-availability)
- [tcld namespace tags](#tags)
- [tcld namespace set-connectivity-rules](#set-connectivity-rules)

## add-region

Use `tcld namespace add-region` to add a <ToolTipTerm term="replica" /> region to an existing Temporal Cloud [Namespace](/namespaces), upgrading it to support [High Availability](/cloud/high-availability).

See [Regions](/cloud/regions) for available regions and their supported replication options.

The following modifiers control the behavior of the command.

#### --request-id

The request identifier to use for the asynchronous operation. If not set, the server assigns an identifier.

Alias: `-r`

#### --namespace

**Required.** Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable `$TEMPORAL_CLOUD_NAMESPACE` is used.

Alias: `-n`

#### --region

**Required.** The region to add to the existing Namespace. See [Regions](/cloud/regions) for a list of supported regions.

:::tip Choosing Replica Regions

See [Regions](/cloud/regions) for available regions and their supported replication options. See [High Availability](/cloud/high-availability) to learn how replication and failover work.

:::

Alias: `--re`

**Example**

```bash
tcld namespace add-region \
    --namespace <namespace_id> \
    --region <replica_region>
```

Specify the region code of the region where you want to create the replica as an argument to the `--region` flag.
See [High Availability](/cloud/high-availability) for details on same-region, multi-region, and multi-cloud replication options.

Temporal Cloud sends an email alert once your Namespace is ready for use.

#### --cloud-provider

The cloud provider of the region. One of [`aws`, `gcp`].

Default: `aws`

## create

The `tcld namespace create` command creates a Temporal [Namespace](/namespaces) in Temporal Cloud.

Alias: `c`

The following modifiers control the behavior of the command.

#### --namespace

**Required.** The name for the new Namespace. This becomes part of the Namespace ID (`<namespace_name>.<account_suffix>`).

Alias: `-n`

#### --region

**Required.** The cloud provider region to create the Namespace in. Supply one `--region` for a standard Namespace, or two for a Namespace with [High Availability](/cloud/high-availability).

See [Regions](/cloud/regions) for available regions and their supported replication options.

Alias: `--re`

#### --auth-method

The authentication method for the Namespace. One of [`mtls`, `api_key`].

- `mtls` (default): Requires `--ca-certificate` or `--ca-certificate-file`
- `api_key`: No other modifiers

**Example**

```bash
tcld namespace create \
    --namespace test-namespace.a1b2c \
    --region us-east-1 \
    --auth-method api_key
```

#### --ca-certificate

A base64-encoded [CA certificate](/cloud/certificates). If both `--ca-certificate` and `--ca-certificate-file` are specified, only `--ca-certificate` is used.

Alias: `-c`

#### --ca-certificate-file

A path to a [CA certificate](/cloud/certificates) PEM file. If both options are specified, only `--ca-certificate` is used.

Alias: `--cf`

#### --certificate-filter-file

Path to a JSON file that defines the [certificate filters](/cloud/certificates#manage-certificate-filters) to be applied to the Namespace.

Sample JSON: `{ "filters": [ { "commonName": "test1" } ] }`

If both `--certificate-filter-file` and `--certificate-filter-input` are specified, the command returns an error.

Alias: `--cff`

#### --certificate-filter-input

A JSON string that defines the [certificate filters](/cloud/certificates#manage-certificate-filters) to be applied to the Namespace.

Sample JSON: `{ "filters": [ { "commonName": "test1" } ] }`

If both `--certificate-filter-input` and `--certificate-filter-file` are specified, the command returns an error.

Alias: `--cfi`

#### --cloud-provider

The cloud provider of the region. One of [`aws`, `gcp`].

Default: `aws`

Alias: `--cp`

#### --connectivity-rule-ids

A list of [connectivity rule](/cloud/connectivity#connectivity-rules) IDs to apply to the Namespace. Can be specified more than once.

Alias: `--ids`

**Example**

```bash
tcld namespace create \
    --namespace test-namespace.a1b2c \
    --region us-east-1 \
    --auth-method api_key \
    --connectivity-rule-ids <rule_id1> \
    --connectivity-rule-ids <rule_id2>
```

#### --enable-delete-protection

Enable [delete protection](/cloud/namespaces#delete-protection) on the Namespace.

Default: `false`

Alias: `--edp`

#### --endpoint

The [codec server](/production-deployment/data-encryption) endpoint to decode payloads for all users interacting with this Namespace. Must be HTTPS.

Alias: `-e`

#### --include-credentials

Include cross-origin credentials when calling the [codec server](/production-deployment/data-encryption).

Default: `false`

Alias: `--ic`

#### --pass-access-token

Pass the user access token to the [codec server](/production-deployment/data-encryption) endpoint.

Default: `false`

Alias: `--pat`

#### --request-id

The request identifier to use for the asynchronous operation. If not set, the server assigns an identifier.

Alias: `-r`

#### --retention-days

The [retention period](/temporal-service/temporal-server#retention-period) in days for closed Workflow Executions.

Default: `30`

Alias: `--rd`

#### --search-attribute

A custom [Search Attribute](/search-attribute) in the form '_name_=_type_'. Can be specified more than once.

Valid values for _type_: `Bool` | `Datetime` | `Double` | `Int` | `Keyword` | `Text`

Alias: `--sa`

**Example**

```bash
tcld namespace create \
    --namespace test-namespace.a1b2c \
    --region us-east-1 \
    --auth-method api_key \
    --search-attribute "customer_id=Int" \
    --search-attribute "customer_name=Text"
```

#### --tag

A [tag](/cloud/namespaces#tag-a-namespace) in the form "_key_=_value_". Can be specified more than once.

See [Tag structure and limits](/cloud/namespaces#tag-structure-and-limits).

Alias: `--t`

**Example**

```bash
tcld namespace create \
    --namespace test-namespace.a1b2c \
    --region us-east-1 \
    --auth-method api_key \
    --tag "key=value" \
    --tag "key2=value2"
```

#### --user-namespace-permission

A [Namespace-level permission](/cloud/users#namespace-level-permissions) for a user in the form '_email_=_permission_'. Can be specified more than once.

Valid values for _permission_: `Admin` | `Write` | `Read`

Alias: `-p`

**Example**

```bash
tcld namespace create \
    --namespace test-namespace.a1b2c \
    --region us-east-1 \
    --auth-method api_key \
    --user-namespace-permission "user@example.com=Admin" \
    --user-namespace-permission "user2@example.com=Write"
```

## delete

The `tcld namespace delete` command deletes the specified [Namespace](/namespaces) in Temporal Cloud.

Alias: `d`

`tcld namespace delete`

The following modifiers control the behavior of the command.

#### --namespace

**Required.** Specify the Namespace hosted on Temporal Cloud to be deleted.

Alias: `-n`

#### --request-id

The request identifier to use for the asynchronous operation. If not set, the server assigns an identifier.

Alias: `-r`

#### --resource-version

A resource version (ETag) to update from. If not set, the CLI uses the latest.

Alias: `-v`

**Example**

```bash
tcld namespace delete \
    --namespace <namespace_id>
```

## delete-region

Use `tcld namespace delete-region` to remove a <ToolTipTerm term="replica" /> for an existing Temporal Cloud
[Namespace](/namespaces). Removing a replica disables [High Availability features](/cloud/high-availability) and results
in a mandatory 7-day waiting period before you can re-enable High Availability features in the same location. Refer to
[Enable High Availability](/cloud/high-availability/enable) for more information.

The following modifiers control the behavior of the command.

#### --request-id

The request identifier to use for the asynchronous operation. If not set, the server assigns an identifier.

Alias: `-r`

#### --namespace

**Required.** Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable `$TEMPORAL_CLOUD_NAMESPACE` is used.

Alias: `-n`

#### --region

**Required.** The region to remove from the Namespace. Upon removal, Temporal stops replication and the Namespace becomes a Standard Namespace. You cannot re-add a region or add a new region for seven days after removing a Namespace region.

Alias: `--re`

**Example**

```bash
tcld namespace delete-region \
    --namespace <namespace_id>\
    --region <replica_region>
```

When using API key authentication, add your API credentials before pressing Enter:

```bash
tcld --api-key <your_api_key> \
    delete-region \
    --namespace <namespace_id> \
    --region <replica_region>
```

#### --cloud-provider

The cloud provider of the region to failover to. One of [aws, gcp].

Default: aws (default: "aws")

## failover

Failover a Temporal Namespace with [High Availability features](/cloud/high-availability). A failover switches a
Namespace region from a primary Namespace to its replica.

**Example**

```bash
tcld namespace failover \
    --namespace <namespace_id> \
    --region <target_region>
```

When using API key authentication, add your API credentials before pressing Enter:

```bash
tcld --api-key <your_api_key> \
    namespace failover \
    --namespace <namespace_id> \
    --region <target_region>
```

#### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request
identifier.

Alias: `-r`

#### --namespace

**Required.** Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable `$TEMPORAL_CLOUD_NAMESPACE` is used.

Alias: `-n`

#### --region

**Required.** The region to failover _to_.

See [Regions](/cloud/regions) for a list of supported regions.

Alias: `--re`

#### --ca-certificate

_Required modifier unless `--ca-certificate-file` is specified_.

A base64-encoded CA certificate.

If both `--ca-certificate` and `--ca-certificate-file` are specified, only `--ca-certificate` is used.

Alias: `-c`

#### --cloud-provider

The cloud provider of the region to failover to. One of [aws, gcp].

Default: aws (default: "aws")

## get

The `tcld namespace get` command gets information about the specified [Namespace](/namespaces) in Temporal Cloud.

Alias: `g`

`tcld namespace get`

The following modifier controls the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

**Example**

```bash
tcld namespace get \
    --namespace <namespace_id>
```

## list

The `tcld namespace list` command lists all [Namespaces](/namespaces) in Temporal Cloud.

Alias: `l`

`tcld namespace list`

The command has no modifiers.

## export

The `tcld namespace export s3` commands manage Workflow History Exports.

Valid options: `s3`

Alias: `es`

- [tcld namespace export s3 create](#create)
- [tcld namespace export s3 get](#get)
- [tcld namespace export s3 delete](#delete)
- [tcld namespace export s3 list](#list)
- [tcld namespace export s3 update](#update)
- [tcld namespace export s3 validate](#validate)

### create

The `tcld namespace export s3 create` command allows users to create an export sink for the Namespace of a Temporal
Cloud account.

**Example**

```bash
tcld namespace export s3 create \
    --namespace <namespace_id> \
    --sink-name <sink_name> \
    --s3-bucket-name <bucket_name> \
    --role-arn <role_arn>
```

The following modifiers control the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

#### --sink-name

Provide a name for the export sink.

_Required modifier_

#### --role-arn

Provide role arn for the IAM Role.

_Required modifier_

#### --s3-bucket-name

Provide the name of an AWS S3 bucket that Temporal will send closed workflow histories to.

_Required modifier_

#### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request
identifier.

Alias: `-r`

#### --kms-arn

Provide the ARN of the KMS key to use for encryption. Note: If the KMS ARN needs to be added or updated, users should
create the IAM Role with KMS or modify the created IAM Role accordingly. Providing it as part of the input won't help.

### get

The `tcld namespace export s3 get` command allows users to retrieve details about an existing export sink from the
Namespace of a Temporal Cloud account.

**Example**

```bash
tcld namespace export s3 get \
    --namespace <namespace_id> \
    --sink-name <sink_name>
```

The following modifiers control the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

#### --sink-name

Provide the name of the export sink you wish to retrieve details for.

_Required modifier_

### delete

The `tcld namespace export s3 delete` command allows users to delete an existing export sink from the Namespace of a
Temporal Cloud account.

**Example**

```bash
tcld namespace export s3 delete \
    --namespace <namespace_id> \
    --sink-name <sink_name>
```

The following modifiers control the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

#### --sink-name

Provide the name of the export sink you wish to delete.

_Required modifier_

#### --resource-version

Specify a resource version (ETag) to delete from. If not specified, the CLI will use the latest version.

Alias: `-v`

#### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request
identifier.

Alias: `-r`

### list

The `tcld namespace export s3 list` command allows users to list all existing export sinks within the Namespace of a
Temporal Cloud account.

**Example**

```bash
tcld namespace export s3 list \
    --namespace <namespace_id>
```

The following modifiers control the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

#### --page-size

Determine the number of results to return per page for list operations. If not specified, the default value is 100.

#### --page-token

Provide the page token to continue listing results from where the previous list operation left off.

### update

The `tcld namespace export s3 update` command allows users to modify the details of an existing export sink within the
Namespace of a Temporal Cloud account.

**Example**

```bash
tcld namespace export s3 update \
    --namespace <namespace_id> \
    --sink-name <sink_name> \
    --enabled true
```

The following modifiers control the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

#### --sink-name

Provide the name of the export sink you wish to update.

_Required modifier_

#### --enabled

Specify whether the export is enabled or not.

#### --role-arn

Update the role ARN for the IAM Role.

#### --s3-bucket-name

Update the name of the AWS S3 bucket that Temporal will send closed workflow histories to.

#### --resource-version

Specify a resource version (ETag) to update from. If not specified, the CLI will use the latest version.

Alias: `-v`

#### --kms-arn

Update the ARN of the KMS key used for encryption. Note: If the KMS ARN needs to be added or updated, users should
create the IAM Role with KMS or modify the created IAM Role accordingly. Providing it as part of the input won't help.

#### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request
identifier.

Alias: `-r`

### validate

The `tcld namespace export s3 validate` command allows users to validate an export sink from the Namespace of a Temporal
Cloud account.

**Example**

```bash
tcld namespace export s3 validate \
    --namespace <namespace_id> \
    --sink-name <sink_name> \
    --s3-bucket-name <bucket_name> \
    --role-arn <role_arn>
```

The following modifiers control the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

#### --sink-name

Provide the name of the export sink you wish to retrieve details for.

_Required modifier_

#### --role-arn

Provide role arn for the IAM Role.

_Required modifier_

#### --s3-bucket-name

Update the name of the AWS S3 bucket that Temporal will send closed workflow histories to.

#### --kms-arn

Update the ARN of the KMS key used for encryption. Note: If the KMS ARN needs to be added or updated, users should
create the IAM Role with KMS or modify the created IAM Role accordingly. Providing it as part of the input won't help.

## accepted-client-ca

The `tcld namespace accepted-client-ca` commands manage the client CA certificates of the specified
[Namespace](/namespaces) in Temporal Cloud. The certificates are used to verify client connections.

:::note

Base64 versions of the CA certificate files are accepted by these commands.

:::

Alias: `ca`

- [tcld namespace accepted-client-ca add](#add)
- [tcld namespace accepted-client-ca list](#list)
- [tcld namespace accepted-client-ca set](#set)
- [tcld namespace accepted-client-ca remove](#remove)

:::important

Do not use a CA certificate that is signed with an insecure signature algorithm, such as SHA-1. Such signatures will be
rejected. Existing CA certificates that use SHA-1 can stop working without warning.

For more information about the vulnerabilities of SHA-1, see [SHAttered](https://shattered.io/).

:::

### add

The `tcld namespace accepted-client-ca add` command adds client CA certificates to a [Namespace](/namespaces) in
Temporal Cloud.

`tcld namespace accepted-client-ca add --ca-certificate <value>`

Alias: `a`

The following modifiers control the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

**Example**

```bash
tcld namespace accepted-client-ca add \
    --namespace <namespace_id> \
    --ca-certificate <encoded_certificate>
```

#### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request
identifier.

Alias: `-r`

**Example**

```bash
tcld namespace accepted-client-ca add \
    --request-id <request_id> \
    --ca-certificate <encoded_certificate>
```

#### --resource-version

Specify a resource version (ETag) to update from. If not specified, the latest version is used.

Alias: `-v`

**Example**

```bash
tcld namespace accepted-client-ca add \
    --resource-version <etag> \
    --ca-certificate <encoded_certificate>
```

#### --ca-certificate

_Required modifier unless `--ca-certificate-file` is specified_

Specify a base64-encoded string of a CA certificate PEM file.

If both `--ca-certificate` and `--ca-certificate-file` are specified, only `--ca-certificate` is used.

Alias: `-c`

**Example**

```bash
tcld namespace accepted-client-ca add \
    --ca-certificate <encoded_certificate>
```

#### --ca-certificate-file

_Required modifier unless `--ca-certificate` is specified_

Specify a path to a CA certificate PEM file.

If both `--ca-certificate` and `--ca-certificate-file` are specified, only `--ca-certificate` is used.

Alias: `-f`

**Example**

```bash
tcld namespace accepted-client-ca add \
    --ca-certificate-file <path>
```

### list

The `tcld namespace accepted-client-ca list` command lists the client CA certificates that are currently configured for
a [Namespace](/namespaces) in Temporal Cloud.

`tcld namespace accepted-client-ca list`

Alias: `l`

The following modifier controls the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

**Example**

```bash
tcld namespace accepted-client-ca list \
    --namespace <namespace_id>
```

### remove

The `tcld namespace accepted-client-ca remove` command removes client CA certificates from a [Namespace](/namespaces) in
Temporal Cloud.

`tcld namespace accepted-client-ca remove --ca-certificate <value>`

Alias: `r`

The following modifiers control the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

**Example**

```bash
tcld namespace accepted-client-ca remove \
    --namespace <namespace_id> \
    --ca-certificate <encoded_certificate>
```

#### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request
identifier.

Alias: `-r`

**Example**

```bash
tcld namespace accepted-client-ca remove \
    --request-id <request_id> \
    --ca-certificate <encoded_certificate>
```

#### --resource-version

Specify a resource version (ETag) to update from. If not specified, the latest version is used.

Alias: `-v`

**Example**

```bash
tcld namespace accepted-client-ca remove \
    --resource-version <etag> \
    --ca-certificate <encoded_certificate>
```

#### --ca-certificate

_Required modifier unless `--ca-certificate-fingerprint` or `--ca-certificate-file` is specified_

Specify the base64-encoded string of a CA certificate PEM file.

If `--ca-certificate-fingerprint` is also specified, both `--ca-certificate` and `--ca-certificate-file` are ignored.

If `--ca-certificate-file` is also specified but `--ca-certificate-fingerprint` is not, only `--ca-certificate` is used.

Alias: `-c`

**Example**

```bash
tcld namespace accepted-client-ca remove \
    --ca-certificate <encoded_certificate>
```

#### --ca-certificate-file

_Required modifier unless `--ca-certificate-fingerprint` or `--ca-certificate` is specified_

Specify a path to a CA certificate PEM file.

If `--ca-certificate-fingerprint` is also specified, both `--ca-certificate-file` and `--ca-certificate` are ignored.

If `--ca-certificate` is also specified but `--ca-certificate-fingerprint` is not, only `--ca-certificate` is used.

Alias: `-f`

**Example**

```bash
tcld namespace accepted-client-ca remove \
    --ca-certificate-file <path>
```

#### --ca-certificate-fingerprint

_Required modifier unless `--ca-certificate` or `--ca-certificate-file` is specified_

Specify the fingerprint of a CA certificate.

If `--ca-certificate`, `--ca-certificate-file`, or both are also specified, they are ignored.

Alias: `--fp`

**Example**

```bash
tcld namespace accepted-client-ca remove \
    --ca-certificate-fingerprint <fingerprint>
```

### set

The `tcld namespace accepted-client-ca set` command sets the client CA certificates for a [Namespace](/namespaces) in
Temporal Cloud.

`tcld namespace accepted-client-ca set --ca-certificate <value>`

Alias: `s`

{/* How to rollover accepted client CA certificates in Temporal Cloud using tcld */}

When updating CA certificates, it's important to follow a rollover process. Doing so enables your Namespace to serve
both CA certificates for a period of time until traffic to your old CA certificate ceases.

1. Create a single file that contains both your old and new CA certificate PEM blocks. Just concatenate the PEM blocks
   on adjacent lines.

   ```
   -----BEGIN CERTIFICATE-----
   ... old CA cert ...
   -----END CERTIFICATE-----
   -----BEGIN CERTIFICATE-----
   ... new CA cert ...
   -----END CERTIFICATE-----
   ```

1. Run the `tcld namespace accepted-client-ca set` command with the CA certificate bundle file.

   ```bash
   tcld namespace accepted-client-ca set \
       --ca-certificate-file <path>
   ```

1. Monitor traffic to your old certificate until it ceases.

1. Create another file that contains only the new CA certificate.

1. Run the `tcld namespace accepted-client-ca set` command again with the updated CA certificate bundle file.

The following modifiers control the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

**Example**

```bash
tcld namespace accepted-client-ca set \
    --namespace <namespace_id>
    --ca-certificate <encoded_certificate>
```

#### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request
identifier.

Alias: `-r`

**Example**

```bash
tcld namespace accepted-client-ca set \
    --request-id <request_id> \
    --ca-certificate <encoded_certificate>
```

#### --resource-version

Specify a resource version (ETag) to update from. If not specified, the latest version is used.

Alias: `-v`

**Example**

```bash
tcld namespace accepted-client-ca set \
    --resource-version <etag> \
    --ca-certificate <encoded_certificate>
```

#### --ca-certificate

_Required modifier unless `--ca-certificate-file` is specified_

Specify a base64-encoded string of a CA certificate PEM file.

If both `--ca-certificate` and `--ca-certificate-file` are specified, only `--ca-certificate` is used.

Alias: `-c`

**Example**

```bash
tcld namespace accepted-client-ca set \
    --ca-certificate <encoded_certificate>
```

#### --ca-certificate-file

_Required modifier unless `--ca-certificate` is specified_

Specify a path to a CA certificate PEM file.

If both `--ca-certificate` and `--ca-certificate-file` are specified, only `--ca-certificate` is used.

Alias: `-f`

**Example**

```bash
tcld namespace accepted-client-ca set \
    --ca-certificate-file <path>
```

## certificate-filters

The `tcld namespace certificate-filters` commands manage optional certificate filters for the specified
[Namespace](/namespaces) in Temporal Cloud. The Namespace can use certificate filters to authorize client certificates
based on distinguished name (DN) fields.

Alias: `cf`

- [tcld namespace certificate-filters import](#import)
- [tcld namespace certificate-filters export](#export)
- [tcld namespace certificate-filters clear](#clear)

### add

The `tcld namespace certificates-filter add` command adds additional certificate filters to the Namespace of a Temporal
Cloud account.

The following modifiers control the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

**Example**

```bash
tcld namespace certificate-filters add \
    --namespace <namespace_id> \
    --certificate-filter-file <file>
```

#### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request
identifier.

Alias: `-r`

**Example**

```bash
tcld namespace certificate-filters add \
    --request-id <request_id> \
    --certificate-filter-file <file>
```

#### --resource-version

Specify a resource version (ETag) to update from. If not specified, the latest version is used.

Alias: `-v`

**Example**

```bash
tcld namespace certificate-filters add \
    --resource-version <etag> \
    --certificate-filter-file <file>
```

#### --certificate-filter-file

_Required modifier unless `--certificate-filter-value` is specified._

Specify a path to a JSON file defining the certificate filters for the Namespace.

Aliases: `-f`, `--file`

**Example**

```bash
tcld namespace certificate-filters add \
    --certificate-filter-file <file>
```

#### --certificate-filter-input

_Required modifier unless `--certificate-filter-file` is specified._

The certificate filters, in JSON, that will be added to the Namespace.

Aliases: `-i`, `--input`

**Example**

```bash
tcld namespace certificate-filters add \
    --certificate-filter-input <JSON>
```

### clear

The `tcld namespace certificate-filters clear` command clears all certificate filters from a [Namespace](/namespaces) in
Temporal Cloud.

:::caution

Using this command allows _any_ client certificate that chains up to a configured CA certificate to connect to the
Namespace.

:::

`tcld namespace certificate-filters clear`

The following modifiers control the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

**Example**

```bash
tcld namespace certificate-filters clear \
    --namespace <namespace_id>
```

#### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request
identifier.

Alias: `-r`

**Example**

```bash
tcld namespace certificate-filters clear
    --request-id <request_id>
```

#### --resource-version

Specify a resource version (ETag) to update from. If not specified, the latest version is used.

Alias: `-v`

**Example**

```bash
tcld namespace certificate-filters clear \
    --resource-version <etag>
```

### export

The `tcld namespace certificate-filters export` command exports existing certificate filters from a
[Namespace](/namespaces) in Temporal Cloud.

`tcld namespace certificate-filters export --certificate-filter-file <path>`

Alias: `exp`

The following modifiers control the behavior of the command.

#### --certificate-filter-file

Specify a path to a JSON file where tcld can export the certificate filters.

Aliases: `--file`, `-f`

**Example**

```bash
tcld namespace certificate-filters export \
    --certificate-filter-file <path>
```

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

**Example**

```bash
tcld namespace certificate-filters import \
    --namespace <namespace_id> \
    --certificate-filter-input <json>
```

#### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request
identifier.

Alias: `-r`

**Example**

```bash
tcld namespace certificate-filters import \
    --request-id <request_id> \
    --certificate-filter-input <json>
```

#### --resource-version

Specify a resource version (ETag) to update from. If not specified, the latest version is used.

Alias: `-v`

**Example**

```bash
tcld namespace certificate-filters import \
    --resource-version <etag> \
    --certificate-filter-input <json>
```

### import

The `tcld namespace certificate-filters import` command sets certificate filters for a [Namespace](/namespaces) in
Temporal Cloud.

`tcld namespace certificate-filters import --certificate-filter-file <path>`

Alias: `imp`

A certificate filter can include any combination (and at least one) of the following:

- `commonName`
- `organization`
- `organizationalUnit`
- `subjectAlternativeName`

The following modifiers control the behavior of the command.

#### --certificate-filter-file

_Required modifier unless `--certificate-filter-input` is specified_

Specify a path to a JSON file that defines certificate filters to be applied to the Namespace, such as
`{ "filters": [ { "commonName": "test1" } ] }`. The specified filters replace any existing filters.

If both `--certificate-filter-file` and `--certificate-filter-input` are specified, the command returns an error.

Aliases: `--file`, `-f`

**Example**

```bash
tcld namespace certificate-filters import \
    --certificate-filter-file <path>
```

#### --certificate-filter-input

_Required modifier unless `--certificate-filter-file` is specified_

Specify a JSON string that defines certificate filters to be applied to the Namespace, such as
`{ "filters": [ { "commonName": "test1" } ] }`. The specified filters replace any existing filters.

If both `--certificate-filter-input` and `--certificate-filter-file` are specified, the command returns an error.

Aliases: `--input`, `-i`

**Example**

```bash
tcld namespace certificate-filters import \
    --certificate-filter-input <json>
```

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

**Example**

```bash
tcld namespace certificate-filters import \
    --namespace <namespace_id> \
    --certificate-filter-input <json>
```

#### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request
identifier.

Alias: `-r`

**Example**

```bash
tcld namespace certificate-filters import \
    --request-id <request_id> \
    --certificate-filter-input <json>
```

#### --resource-version

Specify a resource version (ETag) to update from. If not specified, the latest version is used.

Alias: `-v`

**Example**

```bash
tcld namespace certificate-filters import \
    --resource-version <etag> \
    --certificate-filter-input <json>
```

## search-attributes

The `tcld namespace search-attributes` commands manage [Search Attributes](/search-attribute) of the specified
[Namespace](/namespaces) in Temporal Cloud.

Alias: `sa`

- [tcld namespace search-attributes add](#add)
- [tcld namespace search-attributes rename](#rename)

If you wish to delete a Search Attribute, please contact [Support](/cloud/support) at
[support.temporal.io](https://support.temporal.io).

### add

The `tcld namespace search-attributes add` command adds custom [Search Attributes](/search-attribute) to a Namespace in
Temporal Cloud.

`tcld namespace search-attributes add --search-attribute <value>`

Alias: `a`

The following modifiers control the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

**Example**

```bash
tcld namespace search-attributes add \
    --namespace <namespace_id> \
    --search-attribute <value>
```

#### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request
identifier.

Alias: `-r`

**Example**

```bash
tcld namespace search-attributes add \
    --request-id <request_id> \
    --search-attribute <value>
```

#### --resource-version

Specify a resource version (ETag) to update from. If not specified, the latest version is used.

Alias: `-v`

**Example**

```bash
tcld namespace search-attributes add \
    --resource-version <etag> \
    --search-attribute <value>
```

#### --search-attribute

_Required modifier; can be specified more than once_

Specify a custom Search Attribute in the form "_name_=_type_". Valid values for _type_ are as follows:

- Bool
- Datetime
- Double
- Int
- Keyword
- Text

Alias: `--sa`

**Example**

```bash
tcld namespace search-attributes add \
    --search-attribute "YourSearchAttribute1=Text" \
    --search-attribute "YourSearchAttribute2=Double"
```

### rename

The `tcld namespace search-attributes rename` command renames a custom [Search Attribute](/search-attribute) in Temporal
Cloud.

`tcld namespace search-attributes rename --existing-name <value> --new-name <value>`

The following modifiers control the behavior of the command.

#### --namespace

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

**Example**

```bash
tcld namespace search-attributes rename \
    --namespace <namespace_id> \
    --existing-name <value> \
    --new-name <value>
```

#### --request-id

Specify a request identifier to use for the asynchronous operation. If not specified, the server assigns a request
identifier.

Alias: `-r`

**Example**

```bash
tcld namespace search-attributes rename \
    --request-id <request_id> \
    --existing-name <value> \
    --new-name <value>
```

#### --resource-version

Specify a resource version (ETag) to update from. If not specified, the latest version is used.

Alias: `-v`

**Example**

```bash
tcld namespace search-attributes rename \
    --resource-version <etag> \
    --existing-name <value> \
    --new-name <value>
```

#### --existing-name

_Required modifier_

Specify the name of an existing Search Attribute.

Alias: `--en`

**Example**

```bash
tcld namespace search-attributes rename \
    --existing-name <value> \
    --new-name <value>
```

#### --new-name

_Required modifier_

Specify a new name for the Search Attribute.

Alias: `--nn`

**Example**

```bash
tcld namespace search-attributes rename \
    --existing-name <value> \
    --new-name <value>
```

## retention

The `tcld namespace retention` commands manage the length of time (in days) a closed Workflow is preserved before
deletion for a given Namespace in Temporal Cloud.

Alias: `r`

- [tcld namespace retention get](#get)
- [tcld namespace retention set](#set)

### get

Retrieve the length of time (in days) a closed Workflow will be preserved before deletion for the specified Namespace.

Alias: `g`

The following modifier controls the behavior of the command.

#### --namespace

_Required modifier_

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

**Example**

```bash
tcld namespace retention get \
    --namespace <namespace_id>
```

### set

Set the length of time (in days) a closed Workflow will be preserved before deletion for the specified Namespace.

Alias: `s`

The following modifiers control the behavior of the command.

#### --namespace

_Required modifier_

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

#### --retention-days

_Required modifier_

Specify the number of days a closed Workflow will be preserved before deletion.

Alias: `--rd`

**Example**

```bash
tcld namespace retention set \
    --namespace <namespace_id> \
    --retention-days <retention_days>
```

## update-codec-server

The `tcld namespace update-codec-server` command updates the configuration of a codec server for Temporal Cloud, which
allows payloads to be decodec through a remote endpoint.

Alias: `ucs`

The following modifiers control the behavior of the command.

#### --namespace

_Required modifier._

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

**Example**

```bash
tcld namespace update-codec-server \
    --namespace <namespace_id> \
    --endpoint <http_url>
```

#### --endpoint

_Required modifier._

Specify an endpoint to decode payloads for all users interacting with this Namespace. Endpoints must be valid https
URLs.

Alias: `-e`

**Example**

```bash
tcld namespace update-codec-server \
    --namespace <namespace_id> \
    --endpoint <https_url>
```

#### --pass-access-token

Enables a user access token to be passed with the remote endpoint. This is set to `false` by default.

Alias: `--pat`

**Example**

```bash
tcld namespace update-codec-server \
    --namespace <namespace_id> \
    --endpoint <https_url> \
    --pass-access-token <bool>
```

#### --include-credentials

Enables the inclusion of cross-origin credentials. This is set to `false` by default.

Alias: `--ic`

**Example**

```bash
tcld namespace update-codec-server \
    --namespace <namespace_id> \
    --endpoint <https_url> \
    --include-credentials true
```

## update-high-availability {#update-high-availability}

The `tcld namespace update-high-availability` command enables you to adjust settings for your [Namespace](/namespaces)
with [High Availability features](/cloud/high-availability). This is set to `false` by default.

Alias: `uha`

The following modifiers control the behavior of the command.

#### --namespace

_Required modifier._

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

#### --disable-auto-failover

Specify whether Temporal Cloud should perform <ToolTipTerm term="health checks" src="health check" /> and trigger
automatic failovers.

Pass `true` or `false` (default).

**Example**

```
tcld namespace update-high-availability \
    --namespace <namespace_id> \
    --disable-auto-failover=true
```

When using API key authentication, add your API credentials before pressing Enter:

```
tcld --api-key <your_api_key> \
    namespace update-high-availability \
    --namespace <namespace_id> \
    --disable-auto-failover=true
```

Alias: `-daf`

## tags

The `tcld namespace tags` commands manage [Tags](/cloud/namespaces#tag-a-namespace) of the specified
[Namespace](/namespaces) in Temporal Cloud.

Alias: `t`

- [tcld namespace tags upsert](#upsert)
- [tcld namespace tags remove](#remove)

### upsert

Add new tags or update existing tag values for the specified Namespace.

Alias: `u`

The following modifier controls the behavior of the command.

#### --namespace

_Required modifier_

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

#### --request-id

The request identifier to use for the asynchronous operation. If not set, the server assigns an identifier.

Alias: `-r`

#### --tag

_Required modifier; can be specified more than once_

A tag in the form "_key_=_value_".

[Tag structure and limits](/cloud/namespaces#tag-structure-and-limits).

Alias: `--t`

**Example**

```bash
tcld namespace tags upsert \
    --namespace <namespace_id> \
    --tag "key1=value1" \
    --tag "key2=updated"
```

### remove

Remove existing tags for the specified Namespace using the key.

Alias: `rm`

The following modifiers control the behavior of the command.

#### --namespace

_Required modifier_

Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable
$TEMPORAL_CLOUD_NAMESPACE is used.

Alias: `-n`

#### --request-id

The request identifier to use for the asynchronous operation. If not set, the server assigns an identifier.

Alias: `-r`

#### --tag-key

_Required modifier; can be specified more than once_

A tag key string.

[Tag Key structure and limits](/cloud/namespaces#tag-structure-and-limits).

Alias: `--tk`

**Example**

```bash
tcld namespace tags remove \
    --namespace <namespace_id> \
    --tag-key "key1" \
    --tag-key "key2"
```

## set-connectivity-rules

The `tcld namespace set-connectivity-rules` command enables you to set connectivity rules on your
[Namespace](/namespaces).

Alias: `scrs`

#### --connectivity-rule-ids

The list of connectivity rule IDs, can be used in create namespace and update namespace. example: --ids id1 --ids id2
--ids id3.

Alias: `ids`

#### --namespace

The namespace hosted on temporal cloud.

Alias: `n`

#### --remove-all

Acknowledge that all connectivity rules will be removed, enabling connectivity from any source.

---

## tcld nexus command reference

The `tcld nexus` commands manage Nexus resources in Temporal Cloud.

Alias: `nxs`

- [tcld nexus endpoint](#endpoint)

## endpoint

The `tcld nexus endpoint` commands manage Nexus Endpoints in Temporal Cloud.

Alias: `ep`

- [tcld nexus endpoint allowed-namespace](#allowed-namespace)
- [tcld nexus endpoint create](#create)
- [tcld nexus endpoint delete](#delete)
- [tcld nexus endpoint get](#get)
- [tcld nexus endpoint list](#list)
- [tcld nexus endpoint update](#update)

### allowed-namespace

The `tcld nexus endpoint allowed-namespace` commands manage the allowed namespaces for a Nexus Endpoint.

Alias: `an`

- [tcld nexus endpoint allowed-namespace add](#add)
- [tcld nexus endpoint allowed-namespace list](#list)
- [tcld nexus endpoint allowed-namespace remove](#remove)
- [tcld nexus endpoint allowed-namespace set](#set)

#### add

The `tcld nexus endpoint allowed-namespace add` command adds allowed namespaces to a Nexus Endpoint.

Alias: `a`

##### --name

Endpoint name.

Alias: `n`

##### --namespace

Namespace that is allowed to call this endpoint.

Alias: `ns`

##### --request-id

The request-id to use for the asynchronous operation, if not set the server will assign one (optional).

Alias: `r`

##### --resource-version

The resource-version (etag) to update from, if not set the cli will use the latest (optional).

Alias: `v`

#### list

The `tcld nexus endpoint allowed-namespace list` command lists the allowed namespaces of a Nexus Endpoint.

Alias: `l`

##### --name

Endpoint name.

Alias: `n`

#### remove

The `tcld nexus endpoint allowed-namespace remove` command removes allowed namespaces from a Nexus Endpoint.

Alias: `r`

##### --name

Endpoint name.

Alias: `n`

##### --namespace

Namespace that is allowed to call this endpoint.

Alias: `ns`

##### --request-id

The request-id to use for the asynchronous operation, if not set the server will assign one (optional).

Alias: `r`

##### --resource-version

The resource-version (etag) to update from, if not set the cli will use the latest (optional).

Alias: `v`

#### set

The `tcld nexus endpoint allowed-namespace set` command sets the allowed namespaces of a Nexus Endpoint.

Alias: `s`

##### --name

Endpoint name.

Alias: `n`

##### --namespace

Namespace that is allowed to call this endpoint.

Alias: `ns`

##### --request-id

The request-id to use for the asynchronous operation, if not set the server will assign one (optional).

Alias: `r`

##### --resource-version

The resource-version (etag) to update from, if not set the cli will use the latest (optional).

Alias: `v`

### create

The `tcld nexus endpoint create` command creates a new Nexus Endpoint on the Cloud Account.
An endpoint name is used by 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.

Alias: `c`

#### --allow-namespace

Namespace that is allowed to call this endpoint (optional).

Alias: `ans`

#### --description

Endpoint description in markdown format (optional).

Alias: `d`

#### --description-file

Endpoint description file in markdown format (optional).

Alias: `df`

#### --name

Endpoint name.

Alias: `n`

#### --request-id

The request-id to use for the asynchronous operation, if not set the server will assign one (optional).

Alias: `r`

#### --target-namespace

Namespace in which a handler worker will be polling for Nexus tasks on.

Alias: `tns`

#### --target-task-queue

Task Queue in which a handler worker will be polling for Nexus tasks on.

Alias: `ttq`

### delete

The `tcld nexus endpoint delete` command deletes a Nexus Endpoint on the Cloud Account.
.

Alias: `d`

#### --name

Endpoint name.

Alias: `n`

#### --request-id

The request-id to use for the asynchronous operation, if not set the server will assign one (optional).

Alias: `r`

#### --resource-version

The resource-version (etag) to update from, if not set the cli will use the latest (optional).

Alias: `v`

### get

The `tcld nexus endpoint get` command gets a Nexus Endpoint configuration by name from the Cloud Account.

Alias: `g`

#### --name

Endpoint name.

Alias: `n`

### list

The `tcld nexus endpoint list` command lists all Nexus Endpoint configurations on the Cloud Account.

Alias: `l`

### update

The `tcld nexus endpoint update` command updates an existing Nexus Endpoint on the Cloud Account.
An endpoint name is used by 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.

Alias: `u`

#### --description

Endpoint description in markdown format (optional).

Alias: `d`

#### --description-file

Endpoint description file in markdown format (optional).

Alias: `df`

#### --name

Endpoint name.

Alias: `n`

#### --request-id

The request-id to use for the asynchronous operation, if not set the server will assign one (optional).

Alias: `r`

#### --resource-version

The resource-version (etag) to update from, if not set the cli will use the latest (optional).

Alias: `v`

#### --target-namespace

Namespace in which a handler worker will be polling for Nexus tasks on (optional).

Alias: `tns`

#### --target-task-queue

Task Queue in which a handler worker will be polling for Nexus tasks on (optional).

Alias: `ttq`

#### --unset-description

Unset endpoint description.

---

## tcld request command reference

The `tcld request` commands manage asynchronous requests in Temporal Cloud.

Alias: `r`

- [tcld request get](#get)

## get

The `tcld request get` command gets the status of the specified request in Temporal Cloud.

`tcld request get --request-id <request_id>`

Alias: `g`

The following modifiers control the behavior of the command.

#### --request

_Required modifier_

Specify a request identifier.

Alias: `-r`

**Example**

```bash
tcld request get --request-id <request_id>
```

---

## tcld user group command reference

The `tcld user-group` commands manage user groups in Temporal Cloud.

Alias: `ug`

- [tcld user-group add-users](#add-users)
- [tcld user-group create](#create)
- [tcld user-group delete](#delete)
- [tcld user-group get](#get)
- [tcld user-group list](#list)
- [tcld user-group list-members](#list-members)
- [tcld user-group remove-users](#remove-users)
- [tcld user-group set-access](#set-access)

## add-users

The `tcld user-group add-users` command adds users to the specified user group in Temporal Cloud.
You must set `--group-id` to specify the group to add users to.

Alias: `au`

The following flags control the behavior of the command.

#### --group-id (-id)

Specify the ID of the group to add users to.

#### --user-email (-e)

Specify the email of the user to add. This flag can be specified multiple times to add
multiple users in one command

## create

Creates a user group.

Alias: `c`

The following flags control the behavior of the command.

#### --display-name

The display name of the group.

#### --account-role

The account role that the group should have. One of `admin`, `read`, `developer`, `owner`, `financeadmin`, `none`.

#### --namespace-role (-nr)

Specifies a namespace role that the group should have. Can be repeated multiple times to add
multiple namespace roles to the group. Value is the form of `<namspaceid>-<role>` where the namspace ID is the full ID of the namespace and role is one of `admin`, `read`, or `write`. Example: `mynamespace.abc123-read` adds the read role for the `mynamespace.abc123` namespace.

## delete

Deletes the user group.

Alias: `d`

The following flags control the behavior of the command.

#### --group-id (-id)

Specify the ID of the group to delete.

## get

Gets the user group details.

Alias: `g`

The following flags control the behavior of the command.

#### --group-id (-id)

Specify the ID of the group to list.

## list

List the user groups in your Temporal Cloud account.

Alias: `l`

The following flags control the behavior of the command.

#### --page-size (-s)

The number of groups to list per page. Defaults to 10.

#### --page-token (-p)

The page token used when paginating through result pages.

## list-members

Lists all of the members of a group.

Alias: `lm`

The following flags control the behavior of the command.

#### --group-id (-id)

Specify the ID of the group to list.

## remove-users

Removes one or more users as members of the group.

Alias: `ru`

The following flags control the behavior of the command.

#### --group-id (-id)

Specify the ID of the group to remove users from.

#### --user-email (-e)

The email address of the user to remove from the group. This flag can be specified multiple times in order to remove multiple users with one command.

## set-access

This command sets the access roles that for a group. It follows the same conventions as the [create](#create) command by specifying an optional account role and 0 or more namespace roles.

Alias: `sa`

#### --group-id (-id)

Specify the ID of the group to set access.

#### --account-role

The account role that the group should have. One of `admin`, `read`, `developer`, `owner`, `financeadmin`, `none`.

#### --namespace-role (-nr)

Specifies a namespace role that the group should have. Can be repeated multiple times to add
multiple namespace roles to the group. Value is the form of `<namspaceid>-<role>` where the namspace ID is the full ID of the namespace and role is one of `admin`, `read`, or `write`. Example: `mynamespace.abc123-read` adds the read role for the `mynamespace.abc123` namespace.

#### --append (-a)

Will append namespace roles instead of replacing all existing roles already assigned. This allows namespace roles to be added without knowing what roles are already assigned to the group.

#### --remove (-r)

Will remove the given namespace roles instead of replacing all existing roles already assigned. This allows namespace roles to be removed without knowing what roles are already assigned to the group.

---

## tcld user command reference

The `tcld user` commands manage users in Temporal Cloud.

Alias: `u`

- [tcld user delete](#delete)
- [tcld user get](#get)
- [tcld user invite](#invite)
- [tcld user list](#list)
- [tcld user resend-invite](#resend-invite)
- [tcld user set-account-role](#set-account-role)
- [tcld user set-namespace-permissions](#set-namespace-permissions)

## delete

The `tcld user delete` command deletes the specified user in Temporal Cloud.
You must set either `--user-email` or `--user-id` to specify the user to be deleted.

Alias: `d`

The following modifiers control the behavior of the command.

#### --user-email

Specify the email address of the user to delete.

**Example**

```command
tcld user delete --user-email <test@example.com>
```

#### --user-id

Specify the user identifier of the user to delete.

**Example**

```command
tcld user delete --user-id <test-user-id>
```

#### --request-id

The request identifier to use for the asynchronous operation.

If not set, the server assigns an identifier.

Alias: `-r`

#### --resource-version

Specify a resource version (ETag) to update from.
If not specified, the latest version is used.

Alias: `-v`

## get

The `tcld user get` command gets information about the specified user in Temporal Cloud.
You must set either `--user-email` or `--user-id`.

Alias: `g`

The following modifiers control the behavior of the command.

#### --user-email

Specify the email address of the user to get information about.

**Example**

```command
tcld user delete --user-email <test@example.com>
```

#### --user-id

Specify the user identifier of the user to get information about.

**Example**

```command
tcld user delete --user-id <test-user-id>
```

## invite

The `tcld namespace invite` command invites the specified user to join Temporal Cloud.

Alias: `i`

The following modifiers control the behavior of the command.

#### --user-email

_Required modifier_

Specify the email address of the user to be invited.
You can supply this modifier multiple times to invite multiple users in a single request.

Alias: `-e`

#### --account-role

_Required modifier_

Specify the [account-level Role](/cloud/users#account-level-roles) for the invited user.

Available account roles: `admin` | `developer` | `read`.

Alias: `--ar`

#### --namespace-permission

Specify the [Namespace-level permissions](/cloud/users#namespace-level-permissions) for the invited user.
You can supply this modifier multiple times to set multiple Namespace permissions in a single request.

Each value must be in the format of `namespace=permission-type`.

Available namespace permissions: `Admin` | `Write` | `Read`.

Alias: `-p`

#### --request-id

The request identifier to use for the asynchronous operation.

If not set, the server assigns an identifier.

Alias: `-r`

```command
tcld user invite --user-email <test@example.com> --account-role developer --namespace-permission ns1=Admin --namespace-permission ns2=Write --request-id <123456>
```

## list

The `tcld user list` command returns a paginated list of users in Temporal Cloud.

Alias: `l`

**Example**

```command
tcld user list
```

The following modifiers control the behavior of the command.

#### --namespace

List users that have permissions to the Namespace.

Alias: `-n`

**Example**

```command
tcld user list --namespace <namespace_id>
```

#### --page-token

Page token for paging list users request.

Alias: `-p`

#### --page-size

Page size for paging list users request.

Defaults to 10.

Alias: `-s`

## resend-invite

The `tcld user resend-invite` command resends an invitation to the specified user in Temporal Cloud.
You must set either `--user-email` or `--user-id` to specify the user to receive another invitation.

Alias: `ri`

The following modifiers control the behavior of the command.

#### --user-email

Specify the email address of the user to resend an invitation to.

**Example**

```bash
tcld user resend-invite --user-email <test@example.com>
```

#### --user-id

Specify the user identifier of the user to resend an invitation to.

**Example**

```bash
tcld user resend-invite --user-id <test-user-id>
```

#### --request-id

The request identifier to use for the asynchronous operation.

If not set, the server assigns an identifier.

Alias: `-r`

## set-account-role

The `tcld user set-account-role` command sets an [account-level Role](/cloud/users#account-level-roles) for the specified user in Temporal Cloud.
You must set either `--user-email` or `--user-id`.

Alias: `ri`

The following modifiers control the behavior of the command.

#### --account-role

_Required modifier_

Specify the account-level Role to assign to the user.

Available account roles: `admin` | `developer` | `read`.

Alias: `-ar`

#### --user-email

Specify the email address of the user to assign an account-level Role to.

Alias: `-e`

**Example**

```command
tcld user set-account-role --user-email <test@example.com> --account-role Developer
```

#### --user-id

Specify the user identifier of the user to assign an account-level Role to.

Alias: `--id`

**Example**

```command
tcld user set-account-role --user-id <test-user-id> --account-role Developer
```

#### --request-id

The request identifier to use for the asynchronous operation.

If not set, the server assigns an identifier.

Alias: `-r`

#### --resource-version

Specify a resource version (ETag) to update from.
If not specified, the latest version is used.

Alias: `-v`

## set-namespace-permissions

The `tcld user set-namespace-permissions` command sets [Namespace-level permissions](/cloud/users#namespace-level-permissions) for a specified user in Temporal Cloud.
You must set either `--user-email` or `--user-id`.

Alias: `snp`

The following modifiers control the behavior of the command.

#### --user-email

Specify the email address of the user to assign Namespace-level permissions to.

**Example**

```command
tcld user set-namespace-permissions --user-email <test@example.com>
```

#### --user-id

Specify the user identifier of the user to assign Namespace-level permissions to.

**Example**

```command
tcld user set-namespace-permissions --user-id <test-user-id>
```

#### --request-id

The request identifier to use to assign Namespace-level permissions to.

If not set, the server assigns an identifier.

Alias: `-r`

#### --resource-version

Specify a resource version (ETag) to assign Namespace-level permissions to.
If not specified, the latest version is used.

Alias: `-v`

#### --namespace-permission

Specify the [Namespace-level permissions](/cloud/users#namespace-level-permissions) for the invited user.
You can supply this modifier multiple times to set multiple Namespace permissions in a single request.

Each value must be in the format of `namespace=permission-type`.

Available namespace permissions: `Admin` | `Write` | `Read`.

Alias: `-p`

---

## tcld version command reference

The `tcld version` command gets version information about tcld.

Alias: `v`

`tcld version`

The command has no modifiers.

---

## Temporal Cloud Terraform provider

The Terraform Temporal Cloud provider allows you to use Terraform to manage resources for Temporal Cloud. The Terraform
tool manages infrastructure as code (IaC). With this provider, you can use Terraform to automate Temporal Cloud resource
management, including Namespaces, Users, Service Accounts, API Keys and more.

:::note Terraform Management

Once a resource is managed by Terraform, you should only use Terraform to manage that resource.

:::

Resources:

- The [Temporal Cloud Terraform provider](https://registry.terraform.io/providers/temporalio/temporalcloud/latest) is
  available in the Terraform Registry, where you can find detailed documentation on the Provider's supported resources
  and data sources.
- The GitHub repository for the Terraform provider is
  [terraform-provider-temporalcloud](https://github.com/temporalio/terraform-provider-temporalcloud/tree/main), where
  you can report bugs, provide feature requests, and
  [contribute](https://github.com/temporalio/terraform-provider-temporalcloud/blob/main/CONTRIBUTING.md) to the
  provider. We encourage your input as we develop the provider with the community.
- To view the list of available Temporal Cloud resources supported by Terraform provider, visit the resources section of
  the Terraform documentation in Hashi's
  [registry](https://registry.terraform.io/providers/temporalio/temporalcloud/latest/docs).

### Prerequisites

To use the Terraform provider, you'll need the following:

- The [Terraform CLI](https://developer.hashicorp.com/terraform/cli)
- An [API Key](/cloud/api-keys): an API Key is required to use the Terraform provider.
  - See [the API docs](https://docs.temporal.io/cloud/api-keys#generate-an-api-key) for instructions on generating an
    API Key.

:::note OpenTofu Registry

Our Terraform Provider is registered with [OpenTofu](https://opentofu.org), but that registration is not maintained or
managed by Temporal Technologies.

:::

## Setup

Generate an [API Key](https://docs.temporal.io/cloud/api-keys#generate-an-api-key) to authenticate Terraform operations
with your Temporal Cloud account or a Service Account. Then, either use an environment variable or pass the API Key into
the provider manually to manage your Temporal Cloud Terraform resources.

Follow these examples to use an environment variable to pass in your API Key to the provider.

<Tabs>
  <TabItem value="macos" label="macOS" default>
Export your environment variable for secure access to the API Keys.

```bash