tctl version-next workflow command reference

The tctl workflow commands enable Workflow Execution

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

operations.

Alias: w

• tctl workflow cancel
• tctl workflow count
• tctl workflow describe
• tctl workflow list
• tctl workflow query
• tctl workflow reset
• tctl workflow reset-batch
• tctl workflow scan
• tctl workflow show
• tctl workflow signal
• tctl workflow stack
• tctl workflow start
• tctl workflow terminate

cancel

The tctl workflow cancel command cancels a Workflow Execution

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

.

Canceling a running Workflow Execution records a WorkflowExecutionCancelRequested event in the History. A new command task will be scheduled. After cancellation, the Workflow Execution can perform cleanup work.

The use of the --query modifier (tctl workflow cancel --query) automatically starts a batch job that cancels Workflow Executions according to the List Filter provided.

tctl workflow cancel --query <value> <modifiers>

The following modifiers are supported and control the behavior of the command. Always include required modifiers when executing this command.

• --namespace
• --query
• --reason
• --yes

See also tctl workflow terminate.

count

The tctl workflow count command counts Workflow Executions

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

. This command requires Elasticsearch to be enabled.

tctl workflow count <modifiers>

The following modifier controls the behavior of the command.

• --query

Example

tctl workflow count --query 'ExecutionStatus="Running"'

delete

The tctl workflow delete command deletes a Workflow Execution

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

.

tctl workflow delete

The following modifiers are supported and control the behavior of the command. Always include required modifiers when executing this command.

• --namespace
• --run-id
• --workflow-id

describe

The tctl workflow describe command shows information about a Workflow Execution

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

. This information can be used to locate a failed Workflow Execution, for example.

tctl workflow describe <modifiers>

Alias: d

The following modifiers control the behavior of the command. Always include required modifiers when executing this command.

• --raw
• --reset-points-only
• --run-id
• --workflow-id

execute

The tctl workflow execute command starts a new Workflow Execution

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

and shows its progress until completion.

The command is entered in the following format:

tctl workflow execute [modifiers]

Single quotes ('') are used to wrap input as JSON.

The following modifiers are supported and control the behavior of the command. Always include required modifiers when executing this command.

• --cron
• --execution-timeout
• --fields
• --input
• --input-file
• --limit
• --max-field-length
• --memo-key
• --memo
• --memo-file
• --no-pager
• --output
• --pager
• --search-attribute-key
• --search-attribute-value
• --task-queue
• --task-timeout
• --time-format
• --type
• --workflow-id
• --workflow-id-reuse-policy

list

The tctl workflow list command lists open or closed Workflow Executions

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

.

By default, this command lists a maximum of 10 closed Workflow Executions.

• To set the number of items printed, use the --limit option.
• To specify fields to print, use the --fields option.
• To enable or disable a pager, use --pager <value> or --no-pager.

tctl workflow list <modifiers>

The following modifiers are supported and control the behavior of the command.

• --archived
• --fields
• --limit
• --no-pager
• --output
• --pager
• --query
• --time-format

Examples

List all Workflows with the given WorkflowId or RunId:

tctl workflow list \
  --query 'WorkflowType = "main.Workflow" and (WorkflowId = "1645a588-4772-4dab-b276-5f9db108b3a8" or RunId = "be66519b-5f09-40cd-b2e8-20e4106244dc")'

List all open Workflows that started at a given time:

tctl workflow list \
  --query 'WorkflowType = "main.Workflow" StartTime > "2019-06-07T16:46:34-08:00" and ExecutionStatus = "Running"'

query

The tctl workflow query command sends a Query

What is a Query?

A Query is a synchronous operation that is used to report the state of a Workflow Execution.

Learn more

to a Workflow Execution

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

.

Queries can be used to retrieve all or part of the Workflow state with given parameters.

$ tctl workflow query --workflow-id "HelloQuery" --query-type "getCount"
Query result as JSON:
3

Queries can also be used on completed Workflows. Let's complete a Workflow by updating its greeting, and then query the now-finished Workflow.

$ tctl workflow signal --workflow-id "HelloQuery" --name "updateGreeting" --input \"Bye\"
Signal workflow succeeded.
$ tctl workflow query --workflow-id "HelloQuery" --query-type "getCount"
Query result as JSON:
4

