Temporal CLI operator command reference

cluster

Perform operator actions on Temporal Services (also known as Clusters).

temporal operator cluster [subcommand] [options]

For example to check Service/Cluster health:

temporal operator cluster health

describe

View information about a Temporal Cluster (Service), including Cluster Name, persistence store, and visibility store. Add --detail for additional info:

temporal operator cluster describe [--detail]

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--detail	No	bool Show history shard count and Cluster/Service version information.

health

View information about the health of a Temporal Service:

temporal operator cluster health

list

Print a list of remote Temporal Clusters (Services) registered to the local Service. Report details include the Cluster's name, ID, address, History Shard count, Failover version, and availability:

temporal operator cluster list [--limit max-count]

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--limit	No	int Maximum number of Clusters to display.

remove

Remove a registered remote Temporal Cluster (Service) from the local Service.

temporal operator cluster remove \
    --name YourClusterName

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--name	Yes	string Cluster/Service name.

system

Show Temporal Server information for Temporal Clusters (Service): Server version, scheduling support, and more. This information helps diagnose problems with the Temporal Server.

The command defaults to the local Service. Otherwise, use the --frontend-address option to specify a Cluster (Service) endpoint:

temporal operator cluster system \
    --frontend-address "YourRemoteEndpoint:YourRemotePort"

upsert

Add, remove, or update a registered ("remote") Temporal Cluster (Service).

temporal operator cluster upsert [options]

For example:

temporal operator cluster upsert \
    --frontend-address "YourRemoteEndpoint:YourRemotePort"
    --enable-connection false

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--enable-connection	No	bool Set the connection to "enabled".
--frontend-address	Yes	string Remote endpoint.

namespace

Manage Temporal Cluster (Service) Namespaces:

temporal operator namespace [command] [command options]

For example:

temporal operator namespace create \
    --namespace YourNewNamespaceName

create

Create a new Namespace on the Temporal Service:

temporal operator namespace create \
    --namespace YourNewNamespaceName \
    [options]

Create a Namespace with multi-region data replication:

temporal operator namespace create \
    --global \
    --namespace YourNewNamespaceName

Configure settings like retention and Visibility Archival State as needed. For example, the Visibility Archive can be set on a separate URI:

temporal operator namespace create \
    --retention 5d \
    --visibility-archival-state enabled \
    --visibility-uri YourURI \
    --namespace YourNewNamespaceName

Note: URI values for archival states can't be changed once enabled.

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--active-cluster	No	string Active Cluster (Service) name.
--cluster	No	string[] Cluster (Service) names for Namespace creation. Can be passed multiple times.
--data	No	string[] Namespace data as KEY=VALUE pairs. Keys must be identifiers, and values must be JSON values. For example: YourKey={"your": "value"} Can be passed multiple times.
--description	No	string Namespace description.
--email	No	string Owner email.
--global	No	bool Enable multi-region data replication.
--history-archival-state	No	string-enum History archival state. Accepted values: disabled, enabled.	disabled
--history-uri	No	string Archive history to this URI. Once enabled, can't be changed.
--retention	No	duration Time to preserve closed Workflows before deletion.	72h
--visibility-archival-state	No	string-enum Visibility archival state. Accepted values: disabled, enabled.	disabled
--visibility-uri	No	string Archive visibility data to this URI. Once enabled, can't be changed.

delete

Removes a Namespace from the Service.

temporal operator namespace delete [options]

For example:

temporal operator namespace delete \
    --namespace YourNamespaceName

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--yes, -y	No	bool Request confirmation before deletion.

describe

Provide long-form information about a Namespace identified by its ID or name:

temporal operator namespace describe \
    --namespace-id YourNamespaceId

or

temporal operator namespace describe \
    --namespace YourNamespaceName

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--namespace-id	No	string Namespace ID.

list

Display a detailed listing for all Namespaces on the Service:

temporal operator namespace list

update

Update a Namespace using properties you specify.

temporal operator namespace update [options]

Assign a Namespace's active Cluster (Service):

temporal operator namespace update \
    --namespace YourNamespaceName \
    --active-cluster NewActiveCluster

Promote a Namespace for multi-region data replication:

temporal operator namespace update \
    --namespace YourNamespaceName \
    --promote-global

