Skip to main content

tctl 1.17 schedule command reference

Temporal CLI is now available

The public preview of Temporal CLI is now available. We encourage you to begin using it and to provide feedback.

After the release of Temporal CLI v1.0, tctl will deprecate.

A Schedule is an experimental feature available in tctl 1.17 and tctl next.

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.

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

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

$ 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'

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 command for termination.

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

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​

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​

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

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

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