tcld namespace command reference
The tcld namespace
commands enable Namespace operations in Temporal Cloud.
Alias: n
- tcld namespace add-region
- tcld namespace create
- tcld namespace delete
- tcld namespace failover
- tcld namespace get
- tcld namespace list
- tcld namespace export
- tcld namespace accepted-client-ca
- tcld namespace certificate-filters
- tcld namespace search-attributes
- tcld namespace retention
- tcld namespace update-codec-server
- tcld namespace update-high-availability
add-region
Use tcld namespace add-region
to add a replica to an existing Temporal Cloud Namespace.
Adding a replica upgrades the Namespace to High Availability features.
Once provisioned, High Availability features enable Temporal Cloud to start replicating Workflow Execution data from the primary to the replica and trigger failover during adverse conditions.
Alias: none
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
Specify a Namespace hosted on Temporal Cloud.
If not specified, the value of the environment variable $TEMPORAL_CLOUD_NAMESPACE
is used.
Alias: -n
Required modifier
--region
The region to add to the existing Namespace. See Regions for a list of supported regions.
- GCP Namespaces support Multi-region Replication but do not support Same-region Replication.
- The AWS
sa-east-1
region supports Same-region Replication but does not support Multi-region Replication. - You must select a region using the same Cloud provider for your replica as your primary.
Alias: --re
Required modifier
Example
tcld namespace add-region \
--namespace <namespace_id>.<account_id> \
--region <replica_region>
When using API key authentication, add your API credentials before pressing Enter:
tcld --api-key <your_api_key> \
add-region \
--namespace <namespace_id>.<account_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:
- Using the current region replicates to an isolation domain within your existing region.
- Using a different region (within the same continent) replicates across regions.
- You cannot create a Multi-region deployment on separate continents.
Temporal Cloud sends an email alert once your Namespace is ready for use.
--cloud-provider
The cloud provider of the region.
Default: aws (default: "aws")
create
The tcld namespace create
command creates a Temporal Namespace in Temporal Cloud.
Use it to create a standard Namespace or a Namespace with High Availability features.
Alias: c
tcld namespace create
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
--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
--namespace
Specify a Namespace hosted on Temporal Cloud. If not specified, the value of the environment variable $TEMPORAL_CLOUD_NAMESPACE is used.
Alias: -n
Required modifier
--region
The region to create the Namespace in.
- Supplying a single
--region
flags creates a standard Namespace. - Supplying two
--region
flags creates a Namespace that uses replication and failover for continued service availability in case of failures of incidents.
Example
tcld namespace create \
--namespace <namespace_id>.<account_id> \
--region <primary_region> [\]
[--region <replica_region>] // if adding replica
When using API key authentication, add your API credentials before pressing Enter:
tcld --api-key <your_api_key> \
namespace create \
--namespace <namespace_id>.<account_id> \
--region <primary_region> [\]
[--region <replica_region>] // if adding replica
When using High Availability features, specify the region code of the region where you want to create the replica as an argument to the --region
flag:
- Using the current region replicates to an isolation domain within your existing region. This enables Same-region replication.
- Using a different region (within the same continent) replicates across regions. This enables Multi-region replication.
Temporal Cloud sends an email alert once your Namespace is ready for use.
- GCP Namespaces support Multi-region Replication but do not support Same-region Replication.
- The AWS
sa-east-1
region supports Same-region Replication but does not support Multi-region Replication. - You must select a region using the same Cloud provider for your replica as your primary.
- You cannot create a Multi-region deployment on separate continents.
Alias: --re
Required modifier
--retention-days
The number of days that data about closed Workflow Executions will be retained (default: 30).
Alias: --rd
--ca-certificate-file
Required modifier unless --ca-certificate
is specified
A path to a CA certificate PEM file.
If both --ca-certificate
and --ca-certificate-file
are specified, only --ca-certificate
is used.
Alias: --cf
--certificate-filter-file
Required modifier unless --certificate-filter-input
is specified
Path to a JSON file that defines the certificate filters to be applied to the Namespace. The specified filters replace any existing filters.
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
Required modifier unless --certificate-filter-file
is specified
A JSON string that defines the certificate filters to be applied to the Namespace. The specified filters replace any existing filters.
Sample JSON: { "filters": [ { "commonName": "test1" } ] }
If both --certificate-filter-input
and --certificate-filter-file
are specified, the command returns an error.
Alias: --cfi
--search-attribute
Required modifier; can be specified more than once
A custom Search Attribute in the form _name_=_type_
.
Valid values for type: Bool
| Datetime
| Double
| Int
| Keyword
| Text
Alias: --sa
--user-namespace-permission
Can be specified more than once
A Namespace-level permission for a user in the form _email_=_permission_
.
Valid values for permission: Admin
| Write
| Read
Alias: -p
--endpoint
The codec server endpoint to decode payloads for all users interacting with this Namespace. Must be HTTPS.
Alias: -e
--pass-access-token
Pass the user access token to the remote endpoint (default: false).
Alias: --pat
--include-credentials
Include cross-origin credentials (default: false).
Alias: --ic
Example
tcld namespace create \
--namespace <namespace_id> \
--region us-west-2 \
--retention-days 60 \
--certificate-filter-input '{"filters": [{"commonName": "test1"}]}' \
--user-namespace-permission "user@example.com=Admin" \
--search-attribute "customer_id=Int" \
--search-attribute "customer_name=Text" \
--endpoint "https://test-codec-server.com" \
--pass-access-token \
--include-credentials
delete
The tcld namespace delete
command deletes the specified Namespace in Temporal Cloud.
Alias: d
tcld namespace delete
The following modifiers control the behavior of the command.
--namespace
Specify the Namespace hosted on Temporal Cloud to be deleted.
Alias: -n
Required modifier
--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
tcld namespace delete \
--namespace <namespace_id>
delete-region
Use tcld namespace delete-region
to remove a replica for an existing Temporal Cloud Namespace.
Removing a replica disables High Availability features.
Disabling replication by removing a region results in a mandatory 7-day waiting period before you can re-enable High Availability Namespace features.
Alias: none
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
Specify a Namespace hosted on Temporal Cloud.
If not specified, the value of the environment variable $TEMPORAL_CLOUD_NAMESPACE
is used.
Alias: -n
Required modifier