pithy workflow

Start a Workflow by hand, list the Workflows your Workers compose, and follow one instance, in a deployed environment.

A job is a Workflow your app or a kit capability declares — adding a scheduled job is how you declare one, and durable jobs is why the kit runs slow work that way. This command starts one without waiting for its cron: a backfill, a rerun, a check that a job deployed.

Synopsis

pithy workflow trigger <job> --env <name> [--worker <name>] [--params <json>] [--id <id>] [--confirm <phrase>] [--dry-run] [--json]
pithy workflow list --env <name> [--worker <name>] [--json]
pithy workflow status <job> <instance> --env <name> [--worker <name>] [--json]

Naming a job

A job is named by its <capability>/<job> key: stats/collect for a job your app capability stats declares, storage/sweep for one a kit capability declares. The bare job name works too, collect, when exactly one capability the Worker composes declares a job by that name. When two do, the refusal lists both keys to pick from. A name that matches nothing is refused with every key the Worker has.

The job is looked up in the Worker’s composed registry, the same one its scheduled handler and c.var.workflows.trigger start from, so an app job and a kit capability’s job are named and started the same way. The deployed Workflow it runs under is <project>-<env>-<capability>-<job> (naming and limits), with the Worker’s own host in the name when that Worker owns what its capability’s host binds: acme-staging-api---storage-sweep for an apps/api that lists DB and STORAGE_BUCKET in ownBindings. A job with no class of its own, which your Worker hosts from an entry you wrote (payments/usage, auth/purge, or an optional app job), runs under the name that entry gives its binding in the environment’s stanza of wrangler.jsonc, and under the owner-less <project>-<env>-<capability>-<job> when the stanza has no entry for it. You never type that name; pithy workflow list prints it.

pithy workflow trigger

Starts one instance of a job’s deployed Workflow, and prints its instance id. It does not wait for the Workflow to finish.

Flags

FlagDefaultPurpose
<job>requiredThe job: its <capability>/<job> key, or its bare name
--env <name>requiredThe deployed environment: staging, prod, or one declared in pithy.config.ts. dev is refused: there is no deployed Workflow to start
--worker <name>the project’s only WorkerThe Worker that composes the job. Required when the project has more than one
--params <json>{}The instance’s params, as one JSON value: '{"backfill":true}'. Parsed through the job’s own params schema first, so a schema with defaults fills in what you leave out
--id <id>the job’s instanceId, else Cloudflare’sName the instance: 1 to 100 letters, digits, dashes or underscores
--confirm <phrase>noneUnlock a production environment without a prompt: "yes, i really want to trigger <env>"
--dry-runfalseResolve, validate and print what would start, without starting it
--jsonfalseMachine-readable output — one JSON line

What it checks before anything is sent

--params is parsed as JSON and then through the job’s params schema, before any network call. A value the Workflow would refuse is refused here, validation/invalid_input, with the schema’s message naming each field: --params does not fit stats/collect: backfill: Invalid input: expected boolean, received string. --id is held to Cloudflare’s rule for an instance id the same way.

Instance ids

The id an instance starts under is --id, else the job’s spec instanceId (called with the time now and the parsed params), else none, and Cloudflare generates one. A Workflow holds one instance per id, so an id that is taken is refused, core/conflict, with the pithy workflow status line that follows the instance already holding it. A job whose instanceId names its instances by day therefore runs once per day by hand as on its schedule; pass --id to run it again.

Production

A production environment — prod, production, or any name in seed.productionEnvironments — needs the exact phrase yes, i really want to trigger <env>, compared case-insensitively. At a terminal it is asked for. A run that may not prompt (--json, --no-input, PITHY_NONINTERACTIVE=1, or no terminal) needs --confirm with the phrase, and without it is refused core/person_required, exit 5, before anything is sent (exit codes). The phrase is a person’s to give: an agent that meets the refusal stops and asks. Any other environment starts without asking. --dry-run asks for nothing.

--dry-run

Resolves the job, the Worker and the Workflow name, validates --params and --id, and starts nothing. With an id, from --id or the job’s instanceId, it also asks Cloudflare whether that id is taken, and refuses it as the real run would. It reads the project’s Cloudflare credentials either way. Under --json the payload carries plan (below).

--json

One line on stdout.

KeyTypeMeaning
commandstring"workflow trigger"
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
envstringThe environment the Workflow runs in
workerstringThe Worker that composes the job, by its apps/ directory
jobstringThe job’s <capability>/<job> key, whichever spelling was typed
workflowstringThe deployed Workflow the instance runs under
instanceIdstring | nullThe instance id. null only under --dry-run when Cloudflare would pick it
dryRunbooleanWhether this was --dry-run. Nothing was started when it is true
planobjectPresent only under --dry-run, in the shape every --dry-run shares: one write under data with store: "workflow" and the Workflow as its target, and a note naming the instance id, or saying Cloudflare picks it

