tctl v1.17 namespace command reference

Temporal CLI is now available!

The new Temporal CLI is available for use.

tctl v1.17 can still be used with Temporal Server version 1.20 and is expected to be compatible with Temporal Server version 1.21.

tctl is expected to be fully deprecated by Temporal Server version 1.22

The tctl namespace commands enable Namespace 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

operations.

Alias: n

• tctl namespace describe 🔗
  x

  Link preview

  tctl namespace describe

  How to describe a Namespace using tctl.

  tctl cli reference
• tctl namespace list 🔗
  x

  Link preview

  tctl namespace list

  How to list all Namespaces using tctl.

  tctl cli reference
• tctl namespace register 🔗
  x

  Link preview

  tctl namespace register

  How to register a Namespace using tctl.

  tctl cli reference
• tctl namespace update 🔗
  x

  Link preview

  tctl namespace update

  How to update a Namespace using tctl.

  tctl cli reference

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 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

.

tctl namespace list

The command has no modifiers.

register

The tctl namespace register command registers a Namespace 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

.

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 🔗

x

Link preview

What is a Temporal Cluster?

A Temporal Cluster is a Temporal Server paired with Persistence and Visibility stores.

term explanation

when registering a Namespace 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

. This value changes for Global Namespaces when a failover occurs.

Example

tctl namespace register --active_cluster <name>

--clusters

Specify a list of Temporal Clusters 🔗

x

Link preview

What is a Temporal Cluster?

A Temporal Cluster is a Temporal Server paired with Persistence and Visibility stores.

term explanation

when registering a Namespace 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

.

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 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

.

Example

tctl namespace register --description <value>

--global_namespace

Specifies whether a Namespace 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

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 🔗

x

Link preview

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

term explanation

. Valid values are disabled and enabled.

Example

tctl namespace register --history_archival_state <value>

--history_uri

Specify the URI for Archival 🔗

x

Link preview

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

term explanation

. The URI cannot be changed after Archival is first enabled.

Example

tctl namespace register --history_uri <uri>

--namespace_data

Specify data for a Namespace 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

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 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

owner.

Example

tctl namespace register --owner_email <value>

--retention

Set the Retention Period for the Namespace 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

.

The Retention Period applies to Closed Workflow Executions.

Example

tctl namespace register --retention <value>

--visibility_archival_state

Set the visibility state for Archival 🔗

x

Link preview

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

term explanation

. Valid values are disabled and enabled.

Example

tctl namespace register --visibility_archival_state <value>

--visibility_uri

Specify the visibility URI for Archival 🔗

x

Link preview

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

term explanation

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

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

.

tctl namespace update

The following modifiers control the behavior of the command.

--active_cluster

Specify the name of the active Temporal Cluster 🔗

x

Link preview

What is a Temporal Cluster?

A Temporal Cluster is a Temporal Server paired with Persistence and Visibility stores.

term explanation

when updating a Namespace 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

.

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 🔗

x

Link preview

What is a Command?

A Command is a requested action issued by a Worker to the Temporal Cluster after a Workflow Task Execution completes.

term explanation

to the given binary.

See also --remove_bad_binary.

Example

tctl namespace update --add_bad_binary <value>

--clusters

Specify a list of Temporal Clusters 🔗

x

Link preview

What is a Temporal Cluster?

A Temporal Cluster is a Temporal Server paired with Persistence and Visibility stores.

term explanation

when updating a Namespace 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

.

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 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

.

Example

tctl namespace update --description <value>

--history_archival_state

Set the state of Archival 🔗

x

Link preview

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

term explanation

. Valid values are disabled and enabled.

Example

tctl namespace update --history_archival_state <value>

--history_uri

Specify the URI for URI for Archival 🔗

x

Link preview

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

term explanation

. The URI cannot be changed after Archival is first enabled.

Example

tctl namespace update --history_uri <uri>

--namespace_data

Specify data for a Namespace 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

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 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

owner.

Example

tctl namespace update --owner_email <value>

--reason

Specify a reason for updating a Namespace 🔗

x

Link preview

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

term explanation

.

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 🔗

x

Link preview

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

term explanation

. Valid values are disabled and enabled.

Example

tctl namespace update --visibility_archival_state <value>

--visibility_uri

Specify the visibility URI for Archival 🔗

x

Link preview

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

term explanation

. The URI cannot be changed after Archival is first enabled.

Example

tctl namespace update --visibility_uri <uri>