Skip to main content

tctl v1.17 namespace command reference

Temporal CLI is now available

The public preview of Temporal CLI is now available. We encourage you to begin using it and to provide feedback.

After the release of Temporal CLI v1.0, tctl will deprecate.

The tctl namespace commands enable Namespace operations.

Alias: n

describe

The tctl namespace describe command describes a Namespace.

tctl namespace describe

The following modifier controls the behavior of the command.

--namespace_id

Specify the ID of a Namespace to describe.

This modifier is required unless the global --namespace modifier is specified (tctl --namespace <name> describe).

Example

tctl namespace describe --namespace_id <id>

Example results for a Global Namespace

$ tctl --ns canary-namespace n desc
Name: canary-namespace
Description: testing namespace
OwnerEmail: dev@yourtech.io
NamespaceData:
Status: REGISTERED
RetentionInDays: 7
EmitMetrics: true
ActiveClusterName: dc1
Clusters: dc1, dc2

list

The tctl namespace list command lists all Namespaces.

tctl namespace list

The command has no modifiers.

register

The tctl namespace register command registers a Namespace.

tctl namespace register

By default, Temporal uses a "default" Namespace. Create and register a new Namespace with the following command:

tctl --namespace your-namespace namespace register
# OR using short alias
tctl --ns your-namespace n re

The following modifiers control the behavior of the command.

--active_cluster

Specify the name of the active Temporal Cluster when registering a Namespace. This value changes for Global Namespaces when a failover occurs.

Example

tctl namespace register --active_cluster <name>

--clusters

Specify a list of Temporal Clusters when registering a Namespace.

The list contains the names of Clusters (separated by spaces) to which the Namespace can fail over. Make sure to include to the currently active Cluster. This is a read-only setting and cannot be changed.

This modifier is valid only when the --global_namespace modifier is set to true.

Example

tctl namespace register --clusters <names>

--description

Specify a description when registering a Namespace.

Example

tctl namespace register --description <value>

--global_namespace

Specifies whether a Namespace is a Global Namespace. When enabled, it controls the creation of replication tasks on updates allowing the state to be replicated across Clusters. This is a read-only setting and cannot be changed.

Example

tctl namespace register --global_namespace <boolean>

--history_archival_state

Set the state of Archival. Valid values are disabled and enabled.

Example

tctl namespace register --history_archival_state <value>

--history_uri

Specify the URI for Archival. The URI cannot be changed after Archival is first enabled.

Example

tctl namespace register --history_uri <uri>

--namespace_data

Specify data for a Namespace in the form of key-value pairs (such as k1:v1,k2:v2,k3:v3).

Example

tctl namespace register --namespace_data <data>

--owner_email

Specify the email address of the Namespace owner.

Example

tctl namespace register --owner_email <value>

--retention

Set the Retention Period for the Namespace.

The Retention Period applies to Closed Workflow Executions.

Example

tctl namespace register --retention <value>

--visibility_archival_state

Set the visibility state for Archival. Valid values are disabled and enabled.

Example

tctl namespace register --visibility_archival_state <value>

--visibility_uri

Specify the visibility URI for Archival. The URI cannot be changed after Archival is first enabled.

Example

tctl namespace register --visibility_uri <uri>

update

The tctl namespace update command updates a Namespace.

tctl namespace update

The following modifiers control the behavior of the command.

--active_cluster

Specify the name of the active Temporal Cluster when updating a Namespace.

Example

tctl namespace update --active_cluster <name>

--add_bad_binary

Add a binary checksum to use when resetting a Workflow Execution. Temporal will not dispatch any Commands to the given binary.

See also --remove_bad_binary.

Example

tctl namespace update --add_bad_binary <value>

--clusters

Specify a list of Temporal Clusters when updating a Namespace.

The list contains the names of Clusters (separated by spaces) to which the Namespace can fail over.

This modifier is valid only when the --global_namespace modifier is set to true.

Example

tctl namespace update --clusters <names>

--description

Specify a description when updating a Namespace.

Example

tctl namespace update --description <value>

--history_archival_state

Set the state of Archival. Valid values are disabled and enabled.

Example

tctl namespace update --history_archival_state <value>

--history_uri

Specify the URI for URI for Archival. The URI cannot be changed after Archival is first enabled.

Example

tctl namespace update --history_uri <uri>

--namespace_data

Specify data for a Namespace in the form of key-value pairs (such as k1:v1,k2:v2,k3:v3).

Example

tctl namespace update --namespace_data <data>

--owner_email

Specify the email address of the Namespace owner.

Example

tctl namespace update --owner_email <value>

--reason

Specify a reason for updating a Namespace.

Example

tctl namespace update --reason <value>

--remove_bad_binary

Remove a binary checksum.

See also --add_bad_binary.

Example

tctl namespace update --remove_bad_binary <value>

--retention

Specify the number of days to retain Workflow Executions.

Example

tctl namespace update --retention <value>

--visibility_archival_state

Set the visibility state for Archival. Valid values are disabled and enabled.

Example

tctl namespace update --visibility_archival_state <value>

--visibility_uri

Specify the visibility URI for Archival. The URI cannot be changed after Archival is first enabled.

Example

tctl namespace update --visibility_uri <uri>