Skip to main content

tctl v1.17 command reference

Temporal CLI is now available

The public preview of Temporal CLI is now available. We encourage you to begin using it and to provide feedback.

After the release of Temporal CLI v1.0, tctl will deprecate.

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 Namespace operations (such as register, update, and describe) and Workflow operations (such as start Workflow, show Workflow History, and Signal Workflow).

tctl commands​

How to install tctl​

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

CommandDescription
tctl -hDisplay help for top-level commands and global options
tctl namespace -hDisplay help for Namespace operations
tctl workflow -hDisplay help for Workflow operations
tctl taskqueue -hDisplay help for Task Queue operations

Global modifiers​

You can supply the values for many of these modifiers by setting environment variables 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 custom Data Converter plugin.

--headers_provider_plugin​

Specify the name of the executable for a headers provider 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.