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