Temporaltctl (CLI)
The Temporal CLI is a command-line tool you can use to perform various tasks on a Temporal server. It can perform namespace operations such as register, update, and describe as well as workflow operations like start workflow, show workflow history, and signal workflow.
Using the CLI
The Temporal CLI can be used directly from the Docker Hub image temporalio/tctl or by building the CLI tool locally.
Example of using the docker image to describe a namespace:
On Docker versions 18.03 and later, you may get a "connection refused" error. You can work around this by setting the host to "host.docker.internal" (see here for more info).
To build the CLI tool locally, clone the Temporal server repo and run
make bins. This produces an executable called tctl. With a local build, the same command to
describe a namespace would look like this:
The example commands below will use ./tctl for brevity.
Environment variables
Setting environment variables for repeated parameters can shorten the CLI commands.
- TEMPORAL_CLI_ADDRESS - host:port for Temporal frontend service, the default is for the local server
- TEMPORAL_CLI_NAMESPACE - default workflow namespace, so you don't need to specify
--namespace
Quick Start
Run ./tctl for help on top level commands and global options
Run ./tctl namespace for help on namespace operations
Run ./tctl workflow for help on workflow operations
Run ./tctl taskqueue for help on task queue operations
(./tctl help, ./tctl help [namespace|workflow] will also print help messages)
Note: make sure you have a Temporal server running before using CLI
Namespace operation examples
- Register a new namespace named "samples-namespace":
- View "samples-namespace" details:
Workflow operation examples
The following examples assume the TEMPORAL_CLI_NAMESPACE environment variable is set.
Run workflow
Start a workflow and see its progress. This command doesn't finish until workflow completes.
Brief explanation: To run a workflow, the user must specify the following:
- Task queue name (--tq)
- Workflow type (--wt)
- Execution start to close timeout in seconds (--et)
- Input in JSON format (--i) (optional)
example above uses this sample workflow
and takes a string as input with the -i '"temporal"' parameter. Single quotes ('') are used to wrap input as JSON.
Note: You need to start the worker so that the workflow can make progress.
(Run make && ./bin/helloworld -m worker in temporal-go-samples to start the worker)
Show running workers of a task queue
Start workflow
The workflow start command is similar to the run command, but immediately returns the workflow_id and
run_id after starting the workflow. Use the show command to view the workflow's history/progress.
Reuse the same workflow id when starting/running a workflow
Use option --workflowidreusepolicy or --wrp to configure the workflow id reuse policy.
Option 0 AllowDuplicateFailedOnly: Allow starting a workflow execution using the same workflow Id when a workflow with the same workflow Id is not already running and the last execution close state is one of [terminated, cancelled, timedout, failed].
Option 1 AllowDuplicate: Allow starting a workflow execution using the same workflow Id when a workflow with the same workflow Id is not already running.
Option 2 RejectDuplicate: Do not allow starting a workflow execution using the same workflow Id as a previous workflow.
Start a workflow with a memo
Memos are immutable key/value pairs that can be attached to a workflow run when starting the workflow. These are visible when listing workflows. More information on memos can be found here.
Show workflow history
Show workflow execution information
List closed or open workflow executions
Use --query to list workflows with SQL like query:
This will return all open workflows with workflowType as "main.SampleParentWorkflow".
Query workflow execution
Signal, cancel, terminate workflow
Terminating a running workflow execution will record a WorkflowExecutionTerminated event as the closing event in the history. No more decision tasks will be scheduled for a terminated workflow execution. Canceling a running workflow execution will record a WorkflowExecutionCancelRequested event in the history, and a new decision task will be scheduled. The workflow has a chance to do some clean up work after cancellation.
Signal, cancel, terminate workflows as a batch job
Batch job is based on List Workflow Query(--query). It supports signal, cancel and terminate as batch job type. For terminating workflows as batch job, it will terminte the children recursively.
Start a batch job(using signal as batch type):
You need to remember the JobId or use List command to get all your batch jobs:
Describe the progress of a batch job:
Terminate a batch job:
Note that the operation performed by a batch will not be rolled back by terminating the batch. However, you can use reset to rollback your workflows.
Restart, reset workflow
The Reset command allows resetting a workflow to a particular point and continue running from there. There are a lot of use cases:
- Rerun a failed workflow from the beginning with the same start parameters.
- Rerun a failed workflow from the failing point without losing the achieved progress(history).
- After deploying new code, reset an open workflow to let the workflow run to different flows.
You can reset to some predefined event types:
- FirstDecisionCompleted: reset to the beginning of the history.
- LastDecisionCompleted: reset to the end of the history.
- LastContinuedAsNew: reset to the end of the history for the previous run.
If you are familiar with the Temporal history event, You can also reset to any decision finish event by using:
Some things to note:
- When reset, a new run will be kicked off with the same workflowId. But if there is a running execution for the workflow(workflowId), the current run will be terminated.
- decision_finish_event_id is the Id of events of the type: DecisionTaskComplete/DecisionTaskFailed/DecisionTaskTimeout.
- To restart a workflow from the beginning, reset to the first decision task finish event.
To reset multiple workflows, you can use batch reset command:
Recovery from bad deployment -- auto-reset workflow
If a bad deployment lets a workflow run into a wrong state, you might want to reset the workflow to the point that the bad deployment started to run. But usually it is not easy to find out all the workflows impacted, and every reset point for each workflow. In this case, auto-reset will automatically reset all the workflows given a bad deployment identifier.
Let's get familiar with some concepts. Each deployment will have an identifier, we call it "Binary Checksum" as it is usually generated by the md5sum of a binary file. For a workflow, each binary checksum will be associated with an auto-reset point, which contains a runId, an eventID, and the created_time that binary/deployment made the first decision for the workflow.
To find out which binary checksum of the bad deployment to reset, you should be aware of at least one workflow running into a bad state. Use the describe command with --reset_points_only option to show all the reset points:
Then use this command to tell Temporal to auto-reset all workflows impacted by the bad deployment. The command will store the bad binary checksum into namespace info and trigger a process to reset all your workflows.
As you add the bad binary checksum to your namespace, Temporal will not dispatch any decision tasks to the bad binary. So make sure that you have rolled back to a good deployment(or roll out new bits with bug fixes). Otherwise your workflow can't make any progress after auto-reset.