tctl v1.17 command reference

note

This documentation reflects tctl version 1.17

The Temporal CLI (tctl) is a command-line tool that you can use to interact with a Temporal Cluster. It can perform NamespaceWhat is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

Learn more operations (such as register, update, and describe) and WorkflowWhat is a Workflow?

In day-to-day conversations, the term "Workflow" frequently denotes either a Workflow Type, a Workflow Definition, or a Workflow Execution.

Learn more operations (such as start Workflow, show Workflow History, and Signal Workflow).

• How to install tctlHow to install tctl
  
  You can install tctl in four ways, described in this topic.
  
  Learn more
• Environment variables for tctlEnvironment variables for tctl
  
  What are the environment variables for tctl?
  
  Learn more

tctl commands

• tctl activity
• tctl admin
• tctl batch
• tctl cluster
• tctl dataconverter
• tctl namespace
• tctl taskqueue
• tctl workflow

Install

The Temporal tctl documentation covers version 1.17 of the Temporal CLI.

You can install tctl in the following ways.

• Install locally by using Homebrew: brew install tctl
• Run locally together with Temporal Server in Docker Compose: docker exec temporal-admin-tools tctl YOUR COMMANDS HERE
  • To invoke tctl as though it is installed locally (such as tctl namespace describe), set an alias: alias tctl="docker exec temporal-admin-tools tctl"
• Run the temporal-admin-tools Docker image:
  • On Linux: docker run --rm -it --entrypoint tctl --network host --env TEMPORAL_CLI_ADDRESS=localhost:7233 temporalio/admin-tools:1.14.0
  • On macOS or Windows: docker run --rm -it --entrypoint tctl --env TEMPORAL_CLI_ADDRESS=host.docker.internal:7233 temporalio/admin-tools:1.14.0
  • If your Temporal Server is running on a remote host, change the value of TEMPORAL_CLI_ADDRESS.
  • To simplify command lines, create a tctl alias.
• Build it locally:
  1. Clone the Temporal Server repo.
  2. Run make tctl.
  3. Copy the tctl executable to any directory that appears in the PATH environment variable; for example, /usr/bin/.
• Install the latest version of the tctl in your GOPATH: go install github.com/temporalio/tctl/cmd/tctl@latest

Note: To use tctl, you must have a Temporal Server running.

To see help for tctl commands, enter the following commands.

Command	Description
tctl -h	Display help for top-level commands and global options
tctl namespace -h	Display help for NamespaceWhat is a Namespace? A Namespace is a unit of isolation within the Temporal Platform Learn more operations
tctl workflow -h	Display help for WorkflowWhat is a Workflow? In day-to-day conversations, the term "Workflow" frequently denotes either a Workflow Type, a Workflow Definition, or a Workflow Execution. Learn more operations
tctl taskqueue -h	Display help for Task QueueWhat is a Task Queue? A Task Queue is a first-in, first-out queue that a Worker Process polls for Tasks. Learn more operations

Global modifiers

You can supply the values for many of these modifiers by setting environment variablesEnvironment variables for tctl

What are the environment variables for tctl?

Learn more instead of including the modifiers in a tctl command.

--address

Specify a host and port for the Frontend Service. The default is 127.0.0.1:7233.

--auto_confirm

Automatically confirm all prompts.

--context_timeout

Specify a timeout for the context of an RPC call in seconds. The default value is 5.

--data_converter_plugin

Specify the name of the executable for a headers provider plugin.

--headers_provider_plugin

Specify the name of the executable for a custom Data Converter plugin.

--help

Display help for tctl in the CLI.

Alias: -h

--namespace

Specify a Namespace. By using this modifier, you don't need to specify a --namespace modifier for a sub-command. The default Namespace is default.

Alias: --n

--tls_ca_path

Specify the path to a server Certificate Authority (CA) certificate file.

--tls_cert_path

Specify the path to a public X.509 certificate file for mutual TLS authentication. If you use this modifier, you must also use the --tls_key_path modifier.

--tls_disable_host_verification

Disable verification of the server certificate (and thus host verification).

--tls_key_path

Specify the path to a private key file for mutual TLS authentication. If you use this modifier, you must also use the --tls_cert_path modifier.

--tls_server_name

Specify an override for the name of the target server that is used for TLS host verification. The name must be one of the DNS names listed in the server TLS certificate. Specifying this modifier also enables host verification.

--version

Display the version of tctl in the CLI.

--codec_endpoint

The URL and port number for a Codec Server.

Environment variables

Setting environment variables for repeated parameters can shorten tctl commands.

TEMPORAL_CLI_ADDRESS

Specify a host and port for the Frontend Service. The default is 127.0.0.1:7233.

TEMPORAL_CLI_AUTHORIZATION_TOKEN

Specify a token to be used by the HTTP Basic Authorization plugin.

TEMPORAL_CLI_AUTH

Specify the authorization header to be set for a gRPC request.

TEMPORAL_CLI_NAMESPACE

Specify a Namespace. By setting this variable, you don't need to specify a --namespace modifier in a tctl command. The default Namespace is default.

TEMPORAL_CLI_PLUGIN_DATA_CONVERTER

Specify the name of the executable for a custom Data Converter plugin.

TEMPORAL_CLI_PLUGIN_HEADERS_PROVIDER

Specify the name of the executable for a headers provider plugin.

TEMPORAL_CLI_TLS_CA

Specify the path to a server Certificate Authority (CA) certificate file.

TEMPORAL_CLI_TLS_CERT

Specify the path to a public X.509 certificate file for mutual TLS authentication.

TEMPORAL_CLI_TLS_DISABLE_HOST_VERIFICATION

Set to disable verification of the server certificate (and thus host verification).

TEMPORAL_CLI_TLS_KEY

Specify the path to a private key file for mutual TLS authentication. If you set this variable, you must also set the TEMPORAL_CLI_TLS_CERT variable.

TEMPORAL_CLI_TLS_SERVER_NAME

Specify an override for the name of the target server that is used for TLS host verification. The name must be one of the DNS names listed in the server TLS certificate. Setting this variable also enables host verification.

TEMPORAL_CONTEXT_TIMEOUT

Specify a timeout for the context of an RPC call in seconds. The default value is 5.