Skip to main content

tctl v1.17 batch 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.

How to run a tctl batch command.

A tctl batch command enables you to affect multiple existing Workflow Executions with a single command. A batch job runs in the background and affects Workflow Executions one at a time.

Use tctl batch start to start a batch job.

note

tctl-v1 can run batch and batch-v2 commands.

When starting a batch job, you must provide a List Filter and the type of batch job that should occur. Batch jobs run in the background and affect Workflow Executions one at a time.

The List Filter identifies the set of Workflow Executions to be affected by the batch job. The tctl batch start command shows you how many Workflow Executions will be affected by the batch job and asks you to confirm before proceeding.

The batch type determines what other parameters you must provide and what is being affected. There are three types of batch jobs:

  • Signal: Send a Signal to the set of Workflow Executions that the List Filter specifies.
  • Cancel: Cancel the set of Workflow Executions that the List Filter specifies.
  • Terminate: Terminate the set of Workflow Executions that the List Filter specifies.

A successfully started batch job returns a Job ID. You can use this Job ID in the tctl batch describe command, which describes the progress of a specific batch job.

You can also use the Job ID to terminate the batch job itself. Terminating a batch job does not roll back the operations already performed by the batch job.

tctl batch commands

start

The tctl batch start command starts a batch job.

tctl batch start --query <value> <modifiers>

The following modifiers control the behavior of the command.

--query

Required modifier

Specify the Workflow Executions that this batch job should operate.

The SQL-like query of Search Attributes is the same as used by the tctl workflow list --query command.

Alias: -q

Example

tctl batch start --query <value>

--reason

Specify a reason for running this batch job.

Example

tctl batch start --query <value> --reason <string>

--batch_type

Specify the operation that this batch job performs. The supported operations are signal, cancel, and terminate.

Example

tctl batch start --query <value> --batch_type <operation>

--signal_name

Specify the name of a Signal. This modifier is required when --batch_type is signal.

Example

tctl batch start --query <value> --batch_type signal --signal_name <name>

--input

Pass input for the Signal. Input must be in JSON format.

Alias: -i

Example

tctl batch start --query <value> --input <json>

--rps

Specify RPS of processing. The default value is 50.

Example

tctl batch start --query <value> --rps <value>

--yes

Disable the confirmation prompt.

Alias: y

Example

tctl batch start --query <value> --yes

list

The tctl batch list command lists all batch jobs.

tctl batch list <modifiers>

note

tctl-v1 can run batch and batch-v2 commands.

The following modifier controls the behavior of the command.

--pagesize

Specify the maximum number of batch jobs to list on a page. The default value is 30.

Example

tctl batch list --pagesize <value>

describe

The tctl batch describe command describes the progress of a batch job.

tctl batch describe --job_id <id>

note

tctl can run batch and batch-v2 commands.

The following modifier controls the behavior of the command.

--job_id

Required modifier

Specify the job ID of a batch job.

Example

tctl batch describe --job_id <id>

terminate

The tctl batch terminate command terminates a batch job.

tctl batch terminate --job_id <id> <modifiers>

note

tctl-v1 can run batch and batch-v2 commands.

The following modifiers control the behavior of the command.

--job_id

Required modifier

Specify the job ID of a batch job.

Example

tctl batch terminate --job_id <id>

--reason

Specify a reason for terminating this batch job.

Example

tctl batch terminate --job_id <id> --reason <string>