Add a scheduled job

You need: a scaffolded project.

Declare it in your app capability

Durable jobs is what it becomes, pithy worker sync is what writes the cron into the stanza, reading your logs is how you watch it, and diagnosing a broken project is what to run when it never fires.

A job is a Workflow plus a schedule. You declare both, and pithy worker sync writes them into wrangler.jsonc.

pithy worker sync

Idempotent, comment-preserving, all-or-nothing. Run it as often as you like.

The rule that surprises people

A Worker has one scheduled handler for all of its crons, and it starts only the jobs whose schedule is the cron that fired, matched as written in wrangler.jsonc. A daily job beside an hourly one runs once a day, not every hour.

So the match is on the string. A declared schedule the cron list lacks never fires, and an expression nothing declares starts nothing. 0 2 * * * and 0 2 * * 0-6 are two different crons here, even where they mean the same hours.

Which is why sync sets the cron list to exactly the declared schedules, as you wrote them, rather than merging.

Name each run

Without a name, every start gets a random instance id, so nothing stops a second start from running the same work again. Give the job’s spec an instanceId and it names each instance itself.

workflows: {
  collect: {
    binding: "APP_COLLECT",
    params: z.object({}),
    schedule: "0 2 * * *",
    className: "CollectWorkflow",
    instanceId: ({ firedAt }) => firedAt.toISOString().slice(0, 10),
  },
},

instanceId receives firedAt, cron and params. firedAt is the time the cron was scheduled for, cron is the expression that fired, as written, and params is the payload after the spec’s schema parsed it. The id it returns must be at most 100 characters of [A-Za-z0-9_-].

A name built from the date runs the job once per UTC day. Cloudflare keeps one instance per id, so a second start that day asks for an id that is taken. When a cron start is refused that way, the scheduled handler logs workflow already started with the id and counts no failure.

A manual trigger can name its instance too, with c.var.workflows.trigger("<capability>/<job>", params, { id }). Without an id it falls back to the spec’s instanceId, called with the current time and no cron. A manual trigger whose id is taken rejects: only a cron start treats that as already done.

To start one from a terminal, use pithy workflow trigger. pithy workflow trigger <capability>/<job> --env staging starts the deployed Workflow with --params checked against the spec’s schema first, and takes --id the same way: without one it uses the spec’s instanceId, and an id that is taken is refused. pithy workflow status follows the instance it started.

A spec with no instanceId behaves as it always did.

Replaced, not merged

The app’s entries are replaced. A job renamed or dropped leaves — including the last one, so an app declaring no Workflows still has its stale bindings and crons taken out.

Otherwise dropping the last job would leave a fault naming a command that could not fix it.

An entry carrying a script_name belongs to a library capability’s provisioner and is never touched. Email’s send Worker, storage’s sweep, vector’s reprocess — those are provisioned, not synced. Neither is an entry you wrote for a library job your own Worker hosts, such as @pithy-sh/auth’s purge or @pithy-sh/payments’ usage pass, whose class only your entry can export. Its cron is kept when it is there and never added, and pithy doctor and pithy deploy do not count it against the app.

Nothing is invented for a project that never had either. No empty workflows key, no triggers block.

The entrypoint stays yours

The WorkflowEntrypoint subclass is yours to export from the Worker’s main. sync writes the binding and the schedule; it does not write your code.

Use durable steps

await step.do("fetch-page-1", async () => { … });

Steps are journalled, so an instance that dies resumes at the step it reached rather than starting over.

Derive step names deterministically — from a page counter, not a clock or a random source. A replay must ask for the same steps in the same order, or the journal is unusable.

Classify your faults

An unclassified throw is terminal. If a fault is genuinely retryable — an upstream that was busy, a rate limit whose next window is a different answer — raise it as a code the classifier knows, or it will never be retried.

That is not theoretical: it is exactly the bug the media capability’s enrichment hit, where the one retryable fault was the only one that never got a retry.

Pace a long walk with keyset pagination

If your job mutates the rows its own predicate selects, LIMIT/OFFSET silently skips. Page two starts at row 1,000 of a set that just lost its first 1,000 members.

Read id > cursor in id order. It cannot skip and cannot repeat, whatever the predicate does behind the cursor.

Do not reach for a timer

In a Durable Object, a single setInterval prevents hibernation entirely and bills duration continuously. Use an alarm.

In a Worker, a cron is the timer.

Logging from a job

c.var.log is a request thing. In a Workflow, build one and bind the run context to it so every record carries the instance — otherwise a failure is a line with no way back to which run produced it.

ESC