tctl v1.17 namespace command reference
The tctl namespace commands enable Namespace
What is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more operations.
Alias: n
- tctl namespace describetctl namespace describe
How to describe a Namespace using tctl.
Learn more - tctl namespace listtctl namespace list
How to list all Namespaces using tctl.
Learn more - tctl namespace registertctl namespace register
How to register a Namespace using tctl.
Learn more - tctl namespace updatetctl namespace update
How to update a Namespace using tctl.
Learn more
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 NamespacesWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more.
tctl namespace list
The command has no modifiers.
register
The tctl namespace register command registers a NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more.
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 ClusterWhat is a Temporal Cluster?
A Temporal Cluster is the Temporal Server paired with persistence.
Learn more when registering a NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more.
This value changes for Global Namespaces when a failover occurs.
Example
tctl namespace register --active_cluster <name>
--clusters
Specify a list of Temporal ClustersWhat is a Temporal Cluster?
A Temporal Cluster is the Temporal Server paired with persistence.
Learn more when registering a NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more.
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 NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more.
Example
tctl namespace register --description <value>
--global_namespace
Specifies whether a NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more 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 ArchivalWhat is Archival?
Archival is a feature that automatically backs up Event Histories from Temporal Cluster persistence to a custom blob store after the Closed Workflow Execution retention period is reached.
Learn more.
Valid values are disabled and enabled.
Example
tctl namespace register --history_archival_state <value>
--history_uri
Specify the URI for ArchivalWhat is Archival?
Archival is a feature that automatically backs up Event Histories from Temporal Cluster persistence to a custom blob store after the Closed Workflow Execution retention period is reached.
Learn more.
The URI cannot be changed after Archival is first enabled.
Example
tctl namespace register --history_uri <uri>
--namespace_data
Specify data for a NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more 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 NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more owner.
Example
tctl namespace register --owner_email <value>
--retention
Set the Retention Period for the NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more.
The Retention Period applies to Closed Workflow Executions.
Example
tctl namespace register --retention <value>
--visibility_archival_state
Set the visibility state for ArchivalWhat is Archival?
Archival is a feature that automatically backs up Event Histories from Temporal Cluster persistence to a custom blob store after the Closed Workflow Execution retention period is reached.
Learn more.
Valid values are disabled and enabled.
Example
tctl namespace register --visibility_archival_state <value>
--visibility_uri
Specify the visibility URI for ArchivalWhat is Archival?
Archival is a feature that automatically backs up Event Histories from Temporal Cluster persistence to a custom blob store after the Closed Workflow Execution retention period is reached.
Learn more.
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 NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more.
tctl namespace update
The following modifiers control the behavior of the command.
--active_cluster
Specify the name of the active Temporal ClusterWhat is a Temporal Cluster?
A Temporal Cluster is the Temporal Server paired with persistence.
Learn more when updating a NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more.
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 CommandsWhat is a Command?
A Command is a requested action issued by a Worker to the Temporal Cluster after a Workflow Task Execution completes.
Learn more to the given binary.
See also --remove_bad_binary.
Example
tctl namespace update --add_bad_binary <value>
--clusters
Specify a list of Temporal ClustersWhat is a Temporal Cluster?
A Temporal Cluster is the Temporal Server paired with persistence.
Learn more when updating a NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more.
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 NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more.
Example
tctl namespace update --description <value>
--history_archival_state
Set the state of ArchivalWhat is Archival?
Archival is a feature that automatically backs up Event Histories from Temporal Cluster persistence to a custom blob store after the Closed Workflow Execution retention period is reached.
Learn more.
Valid values are disabled and enabled.
Example
tctl namespace update --history_archival_state <value>
--history_uri
Specify the URI for URI for ArchivalWhat is Archival?
Archival is a feature that automatically backs up Event Histories from Temporal Cluster persistence to a custom blob store after the Closed Workflow Execution retention period is reached.
Learn more.
The URI cannot be changed after Archival is first enabled.
Example
tctl namespace update --history_uri <uri>
--namespace_data
Specify data for a NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more 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 NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more owner.
Example
tctl namespace update --owner_email <value>
--reason
Specify a reason for updating a NamespaceWhat is a Namespace?
A Namespace is a unit of isolation within the Temporal Platform
Learn more.
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 ArchivalWhat is Archival?
Archival is a feature that automatically backs up Event Histories from Temporal Cluster persistence to a custom blob store after the Closed Workflow Execution retention period is reached.
Learn more.
Valid values are disabled and enabled.
Example
tctl namespace update --visibility_archival_state <value>
--visibility_uri
Specify the visibility URI for ArchivalWhat is Archival?
Archival is a feature that automatically backs up Event Histories from Temporal Cluster persistence to a custom blob store after the Closed Workflow Execution retention period is reached.
Learn more.
The URI cannot be changed after Archival is first enabled.
Example
tctl namespace update --visibility_uri <uri>