# tctl v1.17 namespace command reference

> Explore the newly available Temporal CLI, set to replace tctl upon its v1.0 release. Manage and update Namespaces efficiently using a variety of detailed commands.

> **ℹ️ Info:**
> tctl is deprecated
>
> The tctl command line utility has been deprecated and is no longer actively supported.
> We recommend transitioning to [Temporal CLI](/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](/namespaces) operations.

Alias: `n`

- [tctl namespace describe](#describe)
- [tctl namespace list](#list)
- [tctl namespace register](#register)
- [tctl namespace update](#update)

## describe

The `tctl namespace describe` command describes a [Namespace](/namespaces).

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

```bash
tctl namespace describe --namespace_id <id>
```

Example results for a [Global Namespace](/global-namespace)

```bash
$ 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](/namespaces).

`tctl namespace list`

The command has no modifiers.

## register

The `tctl namespace register` command registers a [Namespace](/namespaces).

`tctl namespace register`

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

```bash
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](/temporal-service) when registering a [Namespace](/namespaces).
This value changes for Global Namespaces when a failover occurs.

**Example**

```bash
tctl namespace register --active_cluster <name>
```

### --clusters

Specify a list of [Temporal Clusters](/temporal-service) when registering a [Namespace](/namespaces).

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

```bash
tctl namespace register --clusters <names>
```

### --description

Specify a description when registering a [Namespace](/namespaces).

**Example**

```bash
tctl namespace register --description <value>
```

### --global_namespace

Specifies whether a [Namespace](/namespaces) is a [Global Namespace](/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**

```bash
tctl namespace register --global_namespace <boolean>
```

### --history_archival_state

Set the state of [Archival](/temporal-service/archival).
Valid values are `disabled` and `enabled`.

**Example**

```bash
tctl namespace register --history_archival_state <value>
```

### --history_uri

Specify the URI for [Archival](/temporal-service/archival).
The URI cannot be changed after Archival is first enabled.

**Example**

```bash
tctl namespace register --history_uri <uri>
```

### --namespace_data

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

**Example**

```bash
tctl namespace register --namespace_data <data>
```

### --owner_email

Specify the email address of the [Namespace](/namespaces) owner.

**Example**

```bash
tctl namespace register --owner_email <value>
```

### --retention

Set the [Retention Period](/temporal-service/temporal-server#retention-period) for the [Namespace](/namespaces).

The Retention Period applies to Closed [Workflow Executions](/workflow-execution).

**Example**

```bash
tctl namespace register --retention <value>
```

### --visibility_archival_state

Set the visibility state for [Archival](/temporal-service/archival).
Valid values are `disabled` and `enabled`.

**Example**

```bash
tctl namespace register --visibility_archival_state <value>
```

### --visibility_uri

Specify the visibility URI for [Archival](/temporal-service/archival).
The URI cannot be changed after Archival is first enabled.

**Example**

```bash
tctl namespace register --visibility_uri <uri>
```

## update

The `tctl namespace update` command updates a [Namespace](/namespaces).

`tctl namespace update`

The following modifiers control the behavior of the command.

### --active_cluster

Specify the name of the active [Temporal Cluster](/temporal-service) when updating a [Namespace](/namespaces).

**Example**

```bash
tctl namespace update --active_cluster <name>
```

### --add_bad_binary

Add a binary checksum to use when resetting a [Workflow Execution](/workflow-execution).
Temporal will not dispatch any [Commands](/workflow-execution#command) to the given binary.

See also [`--remove_bad_binary`](#--remove_bad_binary).

**Example**

```bash
tctl namespace update --add_bad_binary <value>
```

### --clusters

Specify a list of [Temporal Clusters](/temporal-service) when updating a [Namespace](/namespaces).

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

```bash
tctl namespace update --clusters <names>
```

### --description

Specify a description when updating a [Namespace](/namespaces).

**Example**

```bash
tctl namespace update --description <value>
```

### --history_archival_state

Set the state of [Archival](/temporal-service/archival).
Valid values are `disabled` and `enabled`.

**Example**

```bash
tctl namespace update --history_archival_state <value>
```

### --history_uri

Specify the URI for [Archival](/temporal-service/archival).
The URI cannot be changed after Archival is first enabled.

**Example**

```bash
tctl namespace update --history_uri <uri>
```

### --namespace_data

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

**Example**

```bash
tctl namespace update --namespace_data <data>
```

### --owner_email

Specify the email address of the [Namespace](/namespaces) owner.

**Example**

```bash
tctl namespace update --owner_email <value>
```

### --reason

Specify a reason for updating a [Namespace](/namespaces).

**Example**

```bash
tctl namespace update --reason <value>
```

### --remove_bad_binary

Remove a binary checksum.

See also [`--add_bad_binary`](#--add_bad_binary).

**Example**

```bash
tctl namespace update --remove_bad_binary <value>
```

### --retention

Specify the number of days to retain [Workflow Executions](/workflow-execution).

**Example**

```bash
tctl namespace update --retention <value>
```

### --visibility_archival_state

Set the visibility state for [Archival](/temporal-service/archival).
Valid values are `disabled` and `enabled`.

**Example**

```bash
tctl namespace update --visibility_archival_state <value>
```

### --visibility_uri

Specify the visibility URI for [Archival](/temporal-service/archival).
The URI cannot be changed after Archival is first enabled.

**Example**

```bash
tctl namespace update --visibility_uri <uri>
```