Temporal CLI command reference

The Temporal CLI, evolving from its precursor tctl, serves as a command-line interface that provides developers with direct access to a Temporal Cluster. It's a powerful tool for managing, monitoring, and debugging Temporal Applications. With the Temporal CLI, developers can start Workflows, Signal or cancel them, and Query Workflow state, directly from their terminal. This interface also facilitates administrative tasks such as Namespace management.

The CLI encapsulates complex operations into simpler command-line inputs, making it an indispensable component of a developer’s toolkit when working with the Temporal ecosystem. Its design philosophy emphasizes ease of use and efficiency, catering to both quick inspections and more complex batch operations, thereby streamlining the development and operational processes for durable applications.

note

When upgrading from tctl to Temporal CLI, make sure to update your environment variables and use updated commands. For details, see CLI release notes.

The Temporal CLI includes a distribution of a Temporal Cluster, comprised of the Temporal Server, SQLite persistence, and the Temporal Web UI.

Command set

• temporal activity
• temporal batch
• temporal env
• temporal operator
• temporal schedule
• temporal server
• temporal task-queue
• temporal workflow

Namespace registration

Namespaces are pre-registered at startup for immediate use. Customize pre-registered Namespaces with the following command:

temporal server start-dev --namespace foo --namespace bar

Register Namespaces with namespace create:

temporal operator namespace create foo

Enable or disable Temporal UI

By default, the Temporal UI starts with Temporal CLI. To disable the UI, use the --headless modifier:

temporal server start-dev --headless

Dynamic configuration

Advanced Temporal CLI configuration requires a dynamic configuration file.

To set values on the command line, use --dynamic-config-value KEY=JSON_VALUE. For example, enable the Search Attribute cache:

temporal server start-dev --dynamic-config-value system.forceSearchAttributesCacheRefreshOnRead=false

This setting makes created Search Attributes immediately available.

Environment variables

Configure system environment with Temporal CLI environmental variables. The following table lists and describes the environment variables you can set for Temporal CLI.

Variable	Definition	Client Option
TEMPORAL_ADDRESS	Host and port (formatted as host:port) for the Temporal Frontend Service.	--address
TEMPORAL_CODEC_AUTH	Sets the authorization header for requests to Codec Server.	--codec-auth
TEMPORAL_CODEC_ENDPOINT	Endpoint for remote Codec Server.	--codec-endpoint
TEMPORAL_CONTEXT_TIMEOUT	Optional timeout for RPC call context (in seconds). Default: 5.	--context-timeout
TEMPORAL_NAMESPACE	Namespace in Temporal Workflow. Default: "default".	--namespace
TEMPORAL_TLS_CA	Path to server CA certificate.	--tls-ca-path
TEMPORAL_TLS_CERT	Path to x509 certificate.	--tls-cert-path
TEMPORAL_TLS_DISABLE_HOST_VERIFICATION	Disables TLS host name verification. Default: false.	--tls-disable-host-verification
TEMPORAL_TLS_KEY	Path to private certificate key.	--tls-key-path
TEMPORAL_TLS_SERVER_NAME	Override for target TLS server name.	--tls-server-name

Proxy support

Temporal CLI provides support for users who are operating behind a proxy. This feature ensures seamless communication even in network-restricted environments.

Setting up proxy support

If you are behind a proxy, you'll need to instruct the Temporal CLI to route its requests via that proxy. You can achieve this by setting the HTTPS_PROXY environment variable.

export HTTPS_PROXY=<host>:<port>

Replace <host> with the proxy's hostname or IP address, and <port> with the proxy's port number.

Once set, you can run the Temporal CLI commands as you normally would.

note

Temporal CLI uses the gRPC library which natively supports HTTP CONNECT proxies. The gRPC library checks for the HTTPS_PROXY (and its case-insensitive variants) environment variable to determine if it should route requests through a proxy.

In addition to HTTPS_PROXY, gRPC also respects the NO_PROXY environment variable. This can be useful if there are specific addresses or domains you wish to exclude from proxying.

For more information, see Proxy in the gRPC documentation.

Auto-completion

Enable auto-completion using the following commands.

zsh auto-completion

Add the following code snippet to your ~/.zshrc file:

source <(temporal completion zsh)

If you're running auto-completion from the terminal, run the following command:

echo 'source <(temporal completion zsh)' >> ~/.zshrc

