Skip to main content

tctl version-next workflow command reference

The tctl workflow commands enable Workflow Execution operations.

cancel​

The tctl workflow cancel command cancels a Workflow Execution.

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.

See also tctl workflow terminate.

count​

The tctl workflow count command counts Workflow Executions. This command requires Elasticsearch to be enabled.

tctl workflow count <modifiers>

The following modifier controls the behavior of the command.

Example

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

delete​

The tctl workflow delete command deletes a Workflow Execution.

tctl workflow delete

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

describe​

The tctl workflow describe command shows information about a Workflow Execution. This information can be used to locate a failed Workflow Execution, for example.

tctl workflow describe <modifiers>

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

execute​

The tctl workflow execute command starts a new Workflow Execution 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.

list​

The tctl workflow list command lists open or closed Workflow Executions.

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.

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 QueryLink preview iconWhat 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.

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.

reset​

The tctl workflow reset command resets a Workflow Execution 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.

reset-batch​

The tctl workflow reset-batch command resets a batch of Workflow Executions 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.

scan​

The tctl workflow scan command lists Workflow Executions.

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.

show​

The tctl workflow show command shows the Event HistoryLink preview iconWhat is an Event History?

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

Learn more for the specified Workflow Execution.

tctl workflow show <modifiers>

The following modifiers control the behavior of the command.

signal​

The tctl workflow signal command SignalsLink preview iconWhat is a Signal?

A Signal is an asynchronous request to a Workflow Execution.

Learn more a Workflow Execution.

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.

stack​

The tctl workflow stack command queries Workflow Execution with --stack-trace as the query type.

tctl workflow stack <modifiers>

The following modifiers control the behavior of the command.

start​

The tctl workflow start command starts a new Workflow Execution. 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.

terminate​

The tctl workflow terminate command terminates a Workflow Execution. If run_id is not specified, the command terminates the last Workflow Execution with the specified workflow_id.

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.