Skip to content

For the complete documentation index, see llms.txt.

Schedule triggers

A schedule trigger runs standing instructions you write on a repeating cron schedule, with no triggering event. It works like an API trigger with a clock attached. Each time a scheduled time comes due, Promptless runs your instructions against your docs and connected context sources. It creates suggestions when the docs need an update, and otherwise finishes quietly.

Use a schedule trigger to:

  • Check every week that your release notes reflect what shipped.
  • Audit a changelog against a release-notes page.
  • Sweep for documentation drift that no single event would catch.
  • At least one active doc collection and a saved configuration. Promptless drops a scheduled run when either is missing.
  • An organization admin role, to create or edit triggers.
  • Every repository and context source your instructions name, connected through source control and context sources so Promptless can read them.

Set up a schedule trigger in the dashboard

Section titled “Set up a schedule trigger in the dashboard”
  1. On the Configuration page, select the Triggers tab.

  2. Select Add an automatic or scheduled trigger.

  3. Under On a schedule, select A recurring schedule.

  4. Under When should Promptless run?, select a preset or enter a five-field cron expression. The help text describes the schedule. For Every 2 hours, it ends with “Runs every 2 hours, on the hour.”

    PresetCron expression
    Every 2 hours0 */2 * * *
    Every day at 9am0 9 * * *
    Every weekday at 9am0 9 * * 1-5
    Every Monday at 9am0 9 * * 1
    First of the month0 9 1 * *
  5. Under In which timezone?, select the timezone the schedule runs in. It defaults to UTC.

  6. Under What should Promptless do each time?, enter your standing instructions.

  7. Select Add trigger.

The schedule runs at its next matching time after you save. Promptless doesn’t run it for times that have already passed.

For precise control, add the schedule trigger to the triggers section of your promptless.yaml file:

triggers:
weekly-release-notes-check:
trigger_type: schedule
match:
- cron: "0 9 * * 1"
timezone: America/Los_Angeles # optional; defaults to UTC
instructions: |
Compare the changelog in acme/api against docs/release-notes.md and open a
suggestion for anything that shipped but isn't documented.

The trigger takes these fields:

FieldDescription
trigger_typeSet to schedule.
cronRequired. Five-field cron expression inside a match clause. Runs at most once an hour.
timezoneOptional. IANA timezone name inside a match clause. Defaults to UTC.
instructionsRequired, non-empty. The standing instructions Promptless runs each time.

instructions sits alongside match, outside any clause, because one set of instructions covers every clause. Each match clause is a cron and timezone pair, and the trigger needs at least one. Add clauses to run the same instructions on several cadences, for example Mondays and Thursdays at 9am:

triggers:
twice-weekly-check:
trigger_type: schedule
match:
- cron: "0 9 * * 1"
timezone: America/Los_Angeles
- cron: "0 9 * * 4"
timezone: America/Los_Angeles
instructions: |
Compare the changelog in acme/api against docs/release-notes.md and open a
suggestion for anything that shipped but isn't documented.

The standing instructions are the whole job, because no pull request or message describes the work. Name the repositories and files to compare, and say what to open a suggestion for.

Instructions can’t be empty, and they have no maximum length. Promptless trims leading and trailing whitespace.

A schedule uses a standard five-field cron expression: minute, hour, day of month, month, and day of week. Promptless rejects six-field expressions that add seconds, and shorthand aliases such as @daily.

A schedule can run at most once an hour. Promptless checks the expression’s actual run times. It rejects any expression that would run more than once in an hour, however the expression is written.

AcceptedRejected (too frequent)
0 9 * * 1*/5 * * * *
0 9 * * *0,30 * * * *
0 * * * *0-10 * * * *
0 9,10 * * ** * * * *
0 9 1 * *
30 2 * * 1-5

The timezone is an optional IANA name, such as America/Los_Angeles, and defaults to UTC. A schedule keeps its wall-clock time across daylight-saving changes. A schedule set for 9am local runs at 9am local through both spring-forward and fall-back.

  • Promptless skips a missed occurrence. If Promptless is briefly unavailable when a scheduled time passes, it doesn’t run that occurrence later.
  • If an earlier run of the same schedule is still in progress, Promptless skips the next occurrence.
  • A run that finds nothing worth changing finishes with no suggestion and no notification.
  • A scheduled run goes through the same pipeline as every other trigger. Its suggestions follow your policies for publishing and notifications, and a policy rule can target it by its trigger key.

Scheduled runs appear on the Triggers page like any other trigger, labeled as a scheduled run. Each entry shows when the occurrence ran and what it produced.