Queries are written as follows:

tctl workflow query --workflow-id [modifiers]

The following modifiers control the behavior of the command. Always include required modifiers when executing this command.

• --input
• --input-file
• --query-reject-condition
• --query-type
• --run-id
• --workflow-id

reset

The tctl workflow reset command resets a Workflow Execution

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

by either eventIdor resetType.

Resetting a Workflow allows the process to be resumed from a certain point without losing your parameters or Event History.

tctl workflow reset <modifiers>

The following modifiers control the behavior of the command.

• --event-id
• --reason
• --reset-type
• --reset-reapply-type
• --reset-bad-binary-checksum
• --run-id
• --workflow-id

reset-batch

The tctl workflow reset-batch command resets a batch of Workflow Executions

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

by resetType.

Resetting a Workflow allows the process to be resumed from a certain point without losing your parameters or Event History.

tctl workflow reset-batch <modifiers>

The following modifiers control the behavior of the command.

• --dry-run
• --exclude-file
• --input-file
• --input-parallelism
• --non-deterministic
• --query
• --reason
• --reset-bad-binary-checksum
• --reset-type
• --skip-current-open
• --skip-base-not-current

scan

The tctl workflow scan command lists Workflow Executions

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

.

By default, this command lists a maximum of 2000 Workflow Executions. To set the size of a page, use the --pagesize option.

See also tctl workflow list.

tctl workflow scan <modifiers>

The following modifiers control the behavior of the command.

• --fields
• --limit
• --no-pager
• --output
• --pager
• --query
• --time-format

show

The tctl workflow show command shows the Event History

What is an Event History?

An append log of Events that represents the full state a Workflow Execution.

Learn more

for the specified Workflow Execution

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

.

tctl workflow show <modifiers>

The following modifiers control the behavior of the command.

• --fields
• --follow
• --limit
• --max-field-length
• --no-pager
• --output
• --output-filename
• --pager
• --reset-points-only
• --run-id
• --time-format
• --workflow-id

signal

The tctl workflow signal command Signals

What is a Signal?

A Signal is an asynchronous request to a Workflow Execution.

Learn more

a Workflow Execution

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

.

The use of the --query modifier (tctl workflow signal --query ...) starts a batch job that sends a Signal to the Workflow Executions according to the List Filter provided.

tctl workflow signal --query <value> <modifiers>

The following modifiers are supported and control the behavior of the command. Always include required modifiers when executing this command.

• --namespace
• --name
• --input
• --query
• --reason
• --yes

stack

The tctl workflow stack command queries Workflow Execution

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

with --stack-trace as the query type.

tctl workflow stack <modifiers>

The following modifiers control the behavior of the command.

• --input
• --input-file
• --query-reject-condition
• --run-id
• --workflow-id

start

The tctl workflow start command starts a new Workflow Execution

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

. This command returns the Workflow Id and Run Id immediately after starting the Workflow.

tctl workflow start <modifiers>

The following modifiers control the behavior of the command. Always include required modifiers when executing this command.

• --cron
• --execution-timeout
• --fields
• --input
• --input-file
• --limit
• --max-field-length
• --memo-key
• --memo
• --memo-file
• --no-pager
• --output
• --pager
• --run-timeout
• --search-attribute-key
• --search-attribute-value
• --task-queue
• --task-timeout
• --time-format
• --type
• --workflow-id
• --workflow-task-timeout
• --workflow-id-reuse-policy

terminate

The tctl workflow terminate command terminates a Workflow Execution

What is a Workflow Execution?

A Temporal Workflow Execution is a durable, scalable, reliable, and reactive function execution. It is the main unit of execution of a Temporal Application.

Learn more

.

Terminating a running Workflow Execution records a WorkflowExecutionTerminated event as the closing event in the History. No more command tasks will be scheduled.

See also tctl workflow cancel.

The use of the --query modifier (tctl workflow terminate --query ...) automatically starts a batch job that Terminates Workflow Executions according to the List Filter provided.

tctl workflow terminate --query <value> <modifiers>

The following modifiers are supported and control the behavior of the command. Always include required modifiers when executing this command.

• --namespace
• --query
• --reason
• --yes