tctl v1.17 namespace command reference
The tctl command line utility has been deprecated and is no longer actively supported. We recommend transitioning to Temporal CLI for continued use and access to new features.
Thank you for being a valued part of the Temporal community.
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 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>