After setting the variable, run the following command:

source ~/.zshrc.

Bash auto-completion

Install bash-completion and add the software to ~/.bash_profile.

To use aliases, add them to ~/.bash_profile as needed.

alias t='temporal'
alias tw='temporal workflow'
alias ts='temporal server start-dev'
alias tsdb='temporal server start-dev --db-filename ~/temporal.db'

# send process to background so you can continue using the terminal
alias tsbg='temporal server start-dev &> /dev/null & disown'

Install the Temporal CLI

How to download and install the Temporal CLI

The Temporal CLI is available on MacOS, Windows, and Linux.

MacOS

How to install the Temporal CLI on Mac OS

Choose one of the following install methods to install the Temporal CLI on MacOS:

• Install the Temporal CLI with Homebrew.

brew install temporal

• Install the Temporal CLI with cURL.

curl -sSf https://temporal.download/cli.sh | sh

• Install the Temporal CLI from CDN.

  1. Select the platform and architecture needed.

  • Download for Darwin amd64: https://temporal.download/cli/archive/latest?platform=darwin&arch=amd64

  • Download for Darwin arm64: https://temporal.download/cli/archive/latest?platform=darwin&arch=arm64

  2. Extract the downloaded archive.

  3. Add the temporal binary to your PATH.

Linux

How to install the Temporal CLI on Linux

Choose one of the following install methods to install the Temporal CLI on Linux:

• Install the Temporal CLI with cURL.

curl -sSf https://temporal.download/cli.sh | sh

• Install the Temporal CLI from CDN.

  1. Select the platform and architecture needed.

  • Download for Linux amd64: https://temporal.download/cli/archive/latest?platform=linux&arch=amd64

  • Download for Linux arm64: https://temporal.download/cli/archive/latest?platform=linux&arch=arm64

  2. Extract the downloaded archive.

  3. Add the temporal binary to your PATH.

Windows

How to install the Temporal CLI on Windows

Choose one of the following methods to install the Temporal CLI on Windows:

• Install the Temporal CLI with Scoop

Run the following command to install Temporal CLI using Scoop on Windows:

scoop install temporal-cli

• Install the Temporal CLI from CDN.

  1. Select the platform and architecture needed and download the binary.

  • Download for Windows amd64: https://temporal.download/cli/archive/latest?platform=windows&arch=amd64

  • Download for Windows arm64: https://temporal.download/cli/archive/latest?platform=windows&arch=arm64

  2. Extract the downloaded archive.

  3. Add the temporal.exe binary to your PATH.

Temporal dev server

How to start the Temporal development server

To start the Temporal development server run the following command:

temporal server start-dev

This command automatically starts the Web UI, creates the default Namespace, and uses an in-memory database.

The Temporal Server should be available on localhost:7233 and the Temporal Web UI should be available at http://localhost:8233.

The in-memory SQLite database does not persist if you stop the dev server. Use the --db-filename option to specify a database file, persisting application state. This is helpful if you plan on stopping and re-starting the dev server.

temporal server start-dev --db-filename temporal.db

For the full list of dev server options use the --help flag:

temporal server start-dev --help

Common CLI operations

The following are some of the more common operations you can perform with the CLI.

Start a Workflow

In another terminal, use the following commands to interact with the Server. The following command starts a Workflow:

$ temporal workflow start \
  --task-queue hello-world \
  --type MyWorkflow \
  --workflow-id 123 \
  --input 456

Running execution:
  WorkflowId                                   123
  RunId       357074e4-0dd8-4c44-8367-d92536dd0943
  Type        MyWorkflow
  Namespace   default
  TaskQueue   hello-world
  Args        [456]

Shorthand options are available:

temporal workflow start -t hello-world --type MyWorkflow -w 123 -i 456

You can also list and describe Workflows:

$ temporal workflow list

  Status   WorkflowId     Name       StartTime
  Running         123  MyWorkflow  14 seconds ago

$ temporal workflow describe --workflow-id 123

