# OR using short alias
tctl --ns your-namespace n re
```

The following modifiers control the behavior of the command.

### --active_cluster

Specify the name of the active [Temporal Cluster](/temporal-service) when registering a [Namespace](/namespaces).
This value changes for Global Namespaces when a failover occurs.

**Example**

```bash
tctl namespace register --active_cluster <name>
```

### --clusters

Specify a list of [Temporal Clusters](/temporal-service) when registering a [Namespace](/namespaces).

The list contains the names of Clusters (separated by spaces) to which the Namespace can fail over.
Make sure to include to the currently active Cluster.
This is a read-only setting and cannot be changed.

This modifier is valid only when the `--global_namespace` modifier is set to true.

**Example**

```bash
tctl namespace register --clusters <names>
```

### --description

Specify a description when registering a [Namespace](/namespaces).

**Example**

```bash
tctl namespace register --description <value>
```

### --global_namespace

Specifies whether a [Namespace](/namespaces) is a [Global Namespace](/global-namespace).
When enabled, it controls the creation of replication tasks on updates allowing the state to be replicated across Clusters.
This is a read-only setting and cannot be changed.

**Example**

```bash
tctl namespace register --global_namespace <boolean>
```

### --history_archival_state

Set the state of [Archival](/temporal-service/archival).
Valid values are `disabled` and `enabled`.

**Example**

```bash
tctl namespace register --history_archival_state <value>
```

### --history_uri

Specify the URI for [Archival](/temporal-service/archival).
The URI cannot be changed after Archival is first enabled.

**Example**

```bash
tctl namespace register --history_uri <uri>
```

### --namespace_data

Specify data for a [Namespace](/namespaces) in the form of key-value pairs (such as `k1:v1,k2:v2,k3:v3`).

**Example**

```bash
tctl namespace register --namespace_data <data>
```

### --owner_email

Specify the email address of the [Namespace](/namespaces) owner.

**Example**

```bash
tctl namespace register --owner_email <value>
```

### --retention

Set the [Retention Period](/temporal-service/temporal-server#retention-period) for the [Namespace](/namespaces).

The Retention Period applies to Closed [Workflow Executions](/workflow-execution).

**Example**

```bash
tctl namespace register --retention <value>
```

### --visibility_archival_state

Set the visibility state for [Archival](/temporal-service/archival).
Valid values are `disabled` and `enabled`.

**Example**

```bash
tctl namespace register --visibility_archival_state <value>
```

### --visibility_uri

Specify the visibility URI for [Archival](/temporal-service/archival).
The URI cannot be changed after Archival is first enabled.

**Example**

```bash
tctl namespace register --visibility_uri <uri>
```

## update

The `tctl namespace update` command updates a [Namespace](/namespaces).

`tctl namespace update`

The following modifiers control the behavior of the command.

### --active_cluster

Specify the name of the active [Temporal Cluster](/temporal-service) when updating a [Namespace](/namespaces).

**Example**

```bash
tctl namespace update --active_cluster <name>
```

### --add_bad_binary

Add a binary checksum to use when resetting a [Workflow Execution](/workflow-execution).
Temporal will not dispatch any [Commands](/workflow-execution#command) to the given binary.

See also [`--remove_bad_binary`](#--remove_bad_binary).

**Example**

```bash
tctl namespace update --add_bad_binary <value>
```

### --clusters

Specify a list of [Temporal Clusters](/temporal-service) when updating a [Namespace](/namespaces).

The list contains the names of Clusters (separated by spaces) to which the Namespace can fail over.

This modifier is valid only when the `--global_namespace` modifier is set to true.

**Example**

```bash
tctl namespace update --clusters <names>
```

### --description

Specify a description when updating a [Namespace](/namespaces).

**Example**

```bash
tctl namespace update --description <value>
```

### --history_archival_state

Set the state of [Archival](/temporal-service/archival).
Valid values are `disabled` and `enabled`.

**Example**

```bash
tctl namespace update --history_archival_state <value>
```

### --history_uri

Specify the URI for URI for [Archival](/temporal-service/archival).
The URI cannot be changed after Archival is first enabled.

**Example**

```bash
tctl namespace update --history_uri <uri>
```

### --namespace_data

Specify data for a [Namespace](/namespaces) in the form of key-value pairs (such as `k1:v1,k2:v2,k3:v3`).

**Example**

```bash
tctl namespace update --namespace_data <data>
```

### --owner_email

Specify the email address of the [Namespace](/namespaces) owner.

**Example**

```bash
tctl namespace update --owner_email <value>
```

### --reason

Specify a reason for updating a [Namespace](/namespaces).

**Example**

```bash
tctl namespace update --reason <value>
```

### --remove_bad_binary

Remove a binary checksum.

See also [`--add_bad_binary`](#--add_bad_binary).

**Example**

```bash
tctl namespace update --remove_bad_binary <value>
```

### --retention

Specify the number of days to retain [Workflow Executions](/workflow-execution).

**Example**

```bash
tctl namespace update --retention <value>
```

### --visibility_archival_state

Set the visibility state for [Archival](/temporal-service/archival).
Valid values are `disabled` and `enabled`.

**Example**

```bash
tctl namespace update --visibility_archival_state <value>
```

### --visibility_uri

Specify the visibility URI for [Archival](/temporal-service/archival).
The URI cannot be changed after Archival is first enabled.

**Example**

```bash
tctl namespace update --visibility_uri <uri>
```

---

## tctl 1.17 schedule command reference

:::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.

:::

A [Schedule](/schedule) is an experimental feature available in `tctl 1.17` and `tctl next`.

- [Backfill a Schedule using tctl](#backfill)
- [Create a Schedule using tctl](#create)
- [Delete a Schedule using tctl](#delete)
- [Describe a Schedule using tctl](#describe)
- [List Schedules using tctl](#list)
- [Toggle Pause on Schedule using tctl](#toggle)
- [Trigger an Action on a Schedule using tctl](#trigger)
- [Update a Schedule using tctl](#update)

## backfill

Backfilling a Schedule means having it do now what it would have done over a specified time range (generally in the past, although it won't prevent you from giving a time range in the future).
You might use this to fill in runs from a time period when the Schedule was paused due to an external condition that's now resolved, or a period before the Schedule was created.

```shell
tctl schedule backfill --sid 'your-schedule-id' \
  --overlap-policy 'BufferAll'                \
  --start-time '2022-05-01T00:00:00Z'         \
  --end-time   '2022-05-31T23:59:59Z'
```

Note that, similar to [tctl schedule trigger](#trigger) immediately, you probably want to override the Overlap Policy.
Specifying `AllowAll` runs all the backfilled Workflows at once; `BufferAll` runs them sequentially.
The other policies don't make much sense in this context.

## create

With tctl, create a Schedule like this:

```shell
$ tctl config set version next   # ensure you're using the new tctl
$ tctl schedule create \
    --schedule-id 'your-schedule-id' \
    --interval '5h/15m' \
    --calendar '{"dayOfWeek":"Fri","hour":"11","minute":"3"}' \
    --overlap-policy 'BufferAll' \
    --workflow-id 'your-workflow-id' \
    --task-queue 'your-task-queue' \
    --workflow-type 'YourWorkflowType'
```

This Schedule takes action every 5 hours at 15 minutes past the hour and also at 11:03 on Fridays.
It starts a Workflow `YourWorkflowType` on Task Queue `your-task-queue`, giving it a Workflow Id like `your-workflow-id-2022-06-17T11:03:00Z`.
Workflows do not run in parallel.
If they would otherwise overlap, they are buffered to run sequentially.

You can also use traditional cron strings, including all features that are supported by `CronSchedule` today, such as `@weekly` and other shorthands, `@every`, and `CRON_TZ`.

```shell
$ tctl schedule create \
    --schedule-id 'your-schedule-id' \
    --cron '3 11 * * Fri' \
    --workflow-id 'your-workflow-id' \
    --task-queue 'your-task-queue' \
    --workflow-type 'YourWorkflowType'
```

<!-- ADDING TO DEPRECATED SECTION FOR INBOUND LINKS AND OLDER DEPLOYMENTS -->

Temporal Workflow Schedule Cron strings follow this format:

```
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
* * * * *
```

Any combination of `--calendar`, `--interval`, and `--cron` is supported and Actions will happen at any of the specified times.
If you use both `--time-zone` and also `CRON_TZ`, they must agree.

See `tctl schedule create --help` for the full set of available options.

## delete

A Schedule can be deleted.

Deleting a Schedule **does not** affect any Workflows started by the Schedule.
Workflow Executions started by Schedules can be cancelled or terminated using the same methods as any others.
However, Workflow Executions started by a Schedule can be identified by the Search Attributes added to them and can be targeted by a [batch](/tctl-v1/batch/) command for termination.

```shell
$ tctl schedule delete --schedule-id 'your-schedule-id'
```

## describe

Display the current Schedule configuration as well as extra information about past, current, and future Runs.

```shell
tctl schedule describe --schedule-id 'your-schedule-id'
```

Because the Schedule Spec is converted to canonical representations, the output might not be in the same form as it was input.

## list

```shell
tctl schedule list
```

Note that if you're using standard Visibility, listing Schedules will currently only include Schedule Ids and no other information.

Because the Schedule Spec is converted to canonical representations, the output might not be in the same form as it was input.

## toggle

```shell
$ tctl schedule toggle --schedule-id 'your-schedule-id' --pause --reason "paused because the database is down"
$ tctl schedule toggle --schedule-id 'your-schedule-id' --unpause --reason "the database is back up"
```

## trigger

Starting a Workflow Run immediately with a Schedule, regardless of its configured Spec, is a common use case.

```shell
$ tctl schedule trigger --schedule-id 'your-schedule-id'
```

Note that the action that it takes is subject to the Overlap Policy of the Schedule by default: if the overlap policy is `Skip` and a Workflow is already running, the triggered Action to start the next Workflow Run is skipped!
Likewise, if the overlap policy is `BufferAll`, the triggered run is buffered behind one or more runs.

If you really want it to run right now, you can override the overlap policy for this request:

```shell
$ tctl schedule trigger --schedule-id 'your-schedule-id' --overlap-policy 'AllowAll'
```

## update

Any part of the Schedule configuration can be updated at any time.

`tctl schedule update` takes the same options as `tctl schedule create` and replaces the entire configuration of the schedule with what's provided.

This means if you want to change just one value, you have to provide everything else again.

---

## tctl v1.17 taskqueue command reference

:::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.

:::

The `tctl taskqueue` command enables [Task Queue](/task-queue) operations.

Alias: `t`

- [tctl taskqueue describe](#describe)
- [tctl taskqueue list-partition](#list-partition)

## describe

The `tctl taskqueue describe` command describes the poller information of a [Task Queue](/task-queue).

`tctl taskqueue describe <modifiers> <value>`

The following modifiers control the behavior of the command.

### --taskqueue

_Required modifier_

Specify a [Task Queue](/task-queue).

Alias: `--t`

**Example**

```bash
tctl taskqueue describe --taskqueue <value>
```

### --taskqueuetype

Specify the type of a [Task Queue](/task-queue).
The type can be `workflow` or `activity`.
The default is `workflow`.

**Example**

```bash
tctl taskqueue describe --taskqueue <value> --taskqueuetype <type>
```

## list-partition

The `tctl taskqueue list-partition` command lists the partitions of a [Task Queue](/task-queue) and the hostname for the partitions.

`tctl taskqueue list-partition --taskqueue <value>`

The following modifier controls the behavior of the command.

### --taskqueue

_Required modifier_

Specify a [Task Queue](/task-queue) description.

Alias: `--t`

**Example**

```bash
tctl taskqueue list-partition --taskqueue <value>
```

---

## tctl v1.17 workflow command reference

:::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.

:::

The `tctl workflow` commands enable [Workflow Execution](/workflow-execution) operations.

- [tctl workflow cancel](#cancel)
- [tctl workflow count](#count)
- [tctl workflow describe](#describe)
- [tctl workflow describeid](#describeid)
- [tctl workflow list](#list)
- [tctl workflow listall](#listall)
- [tctl workflow listarchived](#listarchived)
- [tctl workflow observe](#observe)
- [tctl workflow observeid](#observeid)
- [tctl workflow query](#query)
- [tctl workflow reset](#reset)
- [tctl workflow reset-batch](#reset-batch)
- [tctl workflow run](#run)
- [tctl workflow scan](#scan)
- [tctl workflow show](#show)
- [tctl workflow showid](#showid)
- [tctl workflow signal](#signal)
- [tctl workflow stack](#stack)
- [tctl workflow start](#start)
- [tctl workflow terminate](#terminate)

## cancel

The `tctl workflow cancel --query` command cancels a [Workflow Execution](/workflow-execution).

Canceling a running Workflow Execution records a `WorkflowExecutionCancelRequested` event in the History.
A new [Workflow Task](/tasks#workflow-task) will be scheduled.
After cancellation, the Workflow Execution can perform cleanup work.

See also [`tctl workflow terminate --query`](#terminate).

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

The following modifiers control the behavior of the command.

### --workflow_id

Specify a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow cancel --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflow-execution/workflowid-runid#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow cancel --run_id <id>
```