You may update archives that were previously enabled or disabled. Note: URI values for archival states can't be changed once enabled.

temporal operator namespace update \
    --namespace YourNamespaceName \
    --history-archival-state enabled \
    --visibility-archival-state disabled

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--active-cluster	No	string Active Cluster (Service) name.
--cluster	No	string[] Cluster (Service) names.
--data	No	string[] Namespace data as KEY=VALUE pairs. Keys must be identifiers, and values must be JSON values. For example: YourKey={"your": "value"} Can be passed multiple times.
--description	No	string Namespace description.
--email	No	string Owner email.
--history-archival-state	No	string-enum History archival state. Accepted values: disabled, enabled.
--history-uri	No	string Archive history to this URI. Once enabled, can't be changed.
--promote-global	No	bool Enable multi-region data replication.
--replication-state	No	string-enum Replication state. Accepted values: normal, handover.
--retention	No	duration Length of time a closed Workflow is preserved before deletion.
--visibility-archival-state	No	string-enum Visibility archival state. Accepted values: disabled, enabled.
--visibility-uri	No	string Archive visibility data to this URI. Once enabled, can't be changed.

nexus

These commands manage Nexus resources.

Nexus commands follow this syntax:

temporal operator nexus [command] [subcommand] [options]

endpoint

These commands manage Nexus Endpoints.

Nexus Endpoint commands follow this syntax:

temporal operator nexus endpoint [command] [options]

create

Create a Nexus Endpoint on the Server.

A Nexus Endpoint name is used in Workflow code to invoke Nexus Operations. The endpoint target may either be a Worker, in which case --target-namespace and --target-task-queue must both be provided, or an external URL, in which case --target-url must be provided.

This command will fail if an Endpoint with the same name is already registered.

temporal operator nexus endpoint create \
  --name your-endpoint \
  --target-namespace your-namespace \
  --target-task-queue your-task-queue \
  --description-file DESCRIPTION.md

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--description	No	string Nexus Endpoint description. You may use Markdown formatting in the Nexus Endpoint description.
--description-file	No	string Path to the Nexus Endpoint description file. The contents of the description file may use Markdown formatting.
--name	Yes	string Endpoint name.
--target-namespace	No	string Namespace where a handler Worker polls for Nexus tasks.
--target-task-queue	No	string Task Queue that a handler Worker polls for Nexus tasks.
--target-url	No	string An external Nexus Endpoint that receives forwarded Nexus requests. May be used as an alternative to --target-namespace and --target-task-queue. (Experimental)

delete

Delete a Nexus Endpoint from the Server.

temporal operator nexus endpoint delete --name your-endpoint

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--name	Yes	string Endpoint name.

get

Get a Nexus Endpoint by name from the Server.

temporal operator nexus endpoint get --name your-endpoint

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--name	Yes	string Endpoint name.

list

List all Nexus Endpoints on the Server.

temporal operator nexus endpoint list

update

Update an existing Nexus Endpoint on the Server.

A Nexus Endpoint name is used in Workflow code to invoke Nexus Operations. The Endpoint target may either be a Worker, in which case --target-namespace and --target-task-queue must both be provided, or an external URL, in which case --target-url must be provided.

The Endpoint is patched; existing fields for which flags are not provided are left as they were.

Update only the target task queue:

temporal operator nexus endpoint update \
  --name your-endpoint \
  --target-task-queue your-other-queue

Update only the description:

temporal operator nexus endpoint update \
  --name your-endpoint \
  --description-file DESCRIPTION.md

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--description	No	string Nexus Endpoint description. You may use Markdown formatting in the Nexus Endpoint description.
--description-file	No	string Path to the Nexus Endpoint description file. The contents of the description file may use Markdown formatting.
--name	Yes	string Endpoint name.
--target-namespace	No	string Namespace where a handler Worker polls for Nexus tasks.
--target-task-queue	No	string Task Queue that a handler Worker polls for Nexus tasks.
--target-url	No	string An external Nexus Endpoint that receives forwarded Nexus requests. May be used as an alternative to --target-namespace and --target-task-queue. (Experimental)
--unset-description	No	bool Unset the description.

search-attribute

Create, list, or remove Search Attributes fields stored in a Workflow Execution's metadata:

temporal operator search-attribute create \
    --name YourAttributeName \
    --type Keyword

