# tctl v1.17 batch command reference

> Discover the new Temporal CLI, now in public preview. Use it for efficient management of multiple Workflow Executions with batch commands, signaling, cancellation, and termination tasks. Try it today!

> **ℹ️ Info:**
> tctl is deprecated
>
> The tctl command line utility has been deprecated and is no longer actively supported.
> We recommend transitioning to [Temporal CLI](/cli) for continued use and access to new features.
>
> Thank you for being a valued part of the Temporal community.
>

**How to run a tctl batch command.**

A `tctl batch` command enables you to affect multiple existing [Workflow Executions](/workflow-execution) with a single command.
A batch job runs in the background and affects Workflow Executions one at a time.

Use [tctl batch start](#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](/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

- [tctl batch describe](#describe)
- [tctl batch list](#list)
- [tctl batch start](#start)
- [tctl batch terminate](#terminate)

## 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](/workflow-execution) that this batch job should operate.

The SQL-like query of [Search Attributes](/search-attribute) is the same as used by the `tctl workflow list --query` command.

Alias: `-q`

**Example**

```bash
tctl batch start --query <value>
```

### `--reason`

Specify a reason for running this batch job.

**Example**

```bash
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**

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

### `--signal_name`

Specify the name of a [Signal](/sending-messages#sending-signals). This modifier is required when `--batch_type` is `signal`.

**Example**

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

### `--input`

Pass input for the [Signal](/sending-messages#sending-signals). Input must be in JSON format.

Alias: `-i`

**Example**

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

### `--rps`

Specify RPS of processing. The default value is 50.

**Example**

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

### `--yes`

Disable the confirmation prompt.

Alias: `y`

**Example**

```bash
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**

```bash
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**

```bash
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**

```bash
tctl batch terminate --job_id <id>
```

### `--reason`

Specify a reason for terminating this batch job.

**Example**

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