tctl next-version command reference

This documentation reflects the "next" version of Temporal's tctl command line tool. Currently it is known as tctl v2.0.0-beta, but the name may change in the future.

note

If you are using tctl version 1.16.12 or older, you must update to at least version 1.16.3 before you can switch to tctl v2.0.0-beta.1.

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

What is a Namespace?

A Namespace is a unit of isolation within the Temporal Platform

Learn more

operations (such as register, update, and describe) and Workflow

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

  How to install tctl

  You can install tctl in four ways, described in this topic.

  Learn more

• Environment variables for tctl

  Environment variables for tctl

  What are the environment variables for tctl?

  Learn more

Available commands

• tctl activity
• tctl alias
• tctl batch
• tctl cluster
• tctl data-converter
• tctl namespace
• tctl schedule
• `tctl search-attribute
• tctl task-queue
• tctl workflow

Install

Follow the steps in the tctl README to use the next version of tctl (currently tctl v2.0.0-beta).

Global modifiers

Global modifiers are provided after tctl in the command structure but before the commands themselves. For example:

tctl --address <value> workflow start --task-queue <value> ...

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

Environment variables for tctl

What are the environment variables for tctl?

Learn more

instead of including the modifiers in each tctl command.

--address

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

Alias: --ad

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

Alias: --ct

--data-converter-plugin

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

Alias: --dcp

--headers-provider-plugin

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

Alias: --hpp

--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: --ns

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

Alias: -v

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

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

TEMPORAL_CLI_AUTHORIZATION_TOKEN

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

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.