# tctl 1.17 schedule command reference

> The public preview of Temporal CLI is now available. Explore experimental features like scheduling Workflows in tctl v1.17 and next, including creating, backfilling, updating, and more.

> **ℹ️ 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
```

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.