{
  "executionConfig": {
    "taskQueue": {
      "name": "hello-world",
      "kind": "Normal"
    },
    "workflowExecutionTimeout": "0s",
    "workflowRunTimeout": "0s",
    "defaultWorkflowTaskTimeout": "10s"
  },
  "workflowExecutionInfo": {
    "execution": {
      "workflowId": "123",
      "runId": "357074e4-0dd8-4c44-8367-d92536dd0943"
    },
    "type": {
      "name": "MyWorkflow"
    },
    "startTime": "2023-04-15T06:42:31.191137Z",
    "status": "Running",
    "historyLength": "2",
    "executionTime": "2023-04-15T06:42:31.191137Z",
    "memo": {

    },
    "autoResetPoints": {

    },
    "stateTransitionCount": "1"
  },
  "pendingWorkflowTask": {
    "state": "Scheduled",
    "scheduledTime": "2023-04-15T06:42:31.191173Z",
    "originalScheduledTime": "2023-04-15T06:42:31.191173Z",
    "attempt": 1
  }
}

For more detailed output in JSON format, use the following command:

$ temporal workflow list --fields long --output json

[
  {
    "execution": {
      "workflow_id": "123",
      "run_id": "357074e4-0dd8-4c44-8367-d92536dd0943"
    },
    "type": {
      "name": "MyWorkflow"
    },
    "start_time": "2023-04-15T06:42:31.191137Z",
    "status": 1,
    "execution_time": "2023-04-15T06:42:31.191137Z",
    "memo": {},
    "task_queue": "hello-world"
  }
]

Filter out Workflows based on Workflow Type with jq:

$ temporal workflow list --fields long -o json | jq '.[].type.name'

"OtherWorkflow"
"MyWorkflow"
"MyWorkflow"

To count the number of Workflows, use the following command:

$ temporal workflow list --fields long -o json | jq '.[].type.name' | uniq -c

   1 "OtherWorkflow"
   2 "MyWorkflow"

To see the full range of Workflow-related commands, run temporal workflow or see the Temporal CLI workflow command reference.

For a full list of available commands, run temporal or see Available commands.

Customize your environment variables

To communicate with a different Server, like a production Namespace on Temporal Cloud:

1. Create an environment named prod.
2. Pass --env prod to commands, like temporal workflow list --env prod.

To create a new environment and set its properties:

temporal env set prod.namespace production.f45a2
temporal env set prod.address production.f45a2.tmprl.cloud:7233
temporal env set prod.tls-cert-path /temporal/certs/prod.pem
temporal env set prod.tls-key-path /temporal/certs/prod.key

Check your settings:

$ temporal env get prod

  address        production.f45a2.tmprl.cloud:7233
  namespace      production.f45a2
  tls-cert-path  /temporal/certs/prod.pem
  tls-key-path   /temporal/certs/prod.key

Run a command to test the connection:

$ temporal workflow list --env prod

For a full list of properties, use temporal env set -h.

$ temporal env set -h

OPTIONS:
   Client Options:

   --address value                          The host and port (formatted as host:port) for the Temporal Frontend Service. [$TEMPORAL_CLI_ADDRESS]
   --codec-auth value                       Sets the authorization header on requests to the Codec Server. [$TEMPORAL_CLI_CODEC_AUTH]
   --codec-endpoint value                   Endpoint for a remote Codec Server. [$TEMPORAL_CLI_CODEC_ENDPOINT]
   --context-timeout value                  An optional timeout for the context of an RPC call (in seconds). (default: 5) [$TEMPORAL_CONTEXT_TIMEOUT]
   --env value                              Name of the environment to read environmental variables from. (default: "default")
   --grpc-meta value [ --grpc-meta value ]  Contains gRPC metadata to send with requests (format: key=value). Values must be in a valid JSON format.
   --namespace value, -n value              Identifies a Namespace in the Temporal Workflow. (default: "default") [$TEMPORAL_CLI_NAMESPACE]
   --tls-ca-path value                      Path to server CA certificate. [$TEMPORAL_CLI_TLS_CA]
   --tls-cert-path value                    Path to x509 certificate. [$TEMPORAL_CLI_TLS_CERT]
   --tls-disable-host-verification          Disables TLS host name verification if already enabled. (default: false) [$TEMPORAL_CLI_TLS_DISABLE_HOST_VERIFICATION]
   --tls-key-path value                     Path to private certificate key. [$TEMPORAL_CLI_TLS_KEY]
   --tls-server-name value                  Provides an override for the target TLS server name. [$TEMPORAL_CLI_TLS_SERVER_NAME]

   Display Options:

   --color value  when to use color: auto, always, never. (default: "auto")