Skip to main content

tcld namespace command reference

The tcld namespace commands enable Namespace operations in Temporal Cloud.

Alias: n

create

The tcld namespace create command creates a Temporal Namespace in Temporal Cloud.

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

Required modifier

Specify the name of the Namespace to create.

Alias: -n

--region

Required modifier

The region to create the Namespace in.

Valid options: ap-northeast-1 | ap-southeast-1 | ap-southeast-2 | ca-central-1 | eu-central-1 | eu-west-1 | eu-west-2 | us-east-1 | us-west-2

Alias: --re

--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

Required modifier

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

tcld namespace delete --namespace <namespace_id>

get

The tcld namespace get command gets information about the specified Namespace 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

tcld namespace get --namespace <namespace_id>

list

The tcld namespace list command lists all Namespaces in Temporal Cloud.

Alias: l

tcld namespace list

The command has no modifiers.

accepted-client-ca

The tcld namespace accepted-client-ca commands manage the client CA certificates of the specified Namespace 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

info

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.

add

The tcld namespace accepted-client-ca add command adds client CA certificates to a Namespace 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

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

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

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

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

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 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

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 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

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

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

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

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

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

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 in Temporal Cloud.

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

Alias: s

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-----
  2. Run the tcld namespace accepted-client-ca set command with the CA certificate bundle file.

    tcld namespace accepted-client-ca set --ca-certificate-file <path>
  3. Monitor traffic to your old certificate until it ceases.

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

  5. 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

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

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

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

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

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 in Temporal Cloud. The Namespace can use certificate filters to authorize client certificates based on distinguished name (DN) fields.

Alias: cf

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

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

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

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

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

tcld namespace certificate-filters add --certificate-filter-input <JSON>

clear

The tcld namespace certificate-filters clear command clears all certificate filters from a Namespace 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

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

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

tcld namespace certificate-filters clear --resource-version <etag>

export

The tcld namespace certificate-filters export command exports existing certificate filters from a Namespace 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

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

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

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

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 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

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

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

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

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

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

search-attributes

The tcld namespace search-attributes commands manage Search Attributes of the specified Namespace in Temporal Cloud.

Alias: sa

add

The tcld namespace search-attributes add command adds custom Search Attributes 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

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

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

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

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 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

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

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

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

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

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

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

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

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

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

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

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

tcld namespace update-codec-server --namespace <namespace_id> --endpoint <https_url> --include-credentials true