Supported types include: Text, Keyword, Int, Double, Bool, Datetime, and KeywordList.

If you wish to delete a Search Attribute, please contact support at https://support.temporal.io.

create

Add one or more custom Search Attributes:

temporal operator search-attribute create \
    --name YourAttributeName \
    --type Keyword

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--name	Yes	string[] Search Attribute name.
--type	Yes	string-enum[] Search Attribute type. Accepted values: Text, Keyword, Int, Double, Bool, Datetime, KeywordList.

list

Display a list of active Search Attributes that can be assigned or used with Workflow Queries. You can manage this list and add attributes as needed:

temporal operator search-attribute list

remove

Remove custom Search Attributes from the options that can be assigned or used with Workflow Queries.

temporal operator search-attribute remove \
    --name YourAttributeName

Remove attributes without confirmation:

temporal operator search-attribute remove \
    --name YourAttributeName \
    --yes

Use the following options to change the behavior of this command.

Flag	Required	Description	Default
--name	Yes	string[] Search Attribute name.
--yes, -y	No	bool Don't prompt to confirm removal.

Global Flags

The following options can be used with any command.

Flag	Required	Description	Default
--address	No	string Temporal Service gRPC endpoint.	localhost:7233
--api-key	No	string API key for request.
--client-authority	No	string Temporal gRPC client :authority pseudoheader.
--client-connect-timeout	No	duration The client connection timeout. 0s means no timeout.
--codec-auth	No	string Authorization header for Codec Server requests.
--codec-endpoint	No	string Remote Codec Server endpoint.
--codec-header	No	string[] HTTP headers for requests to codec server. Format as a KEY=VALUE pair. May be passed multiple times to set multiple headers.
--color	No	string-enum Output coloring. Accepted values: always, never, auto.	auto
--command-timeout	No	duration The command execution timeout. 0s means no timeout.
--config-file	No	string File path to read TOML config from, defaults to $CONFIG_PATH/temporal/temporal.toml where $CONFIG_PATH is defined as $HOME/.config on Unix, $HOME/Library/Application Support on macOS, and %AppData% on Windows. (Experimental)
--disable-config-env	No	bool If set, disables loading environment config from environment variables. (Experimental)
--disable-config-file	No	bool If set, disables loading environment config from config file. (Experimental)
--env	No	string Active environment name (ENV).	default
--env-file	No	string Path to environment settings file. Defaults to $HOME/.config/temporalio/temporal.yaml.
--grpc-meta	No	string[] HTTP headers for requests. Format as a KEY=VALUE pair. May be passed multiple times to set multiple headers. Can also be made available via environment variable as TEMPORAL_GRPC_META_[name].
--identity	No	string The identity of the user or client submitting this request. Defaults to "temporal-cli:$USER@$HOST".
--log-format	No	string-enum Log format. Accepted values: text, json.	text
--log-level	No	string-enum Log level. Default is "info" for most commands and "warn" for server start-dev. Accepted values: debug, info, warn, error, never.	info
--namespace, -n	No	string Temporal Service Namespace.	default
--no-json-shorthand-payloads	No	bool Raw payload output, even if the JSON option was used.
--output, -o	No	string-enum Non-logging data output format. Accepted values: text, json, jsonl, none.	text
--profile	No	string Profile to use for config file. (Experimental)
--time-format	No	string-enum Time format. Accepted values: relative, iso, raw.	relative
--tls	No	bool Enable base TLS encryption. Does not have additional options like mTLS or client certs. This is defaulted to true if api-key or any other TLS options are present. Use --tls=false to explicitly disable.
--tls-ca-data	No	string Data for server CA certificate. Can't be used with --tls-ca-path.
--tls-ca-path	No	string Path to server CA certificate. Can't be used with --tls-ca-data.
--tls-cert-data	No	string Data for x509 certificate. Can't be used with --tls-cert-path.
--tls-cert-path	No	string Path to x509 certificate. Can't be used with --tls-cert-data.
--tls-disable-host-verification	No	bool Disable TLS host-name verification.
--tls-key-data	No	string Private certificate key data. Can't be used with --tls-key-path.
--tls-key-path	No	string Path to x509 private key. Can't be used with --tls-key-data.
--tls-server-name	No	string Override target TLS server name.