## count

The `tctl workflow count` command counts [Workflow Executions](/workflow-execution).
This command requires Elasticsearch to be enabled.

`tctl workflow count <modifiers>`

The following modifier controls the behavior of the command.

### --query

_Required modifier_

Specify an SQL-like query of [Search Attributes](/search-attribute).

Alias: `-q`

**Example**

To count all open [Workflow Executions](/workflow-execution):

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

## describe

The `tctl workflow describe` command shows information about a [Workflow Execution](/workflow-execution).
This information can be used to locate a failed Workflow Execution, for example.

To find a Workflow with a given Run Id, refer to [`tctl workflow describeid`](#describeid).

`tctl workflow describe <modifiers>`

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

### --workflow_id

**This is a required modifier.**

Specify a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow describe --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflow-execution/workflowid-runid#run-id).
If a Run Id is not provided, the command will show the latest Workflow Execution of that Workflow Id.

Alias: `-r`

**Example**

```bash
tctl workflow describe --run_id <id>
```

### --print_raw

Print properties exactly as they are stored.

**Example**

```bash
tctl workflow describe --print_raw
```

### --reset_points_only

Show only events that are eligible for reset.
If successful, the command returns the Run Id of all deployments, and the times at which the Events were created.

**Example**

```bash
tctl workflow describe --reset_points_only
```

## describeid

The `tctl workflow describeid` command shows information about a [Workflow Execution](/workflow-execution) for the specified [Workflow Id](/workflow-execution/workflowid-runid#workflow-id)and optional [Run Id](/workflow-execution/workflowid-runid#run-id).

`tctl workflow describeid <workflow_id> <run_id> <modifiers>`

This command is a shortcut for `tctl workflow describe --workflow_id <workflowid> --run_id <runid>`.

The following modifiers control the behavior of the command.

### --print_raw

Print properties exactly as they are stored.

**Example**

```bash
tctl workflow describeid <workflow_id> <id> --print_raw
```

### --reset_points_only

Show only events that are eligible for reset.

**Example**

```bash
tctl workflow describeid <workflow_id> --reset_points_only
```

## list

The `tctl workflow list` command lists open or closed [Workflow Executions](/workflow-execution).

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

- To set the size of a page, use the `--pagesize` option.
- To list multiple pages, use the `--more` option.
- To list open Workflow Executions, use the `--open` option.

See also [`tctl workflow listall`](#listall), [`tctl workflow listarchived`](#listarchived), and [`tctl workflow scan`](#scan).

`tctl workflow list <modifiers>`

The following modifiers control the behavior of the command.

### --print_raw_time

Print the raw timestamp.

**Example**

```bash
tctl workflow list --print_raw_time
```

### --print_datetime

Print the timestamp.

**Example**

```bash
tctl workflow list --print_datetime
```

### --print_memo

Print a memo.

**Example**

```bash
tctl workflow list --print_memo
```

### --print_search_attr

Print the [Search Attributes](/search-attribute).

**Example**

```bash
tctl workflow list --print_search_attr
```

### --print_full

Print the full message without table formatting.

**Example**

```bash
tctl workflow list --print_full
```

### --print_json

Print the raw JSON objects.

**Example**

```bash
tctl workflow list --print_json
```

### --open

List open [Workflow Executions](/workflow-execution).
(By default, the `tctl workflow list` command lists closed Workflow Executions.)

**Example**

```bash
tctl workflow list --open
```

### --earliest_time

Specify the earliest start time to list.
Supported format are as follows:

- `<year>-<month>-<day>T<hour>:<minute>:<second><+|-><offsethours>:<offsetminutes>`
- Raw Unix Epoch time (the number of milliseconds since 0000 UTC on January 1, 1970).
- `<n><duration`, where `<n>` is a value between 0 and 1000000, and `<duration>` is one of the following:
  - `second` or `s`
  - `minute` or `m`
  - `hour` or `h`
  - `day` or `d`
  - `week` or `w`
  - `month` or `M`
  - `year` or `y`

**Examples**

To specify 3:04:05 PM India Standard Time on January 2, 2022:

```bash
tctl workflow list --earliest-time '2022-01-02T15:04:05+05:30'
```

To specify 15 minutes before the current time:

```bash
tctl workflow list --earliest-time '15minute'
```

### --latest_time

Specify the latest start time to list.
Supported formats are as follows:

- `<year>-<month>-<day>T<hour>:<minute>:<second><+|-><offsethours>:<offsetminutes>`
- Raw Unix Epoch time (the number of milliseconds since 0000 UTC on January 1, 1970).
- `<n><duration`, where `<n>` is a value between 0 and 1000000, and `<duration>` is one of the following:
  - `second` or `s`
  - `minute` or `m`
  - `hour` or `h`
  - `day` or `d`
  - `week` or `w`
  - `month` or `M`
  - `year` or `y`

**Examples**

To specify 11:02:17 PM Pacific Daylight Time on April 13, 2022:

```bash
tctl workflow list --latest_time '2022-04-13T23:02:17-07:00'
```

To specify 10s before the current time:

```bash
tctl workflow list --latest_time '10second'
```

### --workflow_id

Specify a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow list --workflow_id <id>
```

### --workflow_type

Specify the name of a [Workflow Type](/workflow-definition#workflow-type).

**Example**

```bash
tctl workflow list --workflow_type <name>
```

### --status

Specify the status of a [Workflow Execution](/workflow-execution).
Supported values are as follows:

- `completed`
- `failed`
- `canceled`
- `terminated`
- `continuedasnew`
- `timedout`

**Example**

```bash
tctl workflow list --status <value>
```

### --query

**How to list and filter Workflow Executions with a [List Filter](/list-filter) using tctl.**

The `--query` flag is supported only when [Advanced Visibility](/visibility#advanced-visibility) is configured with the Cluster.

Using the `--query` option causes tctl to ignore all other filter options, including `open`, `earliest_time`, `latest_time`, `workflow_id`, and `workflow_type`.

Alias: `-q`

**Example**

```bashbash
tctl workflow list --query "WorkflowId=<your-workflow-id>"
```

More examples:

```bashbash
tctl workflow list \
  --query "WorkflowType='main.SampleParentWorkflow' AND ExecutionStatus='Running'"
```

```bashbash
tctl workflow list \
  --query '(CustomKeywordField = "keyword1" and CustomIntField >= 5) or CustomKeywordField = "keyword2"' \
  --print_search_attr
```

```bashbash
tctl workflow list \
  --query 'CustomKeywordField in ("keyword2", "keyword1") and CustomIntField >= 5 and CloseTime between "2018-06-07T16:16:36-08:00" and "2019-06-07T16:46:34-08:00" order by CustomDatetimeField desc' \
  --print_search_attr
```

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

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

### --more

List more than one page.
(By default, the `tctl workflow list` command lists one page of results.)

**Example**

```bash
tctl workflow list --more
```

### --pagesize

Specify the maximum number of [Workflow Executions](/workflow-execution) to list on a page.
(By default, the `tctl workflow list` command lists 10 Workflow Executions per page.)

**Example**

```bash
tctl workflow list --pagesize <value>
```

## listall

The `tctl workflow listall` command lists all open or closed [Workflow Executions](/workflow-execution).

By default, this command lists all closed Workflow Executions.
To list open Workflow Executions, use the `--open` option.

See also [`tctl workflow list`](#list), [`tctl workflow listarchived`](#listarchived), and [`tctl workflow scan`](#scan).

`tctl workflow listall <modifiers>`

The following modifiers control the behavior of the command.

###`--print_raw_time

Print the raw timestamp.

**Example**

```bash
tctl workflow listall --print_raw_time
```

### --print_datetime

Print the timestamp.

**Example**

```bash
tctl workflow listall --print_datetime
```

### --print_memo

Print a memo.

**Example**

```bash
tctl workflow listall --print_memo
```

### --print_search_attr

Print the [Search Attributes](/search-attribute).

**Example**

```bash
tctl workflow listall --print_search_attr
```

### `--print_full`

Print the full message without table formatting.

**Example**

```bash
tctl workflow listall --print_full
```

### --print_json

Print the raw JSON objects.

**Example**

```bash
tctl workflow listall --print_json
```

### --open

List open [Workflow Executions](/workflow-execution).
(By default, the `tctl workflow listall` command lists closed Workflow Executions.)

**Example**

```bash
tctl workflow listall --open
```

### --earliest_time

Specify the earliest start time to list. Supported format are as follows:

- `<year>-<month>-<day>T<hour>:<minute>:<second><+|-><offsethours>:<offsetminutes>`
- Raw Unix Epoch time (the number of milliseconds since 0000 UTC on January 1, 1970).
- `<n><duration`, where `<n>` is a value between 0 and 1000000, and `<duration>` is one of the following:
  - `second` or `s`
  - `minute` or `m`
  - `hour` or `h`
  - `day` or `d`
  - `week` or `w`
  - `month` or `M`
  - `year` or `y`

**Examples**

To specify 3:04:05 PM India Standard Time on January 2, 2022:

```bash
tctl workflow listall --earliest-time '2022-01-02T15:04:05+05:30'
```

To specify 15 minutes before the current time:

```bash
tctl workflow listall --earliest-time '15minute'
```

### --latest_time

Specify the latest start time to list. Supported formats are as follows:

- `<year>-<month>-<day>T<hour>:<minute>:<second><+|-><offsethours>:<offsetminutes>`
- Raw Unix Epoch time (the number of milliseconds since 0000 UTC on January 1, 1970).
- `<n><duration`, where `<n>` is a value between 0 and 1000000, and `<duration>` is one of the following:
  - `second` or `s`
  - `minute` or `m`
  - `hour` or `h`
  - `day` or `d`
  - `week` or `w`
  - `month` or `M`
  - `year` or `y`

Alias: `--lt`

**Examples**

To specify 11:02:17 PM Pacific Daylight Time on April 13, 2022:

```bash
tctl workflow listall --latest-time '2022-04-13T23:02:17-07:00'
```

To specify 10 seconds before the current time:

```bash
tctl workflow listall --latest-time '10second'
```

### --workflow_id

Specify a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow listall --workflow_id <id>
```

### --workflow_type

Specify the name of a [Workflow Type](/workflow-definition#workflow-type).

**Example**

```bash
tctl workflow listall --workflow_type <name>
```

### --status

Specify the status of a [Workflow Execution](/workflow-execution).
Supported values are as follows:

- `completed`
- `failed`
- `canceled`
- `terminated`
- `continuedasnew`
- `timedout`

**Example**

```bash
tctl workflow listall --status <value>
```

### --query

Specify an SQL-like query of [Search Attributes](/search-attribute).

Using the `--query` option causes tctl to ignore all other filter options, including `open`, `earliest_time`, `latest_time`, `workflow_id`, and `workflow_type`.

Alias: `-q`

**Example**

```bash
tctl workflow listall --query <value>
```

## listarchived

The `tctl workflow listarchived` command lists archived [Workflow Executions](/workflow-execution).

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

- To set the size of a page, use the `--pagesize` option.
- To list all pages, use the `--all` option.

See also [`tctl workflow list`](#list), [`tctl workflow listall`](#listall), and [`tctl workflow scan`](#scan).

`tctl workflow listarchived <modifiers>`

The following modifiers control the behavior of the command.

### --print_raw_time

Print the raw timestamp.

**Example**

```bash
tctl workflow listarchived --print_raw_time
```

### --print_datetime

Print the timestamp.

**Example**

```bash
tctl workflow listarchived --print_datetime
```

### --print_memo

Print a memo.

**Example**

```bash
tctl workflow listarchived --print_memo
```

### --print_search_attr

Print the [Search Attributes](/search-attribute).

**Example**

```bash
tctl workflow listarchived --print_search_attr
```

### --print_full

Print the full message without table formatting.

**Example**

```bash
tctl workflow listarchived --print_full
```

### --print_json

Print the raw JSON objects.

**Example**

```bash
tctl workflow listarchived --print_json
```

### --query

Specify an SQL-like query of [Search Attributes](/search-attribute).

Consult the documentation of the visibility archiver that is used by your [Namespace](/namespaces) for detailed instructions.

Alias: `-q`

**Example**

```bash
tctl workflow listarchived --query <value>
```

### --pagesize

Specify the maximum number of [Workflow Executions](/workflow-execution) to list on a page.
(By default, the `tctl workflow listarchived` command lists 100 Workflow Executions per page.)

**Example**

```bash
tctl workflow listarchived --pagesize <value>
```

### --all

List all pages.

**Example**

```bash
tctl workflow listarchived --all
```

## observe

The `tctl workflow observe` command shows the progress of the [Event History](/workflow-execution/event#event-history) of a [Workflow Execution](/workflow-execution).

See also [`tctl workflow observeid`](#observeid).

`tctl workflow observe <modifiers>`

Alias: `o`

The following modifiers control the behavior of the command.

### --workflow_id

Specify a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow observe --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflow-execution/workflowid-runid#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow observe --run_id <id>
```

### --show_detail

Show event details.

**Example**

```bash
tctl workflow observe --show_detail
```

### --max_field_length

Specify the maximum length for each attribute field.
The default value is 0.

**Example**

```bash
tctl workflow observe --max_field_length <length>
```

## observeid

The `tctl workflow observeid` command shows the progress of the [Event History](/workflow-execution/event#event-history) of a [Workflow Execution](/workflow-execution) for the specified [Workflow Id](/workflow-execution/workflowid-runid#workflow-id)and optional [Run Id](/workflow-execution/workflowid-runid#run-id).

`tctl workflow observeid <workflow_id> [<run_id>] <modifiers>`

This command is a shortcut for `tctl workflow observe --workflow_id <workflowid> [--run_id <runid>]`.

The following modifiers control the behavior of the command.

### --show_detail

Show event details.

**Example**

```bash
tctl workflow observeid --show_detail
```

### --max_field_length

Specify the maximum length for each attribute field.
The default value is 0.

**Example**

```bash
tctl workflow observeid --max_field_length <length>
```

## query

Alias: `q`

The `tctl workflow query` command sends a [Query](/sending-messages#sending-queries) to a [Workflow Execution](/workflow-execution).

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

```bash
$ 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.

```bash
$ 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.

### --workflow_id

Specify a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id). **This modifier is required.**

Alias: `-w`

**Example**

```bash
tctl workflow query --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflow-execution/workflowid-runid#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow query --run_id <id>
```

### --query_type

Specify the type of Query to run.

**Example**

```bash
tctl workflow query --query_type <value>
```

### --input

Pass input for the Query.
Input must be in JSON format.
For multiple JSON objects, concatenate them and use spaces as separators.

Alias: `-i`

**Example**

```bash
tctl workflow query --input <json>
```

### --input_file

Pass input for the Query from a JSON file.
For multiple JSON objects, concatenate them and use spaces or newline characters as separators.
Input from the command line overwrites input from the file.

**Example**

```bash
tctl workflow query --input_file <filename>
```

### --query_reject_condition

Reject Queries based on Workflow state.
Valid values are `not_open` and `not_completed_cleanly`.

**Example**

```bash
tctl workflow query --query_reject_condition <value>
```

## reset

The `tctl workflow reset` command resets a [Workflow Execution](/workflow-execution) by either [`eventId`](#--event_id)or [`resetType`](#--reset_type).

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

To run multiple Reset operations at once, see [`tctl workflow reset-batch`](#reset-batch).

`tctl workflow reset <modifiers>`

The following modifiers control the behavior of the command.

### --workflow_id

Specify a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow reset --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflow-execution/workflowid-runid#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow reset --run_id <id>
```

### --event_id

Specify the `eventId` of any event after `WorkflowTaskStarted` to which you want to reset.
Valid values are `WorkflowTaskCompleted`, `WorkflowTaskFailed`, and `WorkflowTaskTimeout`.

**Example**

```bash
tctl workflow reset --event_id <id>
```

### --reason

Specify a reason for resetting the [Workflow Execution](/workflow-execution).

**Example**

```bash
tctl workflow reset --reason <string>
```

### --reset_type

Specify the event type to which you want to reset.

| Value                | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| `FirstWorkflowTask`  | Reset to the beginning of the Event History.                |
| `LastWorkflowTask`   | Reset to the end of the Event History.                      |
| `LastContinuedAsNew` | Reset to the end of the Event History for the previous Run. |
| `BadBinary`          | Reset to the point where a bad binary was used.             |

**Example**

```bash
tctl workflow reset --reset_type <value>
```

### --reset_reapply_type

Specify the types of events to reapply after the reset point.
Valid values are `All`, `Signal`, and `None`. The default is `All`.

**Example**

```bash
tctl workflow reset --reset_reapply_type <value>
```

### --reset_bad_binary_checksum

Specify the binary checksum when using `--reset_type BadBinary`.

**Example**

```bash
tctl workflow reset --reset_bad_binary_checksum <value>
```

## reset-batch

The `tctl workflow reset-batch` command resets a batch of [Workflow Executions](/workflow-execution) by [`resetType`](#--reset_type).

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

To reset individual Workflows, see [`tctl workflow reset`](#reset).

`tctl workflow reset-batch <modifiers>`

The following modifiers control the behavior of the command.

### --input_file

Provide an input file that specifies [Workflow Execution](/workflow-execution) to reset.

Each line contains one [Workflow Id](/workflow-execution/workflowid-runid#workflow-id)as the base Run and, optionally, a [Run Id](/workflow-execution/workflowid-runid#run-id).
If a Run Id is not specified, the current Run Id is used.

**Example**

```bash
tctl workflow reset-batch --input_file <filename>
```

### --query

Specify an SQL-like query of [Search Attributes](/search-attribute) describing the [Workflow Executions](/workflow-execution) to reset.

Alias: `-q`

**Example**

```bash
tctl workflow reset-batch --query <value>
```

### --exclude_file

Provide an input file that specifies [Workflow Executions](/workflow-execution) to exclude from resetting.

Each line contains one [Workflow Id](/workflow-execution/workflowid-runid#workflow-id).

**Example**

```bash
tctl workflow reset-batch --exclude_file <filename>
```

### --input_separator

Specify the separator for the input file.
The default is a tab (`\t`).

**Example**

```bash
tctl workflow reset-batch --input_separator <string>
```

### --reason

Specify a reason for resetting the [Workflow Executions](/workflow-execution).

**Example**

```bash
tctl workflow reset-batch --reason <string>
```

### --input_parallism

Specify the number of goroutines to run in parallel.
Each goroutine processes one line for every second.
The default is 1.

**Example**

```bash
tctl workflow reset-batch --input_parallism <value>
```

### --skip_current_open

Indicate that a [Workflow Execution](/workflow-execution) should be skipped if the current Run is open for the same [Workflow Id](/workflow-execution/workflowid-runid#workflow-id)as the base Run.

**Example**

```bash
tctl workflow reset-batch --skip_current_open
```

### --skip_base_is_not_current

Indicate that a [Workflow Execution](/workflow-execution) should be skipped if the base Run is not the current Run.

**Example**

```bash
tctl workflow reset-batch --skip_base_is_not_current
```

### --only_non_deterministic

Indicate that a [Workflow Execution](/workflow-execution) should be reset only if its last event is `WorkflowTaskFailed` with a nondeterminism error.

**Example**

```bash
tctl workflow reset-batch --only_non_deterministic
```

### --dry_run

Simulate use of the `tctl workflow reset-batch` command without resetting any [Workflow Executions](/workflow-execution).
Output is logged to `stdout`.

**Example**

```bash
tctl workflow reset-batch --dry_run
```

### --reset_type

Specify the event type to which you want to reset.

| Value                | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| `FirstWorkflowTask`  | Reset to the beginning of the Event History.                |
| `LastWorkflowTask`   | Reset to the end of the Event History.                      |
| `LastContinuedAsNew` | Reset to the end of the Event History for the previous Run. |
| `BadBinary`          | Reset to the point where a bad binary was used.             |

**Example**

```bash
tctl workflow reset-batch --reset_type <value>
```

### --reset_bad_binary_checksum

Specify the binary checksum when using `--reset_type BadBinary`.

**Example**

```bash
tctl workflow reset-batch --reset_bad_binary_checksum <value>
```

## run

The `tctl workflow run` command starts a new [Workflow Execution](/workflow-execution) and can show the progress of a Workflow Execution.
The command is entered in the following format:

`tctl workflow run <modifiers>`

To run a Workflow, the user must specify the following:

- Task queue name (`--taskqueue`)
- Workflow Type (`--workflow_type`)

```bash
tctl workflow run --taskqueue your-task-queue-name --workflow_type YourWorkflowDefinitionName
```

Single quotes (`''`) are used to wrap input as JSON.
This command doesn't finish until the Workflow completes.

The following modifiers control the behavior of the command.

### --taskqueue

Specify a [Task Queue](/task-queue).

Alias: `--t`

**Example**

```bash
tctl workflow run --taskqueue <name>
```

### --workflow_id

Specify a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow run --workflow_id <id>
```

### --workflow_type

Specify the name of a [Workflow Type](/workflow-definition#workflow-type).

**Example**

```bash
tctl workflow run --workflow_type <name>
```

### --execution_timeout

Specify the [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of the [Workflow Execution](/workflow-execution) in seconds.
The default value is 0.

**Example**

```bash
tctl workflow run --execution_timeout <seconds>
```

### --workflow_task_timeout

Specify the [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of the [Workflow Task](/tasks#workflow-task) in seconds.
The default value is 10.

**Example**

```bash
tctl workflow run --workflow_task_timeout <seconds>
```

### --cron

Specify a [Cron Schedule](/cron-job#cron-schedules).

**Example**

```bash
tctl workflow run --cron <string>
```

### --workflowidreusepolicy

Specify a [Workflow Id Reuse Policy](/workflow-execution/workflowid-runid#workflow-id-reuse-policy).
Configure if the same [Workflow Id](/workflow-execution/workflowid-runid#workflow-id)is allowed for use in new [Workflow Execution](/workflow-execution).

There are three allowed values:

- [AllowDuplicateFailedOnly](/workflow-execution/workflowid-runid#workflow-id-reuse-policy)
- [AllowDuplicate](/workflow-execution/workflowid-runid#workflow-id-reuse-policy)
- [RejectDuplicate](/workflow-execution/workflowid-runid#workflow-id-reuse-policy)

**Examples**

```bash
tctl workflow run --workflowidreusepolicy AllowDuplicate
tctl workflow run --workflowidreusepolicy AllowDuplicateFailedOnly
tctl workflow run --workflowidreusepolicy RejectDuplicate
```

### --input

Pass input for the Workflow.
Input must be in JSON format.
For multiple JSON objects, pass each in a separate `--input` option. Use `null` for null values.

Alias: `-i`

**Example**

```bash
tctl workflow run --input <json>
```

### --input_file

Pass input for the Workflow from a JSON file.
For multiple JSON objects, concatenate them and use spaces or newline characters as separators.
Input from the command line overwrites input from the file.

**Example**

```bash
tctl workflow run --input_file <filename>
```

### --memo_key

Pass a key for a memo.
For multiple keys, concatenate them and use spaces as separators.

**Example**

```bash
tctl workflow run --memo_key <key>
```

### --memo

Pass a memo.
A memo is information in JSON format that can be shown when the Workflow is listed.
For multiple memos, concatenate them and use spaces as separators.
The order must match the order of keys in `--memo_key`.

**Example**

```bash
tctl workflow run --memo <json>
```

### --memo_file

Pass information for a memo from a JSON file.
For multiple JSON objects, concatenate them and use spaces or newline characters as separators.
The order must match the order of keys in `--memo_key`.

**Example**

```bash
tctl workflow run --memo_file <filename>
```

### --search_attr_key

Specify a [Search Attribute](/search-attribute) key.
For multiple keys, concatenate them and use pipes (`|`) as separators.

To list valid keys, use the `tctl cluster get-search-attributes` command.

**Example**

```bash
tctl workflow run --search_attr_key <key>
```

### --search_attr_value

Specify a [Search Attribute](/search-attribute) value.
For multiple values, concatenate them and use pipes (`|`) as separators.
If a value is an array, use JSON format, such as `["a","b"]`, `[1,2]`, `["true","false"]`, or `["2022-06-07T17:16:34-08:00","2022-06-07T18:16:34-08:00"]`.

To list valid keys and value types, use the `tctl cluster get-search-attributes` command.

**Example**

```bash
tctl workflow run --search_attr_value <value>
```

### --show_detail

Get event details.

**Example**

```bash
tctl workflow run --show_detail
```

### --max_field_length

Specify the maximum length for each attribute field.
The default value is 0.

**Example**

```bash
tctl workflow run --max_field_length <length>
```

## scan

The `tctl workflow scan` command lists [Workflow Executions](/workflow-execution).
It is faster than the `tctl workflow listall` command, but the results are not sorted.

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`](#list), [`tctl workflow listall`](#listall), and [`tctl workflow listarchived`](#listarchived).

`tctl workflow scan <modifiers>`

The following modifiers control the behavior of the command.

### --print_raw_time

Print the raw timestamp.

**Example**

```bash
tctl workflow scan --print_raw_time
```

### --print_datetime

Print the timestamp.

**Example**

```bash
tctl workflow scan --print_datetime
```

### --print_memo

Print a memo.

**Example**

```bash
tctl workflow scan --print_memo
```

### --print_search_attr

Print the [Search Attributes](/search-attribute).

**Example**

```bash
tctl workflow scan --print_search_attr
```

### --print_full

Print the full message without table formatting.

**Example**

```bash
tctl workflow scan --print_full
```

### --print_json

Print the raw JSON objects.

**Example**

```bash
tctl workflow scan --print_json
```

### --pagesize

Specify the maximum number of [Workflow Execution](/workflow-execution) to list on a page.
(By default, the `tctl workflow scan` command lists 2000 Workflow Executions per page.)

**Example**

```bash
tctl workflow scan --pagesize <value>
```

### --query

Specify an SQL-like query of [Search Attributes](/search-attribute).

Alias: `-q`

**Example**

```bash
tctl workflow scan --query <value>
```

## show

The `tctl workflow show` command shows the [Event History](/workflow-execution/event#event-history) for the specified [Workflow Execution](/workflow-execution).

`tctl workflow show <modifiers>`

See also [`tctl workflow showid`](#showid).

The following modifiers control the behavior of the command.

### --workflow_id

Show the History of a [Workflow Execution](/workflow-execution) by specifying a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow show --workflow_id <id>
```

### --run_id

Show the History of a [Workflow Execution](/workflow-execution) by specifying a [Run Id](/workflow-execution/workflowid-runid#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow show --run_id <id>
```

### --print_datetime

Print the timestamp.

**Example**

```bash
tctl workflow show --print_datetime
```

### --print_raw_time

Print the raw timestamp.

**Example**

```bash
tctl workflow show --print_raw_time
```

### --output_filename

Serialize an event to a file.

**Example**

```bash
tctl workflow show --output_filename <filename>
```

### --print_full

Print full event details.

**Example**

```bash
tctl workflow show --print_full
```

### --print_event_version

Print the event version.

**Example**

```bash
tctl workflow show --print_event_version
```

### --event_id

Print the details of a specified event.
The default value is 0.

**Example**

```bash
tctl workflow show --event_id <id>
```

### --max_field_length

Specify the maximum length for each attribute field.
The default value is 500.

**Example**

```bash
tctl workflow show --max_field_length <length>
```

### --reset_points_only

Show only events that are eligible for reset.

**Example**

```bash
tctl workflow show --reset_points_only
```

## showid

The `tctl workflow showid` command shows the Workflow Execution Event History for the specified [Workflow Id](/workflow-execution/workflowid-runid#workflow-id)and optional [Run Id](/workflow-execution/workflowid-runid#run-id).

`tctl workflow showid <workflow_id> [<run_id>] <modifiers>`

This command is a shortcut for `tctl workflow show --workflow_id <workflowid> [--run_id <runid>]`.

Example:

```bashbash
tctl workflow showid <workflow_id>
```

Example output:

```bashtext
1  WorkflowExecutionStarted    {WorkflowType:{Name:HelloWorld}, ParentInitiatedEventId:0,
                                TaskQueue:{Name:HelloWorldTaskQueue, Kind:Normal},
                                Input:[Temporal], WorkflowExecutionTimeout:1h0m0s,
                                WorkflowRunTimeout:1h0m0s, WorkflowTaskTimeout:10s,
                                Initiator:Unspecified, LastCompletionResult:[],
                                OriginalExecutionRunId:f0c04163-833f-490b-99a9-ee48b6199213,
                                Identity:tctl@z0mb1e,
                                FirstExecutionRunId:f0c04163-833f-490b-99a9-ee48b6199213,
                                Attempt:1, WorkflowExecutionExpirationTime:2020-10-13
                                21:41:06.349 +0000 UTC, FirstWorkflowTaskBackoff:0s}
2  WorkflowTaskScheduled       {TaskQueue:{Name:HelloWorldTaskQueue,
                                Kind:Normal},
                                StartToCloseTimeout:10s, Attempt:1}
3  WorkflowTaskStarted         {ScheduledEventId:2, Identity:15079@z0mb1e,
                                RequestId:731f7b41-5ae4-42e4-9695-ecd857d571f1}
4  WorkflowTaskCompleted       {ScheduledEventId:2,
                                StartedEventId:3,
                                Identity:15079@z0mb1e}
5  WorkflowExecutionCompleted  {Result:[],
                                WorkflowTaskCompletedEventId:4}
```

The following modifiers control the behavior of the command.

### --print_datetime

Print the timestamp.

**Example**

```bash
tctl workflow showid <workflow_id> --print_datetime
```

### --print_raw_time

Print the raw timestamp.

**Example**

```bash
tctl workflow showid <workflow_id> --print_raw_time
```

### --output_filename

Serialize an event to a file.

**Example**

```bash
tctl workflow showid <workflow_id> --output_filename <filename>
```

### --print_full

Print full event details.

**Example**

```bash
tctl workflow showid <workflow_id> --print_full
```

### --print_event_version

Print the event version.

**Example**

```bash
tctl workflow showid <workflow_id> --print_event_version
```

### --event_id

Print the details of a specified event.
The default value is 0.

**Example**

```bash
tctl workflow showid <workflow_id> --event_id <id>
```

### --max_field_length

Specify the maximum length for each attribute field.
The default value is 500.

**Example**

```bash
tctl workflow showid <workflow_id> --max_field_length <length>
```

### --reset_points_only

Show only events that are eligible for reset.

**Example**

```bash
tctl workflow showid <workflow_id> --reset_points_only
```

## signal

The `tctl workflow signal` command [Signals](/sending-messages#sending-signals) a [Workflow Execution](/workflow-execution).

Workflows listen for Signals by their Signal name, and can be made to listen to one or more Signal names.
Workflows can also listen for SQL queries.

The Workflow below listens for instances of "HelloSignal":

```bash
tctl workflow start  --workflow_id "HelloSignal" --taskqueue HelloWorldTaskQueue --workflow_type HelloWorld --execution_timeout 3600 --input \"World\"
```

The Worker would return this output upon receiving the Signal:

```text
13:57:44.258 [workflow-method] INFO  c.t.s.javaquickstart.GettingStarted - 1: Hello World!
```

Signals can also be used to change variable values.

```bash
tctl workflow signal --workflow_id "HelloSignal" --name "updateGreeting" --input \"Hi\"
```

The output would change from the first Signal received.

```text
13:57:44.258 [workflow-method] INFO  c.t.s.javaquickstart.GettingStarted - 1: Hello World!
13:58:22.352 [workflow-method] INFO  c.t.s.javaquickstart.GettingStarted - 2: Hi World!
```

When a Signal is sent, an await condition is made to block any Signals that contain the same input value.
However, changing the greeting in our example unblocks it:

```bash
tctl workflow signal --workflow_id "HelloSignal" --name "updateGreeting" --input \"Welcome\"
```

Worker output:

```text
13:57:44.258 [workflow-method] INFO  c.t.s.javaquickstart.GettingStarted - 1: Hello World!
13:58:22.352 [workflow-method] INFO  c.t.s.javaquickstart.GettingStarted - 2: Hi World!
13:59:29.097 [workflow-method] INFO  c.t.s.javaquickstart.GettingStarted - 3: Welcome World!
```

Sending Signals does not require a running Worker.

```bash
tctl workflow signal --workflow_id "HelloSignal" --name "updateGreeting" --input \"Welcome\"
```

CLI output:

```text
Signal workflow succeeded.
```

The Signal request is queued inside the Temporal Server until the Worker is restarted.
If the given Signal contains the same input as before, the queued Signal will be ignored.

Complete the Workflow by sending a Signal with a "Bye" greeting:

```bash
tctl workflow signal --workflow_id "HelloSignal" --name "updateGreeting" --input \"Bye\"
```

Check that the Workflow Execution has been completed.

```bash
tctl workflow showid HelloSignal
```

Signals are written as follows:

```bash
tctl workflow signal --workflow_id <id> <modifiers>
```

or

```bash
tctl workflow signal --query <query> <modifiers>
```

The following modifiers control the behavior of the command.
Make sure to include required modifiers in all command executions.

### --workflow_id

Specify a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id). **This modifier is required.**

Alias: `-w`

**Example**

```bash
tctl workflow signal --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflow-execution/workflowid-runid#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow signal --run_id <id>
```

### --name

Specify the name of a [Signal](/sending-messages#sending-signals).

**Example**

```bash
tctl workflow signal --query <query> --name <name>
```

### --input

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

Alias: `-i`

**Example**

```bash
tctl workflow signal --query <query> --input <json>
```

### --input_file

Pass input for the [Signal](/sending-messages#sending-signals) from a JSON file.

**Example**

```bash
tctl workflow signal --query <query> --input_file <filename>
```

## stack

The `tctl workflow stack` command queries [Workflow Execution](/workflow-execution) with `__stack_trace` as the query type.

This command can be used to locate errors and blocks in a [Workflow Definition](/workflow-definition).

`tctl workflow stack <modifiers>`

The following modifiers control the behavior of the command.

### --workflow_id

**This is a required modifier.**

Specify a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow stack --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflow-execution/workflowid-runid#run-id).

Alias: `-r`

**Example**

```bash
tctl workflow stack --run_id <id>
```

### --input

Pass input for the query.
Input must be in JSON format.
For multiple JSON objects, concatenate them and use spaces as separators.

Alias: `-i`

**Example**

```bash
tctl workflow stack --input <json>
```

### --input_file

Pass input for the query from a JSON file.
For multiple JSON objects, concatenate them and use spaces or newline characters as separators.
Input from the command line overwrites input from the file.

**Example**

```bash
tctl workflow stack --input_file <filename>
```

### --query_reject_condition

Reject queries based on Workflow state.
Valid values are `not_open` and `not_completed_cleanly`.

**Example**

```bash
tctl workflow stack --query_reject_condition <value>
```

## start

The `tctl workflow start` command starts a new [Workflow Execution](/workflow-execution).
Unlike `run`, 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.

### --taskqueue

Specify a [Task Queue](/task-queue).

Alias: `--t`

**Example**

```bash
tctl workflow start --taskqueue <name>
```

### --workflow_id

**This is a required modifier.**

Specify a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow start --workflow_id <id>
```

If a Workflow is started without providing an Id, the Client generates one in the form of a UUID.
Temporal recommends using a business id rather than the client-generated UUID.

**Example**

```bash
tctl workflow start  --workflow_id "HelloTemporal1" --taskqueue HelloWorldTaskQueue --workflow_type HelloWorld --execution_timeout 3600 --input \"Temporal\"
```

### --workflow_type

Specify the name of a [Workflow Type](/workflow-definition#workflow-type).

**Example**

```bash
tctl workflow start --workflow_type <name>
```

### --execution_timeout

Specify the [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of the [Workflow Execution](/workflow-execution) in seconds.
The default value is 0.

**Example**

```bash
tctl workflow start --execution_timeout <seconds>
```

### --workflow_task_timeout

Specify the [Start-To-Close Timeout](/encyclopedia/detecting-activity-failures#start-to-close-timeout) of the [Workflow Task](/tasks#workflow-task) in seconds.
The default value is 10.

**Example**

```bash
tctl workflow start --workflow_task_timeout <seconds>
```

### --cron

Specify a [Cron Schedule](/cron-job#cron-schedules).

**Example**

```bash
tctl workflow start --cron <string>
```

### --workflowidreusepolicy

Specify a [Workflow Id Reuse Policy](/workflow-execution/workflowid-runid#workflow-id-reuse-policy).
Configure if the same [Workflow Id](/workflow-execution/workflowid-runid#workflow-id)is allowed for use in new [Workflow Execution](/workflow-execution).

There are three allowed values:

- [AllowDuplicateFailedOnly](/workflow-execution/workflowid-runid#workflow-id-reuse-policy)
- [AllowDuplicate](/workflow-execution/workflowid-runid#workflow-id-reuse-policy)
- [RejectDuplicate](/workflow-execution/workflowid-runid#workflow-id-reuse-policy)

**Examples**

```bash
tctl workflow start --workflowidreusepolicy AllowDuplicate
tctl workflow start --workflowidreusepolicy AllowDuplicateFailedOnly
tctl workflow start --workflowidreusepolicy RejectDuplicate
```

:::note

Multiple Workflows with the same Id cannot be run at the same time

:::

### --input

Pass input for the Workflow.
Input must be in JSON format.
For multiple JSON objects, pass each in a separate `--input` option.
Use `null` for null values.

Alias: `-i`

**Example**

```bash
tctl workflow start --input <json>
```

### --input_file

Pass input for the Workflow from a JSON file.
For multiple JSON objects, concatenate them and use spaces or newline characters as separators.
Input from the command line overwrites input from the file.

**Example**

```bash
tctl workflow start --input_file <filename>
```

### --memo_key

Pass a key for a memo.
For multiple keys, concatenate them and use spaces as separators.

**Example**

```bash
tctl workflow start --memo_key <key>
```

### --memo

Pass information for a [memo](/workflow-execution#memo) from a JSON file.

Memos are immutable key/value pairs that can be attached to a workflow run when starting the workflow.
Memos are visible when listing workflows.

For multiple memos, concatenate them and use spaces as separators.
The order must match the order of keys in `--memo_key`.

**Example**

```bash
tctl workflow start \
  -tq your-task-queue \
  -wt your-workflow \
  -et 60 \
  -i '"temporal"' \
  -memo_key '<key values>' \
  -memo '<value>'
```

### --memo_file

Pass information for a memo from a JSON file.
For multiple JSON objects, concatenate them and use spaces or newline characters as separators.
The order must match the order of keys in `--memo_key`.

**Example**

```bash
tctl workflow start --memo_file <filename>
```

### --search_attr_key

Specify a [Search Attribute](/search-attribute) name.
For multiple names, concatenate them and use pipes (`|`) as separators.

To list valid Search Attributes, use the `tctl cluster get-search-attributes` command.

**Example**

```bash
tctl workflow start --search_attr_key <key>
```

### --search_attr_value

Specify a [Search Attribute](/search-attribute) value.
For multiple values, concatenate them and use pipes (`|`) as separators.
If a value is an array, use JSON format, such as `["a","b"]`, `[1,2]`, `["true","false"]`, or `["2022-06-07T17:16:34-08:00","2022-06-07T18:16:34-08:00"]`.

To list valid Search Attributes and value types, use the `tctl cluster get-search-attributes` command.

**Example**

```bash
tctl workflow start --search_attr_value <value>
```

## terminate

The `tctl workflow terminate` command terminates a [Workflow Execution](/workflow-execution).

Terminating a running Workflow Execution records a `WorkflowExecutionTerminated` event as the closing event in the History.
No more [Workflow Task](/tasks#workflow-task) will be scheduled.

See also [`tctl workflow cancel`](#cancel).

`tctl workflow terminate --query <modifiers>`

The following modifiers control the behavior of the command.

### --workflow_id

_Required modifier_

Specify a [Workflow Id](/workflow-execution/workflowid-runid#workflow-id).

Alias: `-w`

**Example**

```bash
tctl workflow terminate --workflow_id <id>
```

### --run_id

Specify a [Run Id](/workflow-execution/workflowid-runid#run-id).

If `run_id` is not specified, `tctl` terminates the last Workflow Execution for the specified `workflow_id`.

Alias: `-r`

**Example**

```bash
tctl workflow terminate --run_id <id>
```

### --reason

Specify a reason for terminating the [Workflow Execution](/workflow-execution).

**Example**

```bash
tctl workflow terminate --workflow_id --reason <string>
```

---

## Troubleshoot the blob size limit error

The `BlobSizeLimitError` is an error that occurs when the size of a blob (payloads including Workflow context and each Workflow and Activity argument and return value) exceeds the set limit in Temporal.

- The max payload for a single request is 2 MB.
- The max size limit for any given [Event History](/workflow-execution/event#event-history) transaction is 4 MB.

## Why does this error occur?

This error occurs when the size of the blob exceeds the maximum size allowed by Temporal.

This limit helps ensure that the Temporal Service prevents excessive resource usage and potential performance issues when handling large payloads.

## How do I resolve this error?

To resolve this error, reduce the size of the blob so that it is within the 4 MB limit.

There are multiple strategies you can use to avoid this error:

1. Use compression with a [custom payload codec](/payload-codec) for large payloads.

   - This addresses the immediate issue of the blob size limit; however, if blob sizes continue to grow this problem can arise again.

2. Break larger batches of commands into smaller batch sizes:

   - Workflow-level batching:
     1. Modify the Workflow to process Activities or Child Workflows into smaller batches.
     2. Iterate through each batch, waiting for completion before moving to the next.
   - Workflow Task-level batching:
     1. Execute Activities in smaller batches within a single Workflow Task.
     2. Introduce brief pauses or sleeps (for example, 1ms) between batches.

3. Consider offloading large payloads to an object store to reduce the risk of exceeding blob size limits:
   1. Pass references to the stored payloads within the Workflow instead of the actual data.
   2. Retrieve the payloads from the object store when needed during execution.

---

## Troubleshoot the deadline-exceeded error

All requests made to the [Temporal Service](/temporal-service) by the Client or Worker are [gRPC requests](https://grpc.io/docs/what-is-grpc/core-concepts/#deadlines).
Sometimes, when these frontend requests can't be completed, you'll see this particular error message: `Context: deadline exceeded`.
Network interruptions, timeouts, server overload, and Query errors are some of the causes of this error.

The following sections discuss the nature of this error and how to troubleshoot it.

### Check system clocks

Timing skew can cause the system clock on a Worker to drift behind the system clock of the Temporal Service.
If the difference between the two clocks exceeds an Activity's Start-To-Close Timeout, an `Activity complete after timeout` error occurs.

If you receive an `Activity complete after timeout` error alongside `Context: deadline exceeded`, check the clocks on the Temporal Service's system and the system of the Worker sending that error.
If the Worker's clock doesn't match the Temporal Service, synchronize all clocks to an NTP server.

### Check Frontend Service logs

:::note

Cloud users cannot access some of the logs needed to diagnose the source of the error.

If you're using Temporal Cloud, create a [support ticket](/cloud/support#support-ticket) with as much information as possible, including the Namespace Name and the Workflow Ids of some Workflow Executions in which the issue occurs.

:::

[Frontend Service](/temporal-service/temporal-server#frontend-service) logs can show which parts of the Temporal Service aren't working.
For the error to appear, a service pod or container must be up and running.

OSS users can verify that the Frontend Service is connected and running by using the Temporal CLI.

```
temporal operator cluster health --address 127.0.0.1:7233
```

Use [`grpc-health-probe`](https://github.com/grpc-ecosystem/grpc-health-probe) to check the Frontend Service, [Matching Service](/temporal-service/temporal-server#matching-service), and [History Service](/temporal-service/temporal-server#history-service).

```
./grpc-health-probe -addr=frontendAddress:frontendPort -service=temporal.api.workflowservice.v1.WorkflowService

./grpc-health-probe -addr=matchingAddress:matchingPort -service=temporal.api.workflowservice.v1.MatchingService

./grpc-health-probe -addr=historyAddress:historyPort -service=temporal.api.workflowservice.v1.HistoryService
```

Logs can also be used to find failed Client [Query](/sending-messages#sending-queries) requests.

### Check your Temporal Service metrics

Temporal Service metrics can be used to detect issues (such as `resource exhausted`) that impact Temporal Service health.
A `resource exhausted` error can cause your client request to fail, which prompts the `deadline exceeded` error.

Use the following query to check for errors in `RpsLimit`, `ConcurrentLimit` and `SystemOverloaded` on your metrics dashboard.

```
sum(rate(service_errors_resource_exhausted{}[1m])) by (resource_exhausted_cause)
```

Look for high latencies, short timeouts, and other abnormal [Temporal Service metrics](/references/cluster-metrics).
If the metrics come from a specific service (such as History Service), check the service's health and performance.

### Check Workflow logic

Check your [Client and Worker configuration](/references/configuration) files for missing or invalid target values, such as the following:

- Server names
- Network or host addresses
- Certificates

Invalid targets also cause `connection refused` errors alongside `deadline exceeded`.
Check that the Client connects after updating your files.

### Advanced troubleshooting

In addition to the steps listed in the previous sections, check the areas mentioned in each of the following scenarios.

### After enabling mTLS

Check the health of the Temporal Service with `temporal operator cluster health`.

```
temporal operator cluster health --address [SERVER_ADDRESS]
```

Add any missing [environment variables](/references/web-ui-environment-variables) to the configuration files, and correct any incorrect values.
Server names and certificates must match between Frontend and internode.

### After restarting the Temporal Service

You might not be giving the Temporal Service enough time to respond and reconnect.
Restart the Server, wait, and then check all services for connectivity and further errors.

If the error persists, review your Workflow Execution History and server logs for more specific causes before continuing to troubleshoot.

### When executing or scheduling Workflows

One or more services might be unable to connect to the [Frontend Service](/temporal-service/temporal-server#frontend-service).
The Workflow might be unable to complete requests within the given connection time.

Increase the value of `frontend.keepAliveMaxConnectionAge` so that requests can be finished before the connection terminates.

:::note

If you increase `frontend.keepAliveMaxConnectionAge` values, consider monitoring your server performance for load.

:::

---

Still unable to resolve your issue?

- If you use Temporal Cloud, create a [support ticket](/cloud/support#support-ticket).
- If you use our open source software or Temporal Cloud, check for similar questions and possible solutions in our [community forum](https://community.temporal.io) or [community Slack](https://temporal.io/slack).

---

## Error Handling and Troubleshooting

Even the most reliable systems can encounter issues.
Our troubleshooting guides are designed to help you quickly identify and resolve potential errors, ensuring your Temporal applications run smoothly and efficiently.

- [Troubleshoot the BlobSizeLimitError](/troubleshooting/blob-size-limit-error): The `BlobSizeLimitError` happens when the size of a blob (payloads including Workflow context and each Workflow and Activity argument and return value) is too large.
  The maximum payload for a single request is 2 MB, and the maximum size for any Event History transaction is 4 MB.
- [Troubleshoot the Deadline-Exceeded Error](/troubleshooting/deadline-exceeded-error):
  The "Context: deadline exceeded" error occurs when requests to the Temporal Service by the Client or Worker cannot be completed.
  This can be due to network issues, timeouts, server overload, or Query errors.
- [Troubleshoot the Failed Reaching Server Error](/troubleshooting/last-connection-error): The message "Failed reaching server: last connection error" often happens due to an expired TLS certificate or during the Server startup process when Client requests reach the Server before roles are fully initialized.

---

## Troubleshoot the failed reaching server error

The message `Failed reaching server: last connection error` can often result from an expired TLS certificate or during the Server startup process, in which the Client requests reach the Server before the roles are fully initialized.

This troubleshooting guide shows you how to do the following:

- Verify the certification expiration date
- Renew the certification
- Update the server configuration

### Verify TLS certification expiration date

The first step in troubleshooting this error is to verify the expiration date of the TLS certification.
Then you can renew the certification and update the server configuration.

Choose one of the following methods to verify the expiration date of the TLS certification:

**Verify the expiration date of the TLS certification**

List the expiration date with the following command:

```command
tcld namespace accepted-client-ca list \
    --namespace <namespace_id>.<account_id> | \
    jq -r '.[0].notAfter'
```

If the returned date is in the past, the certificate has expired.

**Existing certificate management infrastructure**

If you are using an existing certificate management infrastructure, use it to verify the TLS connection.
For example, if you are using OpenSSL, run the following command:

```command
openssl s_client -connect <namespace_grpc_endpoint> -showcerts -cert ~/certs/path.pem -key .~/certs/path.key -tls1_2
```

**Self-signed certificate**

If you are using a self-signed certificate, run the following Temporal CLI command:

```command
temporal namespace describe \
    --namespace <namespace_id>.<account_id> \
    --address <namespace_grpc_endpoint> \
    --tls-cert-path <path-to-mTLS-pem-file> \
    --tls-key-path <path-to-mTLS-key-file>
```

Your Namespace gRPC endpoint is available on the details page for your [Temporal Cloud Namespace](https://cloud.temporal.io/namespaces).

### Renew TLS certification

If the certificate has expired or is about to expire, the next step is to renew it.

You can do this by contacting the certificate authority (CA) that issued the certificate and requesting a renewal.

**Existing certificate management infrastructure**

If you are using an existing certificate management infrastructure, contact the administrator of the infrastructure to renew the certificate.

**Self-signed certificate**

If you are using a self-signed certificate or don't have an existing infrastructure, you can generate a new certificate using OpenSSL, [step CLI](https://github.com/smallstep/cli), or similar tools.

For information on generating a self-signed certificate, see [Control authorization](/cloud/certificates#control-authorization).

### Update the CA certification in the server configuration

Update the new CA certificate in the Temporal Cloud server configuration.

You can update certificates using any of the following methods:

- [Update certificates using Temporal Cloud UI](/cloud/certificates#update-certificates-using-temporal-cloud-ui)
- [Update certificates using tcld](/cloud/certificates#update-certificates-using-tcld)

After you update the TLS certification in the server configuration, retry your connection.

### Set reminders

Don't let your certificates expire.
Add reminders to your calendar to issue new CA certificates well before the expiration dates of the existing ones.

### Additional resources

The preceding steps should help you troubleshoot the `failed reaching server: last connection error` error caused by an expired TLS certificate.

If this issue persists, verify that the Client you are using to connect to the server is using the correct TLS certification and that the Client requests reach the server after the roles are fully initialized.
If you still need help, [create a support ticket](/cloud/support#support-ticket).

---

## Performance bottlenecks troubleshooting guide

This guide outlines common performance bottlenecks in Temporal Workers and Clients.
It covers key latency metrics and root causes of high values, and provides diagnostic steps and troubleshooting strategies.
These metrics can help you optimize Temporal deployments and Workflow execution.

To get the most out of this guide, you should be familiar with [Temporal architecture](/temporal), [Workflows](/workflows), [Activities](/activities), and [Task Queues](/task-queue).
You should also know how to use key metrics like latency, counter, rate, CPU utilization, and memory usage.

## Task processing metrics

These metrics provide insights into various stages of the [Task](/tasks) lifecycle, from scheduling to completion.
The following sections detail common metrics, their potential causes for high latency or resource depletion, and strategies for diagnosing and resolving performance issues.

### `temporal_workflow_task_schedule_to_start_latency` spike

High [`temporal_workflow_task_schedule_to_start_latency`](/references/sdk-metrics#workflow_task_schedule_to_start_latency) (P95 higher than one second) can be caused by several factors.
This metric represents the time between when a [Workflow Task](/tasks#workflow-task) is scheduled (enqueued) and when it is picked up by a Worker for processing. Here are some potential causes:

- Insufficient Worker capacity: If there aren't enough Workers or if the Workers are overloaded, they may not be able to pick up Tasks quickly enough. This can lead to Tasks waiting longer in the queue ([Detect Task Backlog](https://docs.temporal.io/cloud/worker-health#detect-task-backlog)).
- Worker configuration issues: Improperly configured Workers, such as having too few pollers or Task slots, can lead to increased latency ([Detect Task Backlog](https://docs.temporal.io/cloud/worker-health#detect-task-backlog)).
- High Workflow lock latency: If many updates are made to a single execution, this can cause Workflow lock latency, which in turn affects the Schedule-to-start latency. Reduce the rate of Signals.
- Network latency: Workers in a different region from the Temporal cluster, or large payload size, can introduce additional latency.

To diagnose and address high `temporal_workflow_task_schedule_to_start_latency`, you should:

1. Check Worker CPU and memory usage.
1. Review Worker configuration (number of pollers, Task slots, etc.).
1. Look for any spikes in Workflow or Activity starts that might be overwhelming the system.
1. Ensure Workers are in the same region as the Temporal cluster if possible.

### `temporal_activity_schedule_to_start_latency` spike

High [`temporal_activity_schedule_to_start_latency`](/references/sdk-metrics#activity_schedule_to_start_latency) (P95 higher than one second) can be caused by several factors.
This metric represents the time between when an [Activity Task](/tasks#activity-task) is scheduled (enqueued) and when it is picked up by a Worker for processing.
Here are some potential causes:

- Insufficient Worker capacity: If there aren't enough Workers or if the Workers are overloaded, they may not be able to pick up Tasks quickly enough. This can lead to Tasks waiting longer in the queue ([Detect Task Backlog](https://docs.temporal.io/cloud/worker-health#detect-task-backlog)).
- Worker configuration issues: Improperly configured Workers, such as having too few pollers or Task slots, can lead to increased latency ([Detect Task Backlog](https://docs.temporal.io/cloud/worker-health#detect-task-backlog)).
- Task Queue configuration: Setting `TaskQueueActivitiesPerSecond` too low can limit the rate at which Activities are started, leading to increased Schedule-to-start latency.
- Network latency: Workers in a different region from the Temporal cluster, or large payload size can introduce additional latency.

To diagnose and address high `temporal_activity_schedule_to_start_latency`:

1. Check Worker CPU and memory usage.
1. Review Worker configuration (number of pollers, Task slots, etc.).
1. Look for any spikes in Workflow or Activity starts that might be overwhelming the system.
1. Ensure Workers are in the same region as the Temporal cluster if possible.

### `temporal_workflow_endtoend_latency` spike

The [`temporal_workflow_endtoend_latency`](/references/sdk-metrics#workflow_endtoend_latency) metric represents the total Workflow Execution time from Schedule to the closure for a single Workflow Run.
Normal ranges for this metric depend on the use case, but here are some potential causes for the unexpected spikes:

- Complex Workflows: If the Workflows have many Activities or if the Activities take a long time to execute.
- Workflow and Activity retries: If Workflows or Activities are configured to retry upon failure and they fail often, this can increase the end-to-end latency as the system will wait for the retry delay before reattempting the failed operation.
- Worker capacity and configuration: If there aren't enough Workers or if the Workers are overloaded, they may not be able to pick up and process Tasks quickly enough. This can lead to Tasks waiting longer in the queue, thereby increasing the end-to-end latency ([Detect Task Backlog](https://docs.temporal.io/cloud/worker-health#detect-task-backlog)).
- External dependencies: If your Workflows or Activities depend on external systems or services (such as databases or APIs) and these systems are slow or unreliable, they can increase the end-to-end latency.
- Network latency: Workers in a different region from the Temporal cluster can introduce additional latency.

To diagnose and address high `temporal_workflow_endtoend_latency`:

1. Review your Workflow and Activity designs to ensure they are as efficient as possible.
2. Monitor your Workers to ensure they have sufficient capacity (CPU and memory) and are not overloaded.
3. Monitor your external dependencies to ensure they are performing well.
4. Ensure Workers are in the same region as the Temporal cluster if possible.

### High `temporal_workflow_task_execution_latency`

The [`temporal_workflow_task_execution_latency`](/references/sdk-metrics#workflow_task_execution_latency) metric represents the time taken by a Worker to execute a Workflow Task.
The Temporal SDK raises a “Deadlock detected during Workflow run” error or [TMPRL1101](https://github.com/temporalio/rules/blob/main/rules/TMPRL1101.md) when a Workflow Task takes more than one or two seconds to complete.
Here are some potential causes:

- CPU-intensive work: Performing CPU-intensive operations in your Workflow Task can lead to slow execution.
- Slow local Activities: Workflow Task execution time includes the Local Activity execution time.
- Slow Workflow replay: Workflow Task execution time includes the Workflow Replay time. Refer to `workflow_task_replay_latency` for more details.
- Worker resource constraints: High CPU usage on Worker pods can lead to slower Workflow Task execution. Workers with insufficient CPU resources can cause delays.
- Infinite loops or blocking calls: Workflow code with infinite loops or blocking external API calls can cause the Workflow Task to execute slowly or time out.
- Slow data conversion: Your custom Data Converter is taking too long to encode/decode payloads, for example, when talking to a remote encryption service.

To diagnose and address slow Workflow Task execution, you can:

1. Monitor Worker CPU and memory utilization.
2. Ensure that your Workers have adequate resources and are properly scaled for your workload.
3. Consider running your Workflow code in a profiler using a replayer to see where CPU cycles are spent.
4. Review your Workflow code for potential optimizations or to remove blocking operations.
5. Disable deadlock detection for Data Converter: It does not reduce Task execution latency but does remove the “Deadlock detected during Workflow run” or TMPRL1101 error. In Go, wrap it with `workflow.DataConverterWithoutDeadlockDetection`. In Java, surround your Data Converter code with `WorkflowUnsafe.deadlockDetectorOff`.

### High `workflow_task_replay_latency`

Workflow Task replay is the process of reconstructing the Workflow's state by re-executing the Workflow code from the beginning, using the recorded Event History.
This process ensures that the Workflow can continue from where it left off, even after interruptions or failures.
[`workflow_task_replay_latency`](/references/sdk-metrics#workflow_task_replay_latency) is high if it exceeds a few milliseconds.
Here are the main causes:

- Large Event Histories: Workflows with long histories take more time to replay, as the Worker needs to process all events to reconstruct the Workflow state.
- Data Converter performance: Slow Data Converters, especially those that perform encryption or interact with external services, can impact replay.
- Large payloads: Activities or Signals with large payloads can slow down the replay process, especially if the Data Converter needs to process these payloads.
- Complex Workflow logic: Workflow code with complex logic or computationally intensive operations, such as scheduling many concurrent child Workflows or Activities, can increase replay latency.
- Frequent cache evictions: If workers often evict Workflow Executions from their cache (due to memory constraints or frequent restarts), it leads to more replays and higher latency.
- Worker resource constraints: High CPU utilization or memory pressure on Worker nodes can slow down the replay.

To diagnose and address slow Workflow Task replay, you can:

1. Monitor SDK Metrics: Keep a close eye on the `temporal_workflow_task_replay_latency` metric. This histogram metric measures the time it takes to replay a Workflow Task.
1. Analyze Workflow History Size: Check the number of events in your Workflow histories and consider using the "Continue-As-New" feature for long-running Workflows.
1. Optimize Data Converters: If you're using custom Data Converters, especially for encryption or complex serialization, look for opportunities to optimize their performance.
1. Review Payload Sizes: Large Activity or Signal payloads can slow down replay. Consider optimizing the size of data being passed in your Workflows.
1. Profile Workflow Code: Use a profiler to identify CPU-intensive parts of your Workflow code that might be slowing down replay.
1. Manage Worker Cache: Frequent cache evictions can lead to more replays. Tune your Worker's cache size and eviction policies.

### `temporal_activity_execution_latency` spike

The [`temporal_activity_execution_latency`](/references/sdk-metrics#activity_execution_latency) metric measures the time from when a Worker starts processing an Activity Task until it reports to the service that the Task is complete or failed.
There are several potential causes for high `temporal_activity_execution_latency`:

- Activity implementation: The most common cause of high Activity Execution latency is the actual implementation of the Activity itself. If the Activity is performing time-consuming operations or making slow external API calls, it will take longer to execute.
- External dependencies: If your Activity is constrained by an external resource or service that all Activities access, it could cause increased latency.
- Worker resource constraints: Under-resourced Worker nodes or experiencing high CPU utilization can lead to slower Activity Execution.
- Network latency: High latency between your Workers and external services or the Temporal service itself can contribute to increased Activity Execution time.

To diagnose and address high Activity Execution latency:

1. Monitor the `activity_execution_latency` metric, which you can filter by Activity type and Activity Task queue.
2. Optimize your Activity implementation to reduce latency, especially with external services or database interactions.
3. Check your Worker CPU and memory utilization to make sure they have adequate resources.
4. Examine your Worker configuration, particularly `(Max)ConcurrentActivityExecutionSize` and `(Max)WorkerActivitiesPerSecond`, to ensure they are not limiting your activity execution.

### Depletion of `temporal_worker_task_slots_available` for `WorkflowWorker`

The [`temporal_worker_task_slots_available{worker_type=”WorkflowWorker”}`](/references/sdk-metrics#worker_task_slots_available) metric indicates the number of available slots for executing Workflow Tasks on a Worker.
This metric may go to zero for several reasons:

- High Workflow Task Load: If there are more Tasks than the Worker can handle concurrently, the available slots will be depleted. This can happen if the rate of incoming Tasks is higher than the rate at which tasks are being completed.
- Worker Configuration: The number of available slots is determined by the Worker configuration, specifically the `MaxConcurrentWorkflowTaskExecutionSize` setting. If these are set too low, the Worker may not have enough slots to handle the Task load.
- High `temporal_workflow_task_execution_latency` and `workflow_task_replay_latency`.

To prevent depletion of Workflow Task slots:

1. Monitor Worker CPU and Memory usage while increasing `(Max)ConcurrentWorkflowTaskExecutionSize` to add more execution slots.
2. Scale up Workers both vertically (increasing CPU and Memory) and horizontally (increasing Worker instances).

### Depletion of `temporal_worker_task_slots_available` for `ActivityWorker`

The [`temporal_worker_task_slots_available{worker_type=”ActivityWorker”}`](/references/sdk-metrics#worker_task_slots_available) metric indicates the number of available slots for executing Activity Tasks on a Worker.
This metric may go to zero for several reasons:

- Blocked Activities and Zombie Activities: The most common cause is activities that are blocked or not returning on time. Zombie Activities are a subset of this category. They occur when an Activity times out (hits its `StartToClose` or `HeartbeatTimeout` timeout) and has stopped Heartbeating but continues to run, occupying some or all the slots as more retries occur. This can happen if:
  - The Activity code is blocking on a downstream service call or an infinite loop.
  - There's a mismatch between the Activity's `StartToClose` timeout and any client-side timeouts for external calls.
- Resource Utilization: High CPU or memory usage on Workers can cause activities to block and not release slots.

To prevent depletion of Activity Task slots:

1. Monitor Worker CPU and Memory usage while increasing `(Max)ConcurrentActivityExecutionSize` to add more execution slots.
2. Add client-side timeout to your downstream API client.
3. Review your Task code to ensure Tasks complete within a reasonable time measured by `temporal_activity_execution_latency`.

## Network requests

Network issues can impact Temporal clients and workers, leading to delays, failures, and overall system instability.
This section focuses on metrics that reveal common network-related problems with your Temporal deployment, specifically related to network connectivity, latency, and request failures.
These metrics can indicate where bottlenecks exist within the communication channels between Temporal clients (including Temporal Workers) and the Temporal server.

### High `temporal_long_request_failure`

The [`temporal_long_request_failure`](/references/sdk-metrics#long_request_failure) metric counts the number of failed RPC long poll requests for `PollWorkflowTaskQueue`, `PollActivityTaskQueue`, and `GetWorkflowExecutionHistory` (when polling new events). High values of this metric can be caused by several factors:

- Network Issues: Problems with the network connection between the Temporal Client and the Temporal Server, including firewalls and proxies, can cause long poll requests to fail.
- Rate Limiting: If the rate of requests exceeds the configured limits on the Temporal Server or Temporal Cloud, additional requests may be rejected, increasing the `temporal_long_request_failure` count. This is often indicated by a `ResourceExhausted` status code.
- Server Errors: If the Temporal Server is experiencing issues, it may fail to respond to long poll requests correctly, leading to an increase in `temporal_long_request_failure`.

To diagnose the cause of high `temporal_long_request_failure`, you can:

1. Check the operation and the status or code tag of the `temporal_long_request_failure` metric to see the type of errors that are occurring.
2. If you receive a `ResourceExhausted` status code, review the rate limits configured on the Temporal Server or ask for help from Temporal Support for Temporal Cloud.
3. Check the network connection between the Temporal Client and the Temporal Server.

### High `temporal_request_failure_total`

The [`temporal_request_failure_total`](/references/sdk-metrics#request_failure) metric counts the number of RPC requests made by the Temporal Client that have failed.
High values of this metric can be caused by several factors:

- Network Issues: Problems with the network connection between the Temporal Client and the Temporal Server can cause requests to fail.
- Client Errors: If there's an issue with the Temporal Client, such as misconfiguration or resource exhaustion, it may fail to make requests correctly.
- Operation Errors: Specific operations like `SignalWorkflowExecution` or `TerminateWorkflowExecution` can fail if they are trying to act on a closed Workflow Execution that no longer exists (because it completed and was removed from persistence when it hit Namespace retention time).
- Rate Limiting: If the rate of requests exceeds the configured limits on the Temporal Server, additional requests may be rejected, increasing the counter. This is often indicated by a `ResourceExhausted` status code.
- Request Size Limit: If the Worker tries to return an Activity response that is larger than the blob size limit (2MB), the service will reject it, causing a request failure.
- Server Errors: If the Temporal Server is experiencing issues, it may fail to respond to requests correctly, leading to an increase in `temporal_request_failure_total`.

To diagnose the cause of high `temporal_request_failure_total`, you can:

1. Check the status or code tag of the `temporal_request_failure_total` metric to see the type of errors that are occurring.
2. Look at the operation tag of the `temporal_request_failure_total` metric to see which operations are failing.
3. Monitor the Temporal Server logs and the Temporal Client logs for any error messages or warnings.
4. Check the network connection between the Temporal Client and the Temporal Server.

### High `temporal_request_latency`

The [`temporal_request_latency`](/references/sdk-metrics#request_latency) metric measures the latency of gRPC requests made by the Temporal Client.
High values for this metric can be caused by several factors:

- Network Latency: The physical distance and network conditions between the Temporal Client and the Temporal Server can affect the latency of requests.
- Network Transfer Time: Larger payloads take longer to transfer over the network, which affects request latency. For example, large payloads in `RespondWorkflowTaskCompleted` can affect the latency of the request. This is especially true when Workflows are scheduling multiple activities with large inputs.
- Resource Exhaustion: Running out of resources (such as CPU or memory) on the client or server can cause delays in processing the request.
- Client Configuration: Improper client configuration, such as setting thread pool sizes too aggressively or having memory constraints that are too low for the number of allocated threads, can lead to situations where Tasks overwhelm the client, causing increased latency.
- Server Load: If the Temporal Server is under heavy load, it may take longer to respond to requests, leading to increased latency.

To diagnose and address high `temporal_request_latency`:

1. Monitor the `temporal_request_latency` metric to identify when and where latency spikes are occurring.
2. Check the network connection between the Temporal Client and the Temporal Server.
3. Monitor the resource usage on both the Temporal Client and the Temporal Server.
4. Review your Temporal Client configuration to ensure it is optimized for your workload.
5. If you're using Temporal Cloud, check if the Cloud’s [service-latency](https://docs.temporal.io/cloud/metrics/reference#service-latency) metric spikes up and reach out to Temporal Support for help.

### `rate(temporal_long_request_total{operation="PollActivityTaskQueue"})`

The [`rate(temporal_long_request_total{operation="PollActivityTaskQueue"})`](/references/sdk-metrics#long_request) expression measures the per-second average rate of `PollActivityTaskQueue` long poll requests over a certain period of time.

`PollActivityTaskQueue` is an operation where Workers poll for Activity Tasks from the Task Queue.
The `temporal_long_request_total` metric counts the number of these long poll requests.

By applying the `rate()` function in Prometheus, you can calculate the per-second average rate of these requests over the time range specified in the Query.
This can help you understand the load on your Temporal service and how often your Workers are polling for Activity Tasks.

### `rate(temporal_long_request_total{operation="PollWorkflowTaskQueue"})`

The [`rate(temporal_long_request_total{operation="PollWorkflowTaskQueue"})`](/references/sdk-metrics#long_request) expression measures the per-second average rate of `PollWorkflowTaskQueue` long poll requests over a certain period of time.

`PollWorkflowTaskQueue` is an operation where Workers poll for Workflow Tasks from the Task Queue.
The `temporal_long_request_total` metric counts the number of these long poll requests.

By applying the `rate()` function in Prometheus, you can calculate the per-second average rate of these requests over the time range specified in the query.
This can help you understand the load on your Temporal service and how often your Workers are polling for Workflow Tasks.

## Caching

Temporal Workers relies on caching to optimize performance by reducing the overhead of fetching Workflow state from the history and Replaying.
However, unlimited caching is impossible; there's a trade-off between the benefits of cached data and the memory consumed.
These metrics allow you to balance performance gains with responsible memory usage.

### `temporal_sticky_cache_size`

The [`temporal_sticky_cache_size`](/references/sdk-metrics#sticky_cache_size) metric represents the number of Workflow executions currently cached in a Worker's memory.

The sticky cache is used to improve performance by keeping the Workflow state in memory, reducing the need to reconstruct the Workflow from its Event History for every Task.
It’s particularly useful for latency-sensitive Workflows.

There is a direct relationship between the sticky cache size and Worker memory consumption.
As the cache size increases, so does the memory usage of the Worker.

The maximum size of the sticky cache can be configured. For example, the default in the Go SDK is 10,000 Workflows.

A larger sticky cache can improve performance by reducing the need to replay Workflow histories.
However, it also increases memory usage, which can lead to issues if not properly managed.

Monitor this metric alongside Worker memory usage.
A sudden increase in `sticky_cache_size` can correlate with increased memory consumption and potential performance issues.

If memory consumption is too high, you can reduce the maximum sticky cache size.
Conversely, if you have available memory and want to improve performance, you might increase it.

### `temporal_sticky_cache_hit_total` and `temporal_sticky_cache_miss_total`

The [`temporal_sticky_cache_hit_total`](https://docs.temporal.io/references/sdk-metrics#sticky_cache_hit) metric is a counter that measures the total number of times a Workflow Task found a cached Workflow Execution to run against, and
the opposite is [`temporal_sticky_cache_miss_total`](https://docs.temporal.io/references/sdk-metrics#sticky_cache_miss), which is a counter that measures the total number of times a Workflow Task did not find a cached Workflow Execution to run against.

Sticky Execution is a feature where a Worker caches a Workflow Execution and creates a dedicated Task Queue to listen on.
This improves performance because the Temporal Service only sends new events to the Worker instead of entire Event Histories, and the Workflow doesn't have to Replay.

A “hit” means the Worker finds the Workflow in its cache when processing a Workflow Task, allowing immediate processing without fetching the full Event History from the server and Replaying.
A "miss" means the Worker didn't find the Workflow in its cache, and it must fetch the Event History and Replay.

Monitoring these two metrics and comparing them can help you understand how your sticky cache is being used.
A high rate of cache hits with a low rate of cache misses indicates that your Workflows are being scheduled efficiently, with minimal need for fetching Event Histories and Replaying.

### `temporal_sticky_cache_total_forced_eviction_total`

The [`temporal_sticky_cache_total_forced_eviction_total`](https://docs.temporal.io/references/sdk-metrics#sticky_cache_hit) metric is a counter that measures the total number of Workflow Executions that have been forcibly evicted from the sticky cache.

Sticky Execution is a feature where a Worker caches a Workflow Execution and creates a dedicated Task Queue to listen on.
This improves performance because the Temporal Service only sends new events to the Worker instead of entire Event Histories, and the Workflow doesn't have to Replay.

A "forced eviction" in this context means that a Workflow Execution was removed from the cache before it completed, typically because the cache was full and needed to make room for other Workflow Executions.
This means that if the Worker needs to process more Tasks for the evicted Workflow Execution, it will have to fetch the entire Event History from the Temporal Service and Replay.

Monitoring the `temporal_sticky_cache_total_forced_eviction_total` metric can help you understand how often your Workflows are being evicted from the cache.
A high rate of forced evictions could indicate that your cache size is too small for your workload, and you may need to increase the `WorkflowCacheSize` setting if your Worker resources can accommodate it.

---

## Use These Docs with AI


Connect Temporal documentation directly to your AI assistant for accurate, up-to-date answers about Temporal.
The Temporal docs MCP server gives AI tools real-time access to our documentation, so responses draw from current docs rather than training data.

The server requires anonymous authentication using any Google account to enforce rate limits and prevent abuse.
We cannot see nor do we collect any contact information from this.

## Claude Code

Add the Temporal docs MCP server to Claude Code with a single command:

```bash
claude mcp add --scope user --transport http temporal-docs https://temporal.mcp.kapa.ai
```

This adds the server globally so it's available in all your projects.

To add it to a specific project only (stored in `.mcp.json`):

```bash
claude mcp add --transport http temporal-docs https://temporal.mcp.kapa.ai
```

After adding, restart Claude Code and run `/mcp` to authenticate with your Google account.

## Claude Desktop

1. Open Claude Desktop settings
2. Navigate to **Settings > Connectors**
3. Add a new MCP server with the URL: `https://temporal.mcp.kapa.ai`

## Other MCP-compatible tools

For any tool that supports the Model Context Protocol, use the following server URL:

```
https://temporal.mcp.kapa.ai
```

Configuration format varies by tool. Here's a generic JSON configuration:

```json
{
  "mcpServers": {
    "temporal-docs": {
      "transport": "http",
      "url": "https://temporal.mcp.kapa.ai"
    }
  }
}
```