pithy workflow list

Lists every job each Worker composes, with its deployed Workflow name in the environment and its schedule. It reads the project only and never reaches Cloudflare, so it says what the composition declares, not what is deployed.

FlagDefaultPurpose
--env <name>requiredThe environment the Workflow names are for
--worker <name>every WorkerList one Worker’s jobs
--jsonfalseMachine-readable output — one JSON line

One line per job, Worker by Worker and each Worker’s jobs by key: the Worker, the key, the Workflow, and cron <expression> or on trigger. A project with no Workflow prints No Worker composes a Workflow.

--json

KeyTypeMeaning
commandstring"workflow list"
schemaVersionintegerThe version of this payload’s shape
envstringThe environment the Workflow names are for
jobsobject[]Every job each Worker composes, Worker by Worker. Empty when none does
jobs[].workerstringThe Worker that composes it, by its apps/ directory
jobs[].keystringThe job’s <capability>/<job> key
jobs[].capabilitystringThe capability that declares it: a kit capability, or the Worker’s app
jobs[].jobstringThe job name
jobs[].bindingstringThe Workflow binding the Worker reaches it by
jobs[].schedulestring | nullIts cron, or null for a job that runs only when triggered
jobs[].workflowstringIts deployed Workflow name in the environment

pithy workflow status

Reports one instance: its state, its output once it completes, and why it failed when it did.

FlagDefaultPurpose
<job>requiredThe job: its <capability>/<job> key, or its bare name
<instance>requiredThe instance id the trigger printed
--env <name>requiredThe environment the instance runs in
--worker <name>the project’s only WorkerThe Worker that composes the job
--jsonfalseMachine-readable output — one JSON line

The first line is <key> <instance> in <env>: <status>. A failure adds Step <name> failed: <reason>, or Failed: <reason> when no step is named, and a completed instance adds Output: <json>. The command reports the state and exits 0 whatever it is: an errored instance is an answer, not a failed call.

--json

KeyTypeMeaning
commandstring"workflow status"
schemaVersionintegerThe version of this payload’s shape
envstringThe environment the Workflow runs in
workerstringThe Worker that composes the job, by its apps/ directory
jobstringThe job’s <capability>/<job> key
workflowstringThe deployed Workflow the instance runs under
instanceIdstringThe instance id
statusstringThe instance’s lifecycle state, as Cloudflare reports it: queued, running, paused, waiting, complete, errored, terminated and the rest of its set
outputanyThe Workflow’s return value. Present once status is complete
errorstring | nullWhy it failed: the failed step’s text, else the instance’s own. null when nothing failed
failedStepstring | nullThe name of the step that failed. null when none did

Errors

Each exits by its class.

ConditionEffect
No --env, dev, or an environment the project does not declareRefused validation/invalid_input, exit 2, naming the environments it takes
A job name that matches nothing, or a bare name more than one capability declaresRefused validation/invalid_input, exit 2, listing the keys to pick from
--params that is not JSON, or does not fit the job’s schemaRefused validation/invalid_input, exit 2, with the schema’s message, before any network call
--id outside Cloudflare’s ruleRefused validation/invalid_input, exit 2
An id the Workflow already holdsRefused core/conflict, exit 3, with the pithy workflow status line for that instance. Under --dry-run too
A production environment without the phraseRefused core/person_required, exit 5, naming --confirm
status for an instance id the Workflow does not holdRefused core/not_found, exit 3. Check the id and the --env it ran in
Cloudflare credentials are missing.Exit 3, on trigger and status. Run pithy cloudflare connect, or set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN

Examples

# Backfill: start the app's collector with params its schema accepts.
pithy workflow trigger stats/collect --env staging --params '{"backfill":true}' --id backfill-1

# Follow the instance it started.
pithy workflow status stats/collect backfill-1 --env staging

# What would start in production, and under which Workflow.
pithy workflow trigger collect --env prod --dry-run --json
Started stats/collect in staging, as acme-staging-stats-collect.
Instance backfill-1. Follow it with pithy workflow status stats/collect backfill-1 --env staging --worker api.
Done.
api  stats/collect  acme-staging-stats-collect  cron 0 * * * *
api  storage/sweep  acme-staging-storage-sweep  on trigger
{"command":"workflow trigger","schemaVersion":1,"env":"staging","worker":"api","job":"stats/collect","workflow":"acme-staging-stats-collect","instanceId":"backfill-1","dryRun":false}

Canceling, pausing or retrying an instance is not here; wrangler workflows instances does those against the Workflow name pithy workflow list prints.

ESC