Workflows
Inspect and run deployed workflows, follow their status, continue eligible runs from saved checkpoints, and understand task prices and owner costs.
A workflow runs a bounded graph of tool calls and saves checkpoints as it progresses. Call an accessible deployment with the public crab CLI; authoring one is covered in Development.
Run
Replace OWNER/page-watch.page_watch with the deployed service and workflow address:
crab workflow inspect OWNER/page-watch.page_watch
crab workflow run OWNER/page-watch.page_watch '{"urls":["https://example.com/"]}' --dry-run
crab workflow run OWNER/page-watch.page_watch '{"urls":["https://example.com/"]}'Inspection resolves the graph, dependencies, call-count bounds and current terms without executing application tools. Dry-run also validates the input without creating a run.
Run prints the terms and asks for confirmation; scripts use --yes. It returns an accepted run ID without waiting for completion. Input comes from stdin when omitted.
JSON output is automatic when piped, or selected with --json; pre-execution terms stay on stderr. MCP and the HTTP API use the same admission and run model.
Status
crab workflow status OWNER/page-watch.page_watch RUN_IDStatus shows checkpoints, attempts, the result, retention expiry and continuation eligibility. On Cloud, run history is available to the owner and original authenticated initiator; detailed accounting is owner-only.
After a lost admission response, check the UUID printed before dispatch. Resend with run --id RUN_ID using identical input and accepted terms; a new UUID starts a new run.
Continue or cancel
crab workflow continue OWNER/page-watch.page_watch RUN_ID
crab workflow cancel OWNER/page-watch.page_watch RUN_IDContinuation is manual and retains the original image, input, prepared payloads, branch decisions and successful checkpoints. It gets a fresh attempt deadline and the remaining cumulative owner cap.
Current permission, original key/app funding authority and accepted dependency bindings are rechecked. An uncertain write requires the target's still-valid idempotency guarantee and original payload/key, or an authoritative recorded outcome.
Expired or deleted checkpoints cannot be continued; default retention is seven days. A changed input needs a new run.
Cancellation stops new calls and drains active calls; it cannot undo effects already accepted by external services. Both controls ask for confirmation, or accept --yes.
run, status and continue exit 2 for failed, indeterminate or cancelled outcomes. Accepted cancellation exits 0.
Cost
The fixed customer task price settles once on successful completion. Terminal failure or cancellation releases its reservation; the owner pays incurred execution costs.
The owner's cumulative Cloud managed-spend cap is separate from the customer price. Owner calls and schedules have no self-sale; continuation uses the cap remaining from earlier attempts.
The local runtime does not settle task fees. Independently billed providers remain outside the managed cap; review the service's disclosures before running it.
Storage capacity is required for checkpoints and retained images before dispatch. A spend cap does not guarantee completion; see Cost of a call for Cloud charges.
Schedules
A service can declare a schedule in its manifest; redeploying changes it. Each occurrence has a stable identity, so duplicate delivery does not create another attempt.
A scheduled occurrence has a 60-second delivery window. Delivery after that window is refused with E0075, and the workflow is not run.
Schedules do not retry failures or backfill downtime. Each later occurrence starts a new run with owner funding.
Command reference
Inspect and manage durable workflow runs
Usage: crab workflow [OPTIONS] <COMMAND>
Commands:
inspect Resolve the graph, bounds and current quote without executing it
run Admit one run and return its identity; use status to follow it
status Read a run's checkpoints, result and continuation eligibility
continue Continue an eligible run using its original input and saved checkpoints
cancel Stop new calls; an external request already accepted cannot be recalled
help Print this message or the help of the given subcommand(s)
Options:
--context <CONTEXT> The context to talk to, in place of the one in use
--org <ORG> Act for this org, by handle or id, in place of the context's account
--json Print JSON. On whenever stdout is not a terminal
-y, --yes Confirm terminal prompts. Commands with terminal prompts refuse without a terminal unless this is given. Cloud deploys with --yes require an API key with deployments:write; CLI sessions use browser approval instead
-h, --help Print helpcrab workflow inspect
Resolve the graph, bounds and current quote without executing it
Usage: crab workflow inspect [OPTIONS] <TARGET>
Arguments:
<TARGET> A service and workflow, `owner/service.workflow` on Cloud
Options:
--caller <CALLER> On the local host, override the default caller `local`
--context <CONTEXT> The context to talk to, in place of the one in use
--anonymous On the local host, call without a caller
--org <ORG> Act for this org, by handle or id, in place of the context's account
--issuer <ISSUER> On the local host, the end user's issuer (unchecked)
--json Print JSON. On whenever stdout is not a terminal
--user <USER> On the local host, the end user's subject (unchecked)
-y, --yes Confirm terminal prompts. Commands with terminal prompts refuse without a terminal unless this is given. Cloud deploys with --yes require an API key with deployments:write; CLI sessions use browser approval instead
-h, --help Print helpcrab workflow run
Admit one run and return its identity; use status to follow it
Usage: crab workflow run [OPTIONS] <TARGET> [INPUT]
Arguments:
<TARGET>
[INPUT] JSON input; read stdin when omitted, or use {} with an empty stdin
Options:
--context <CONTEXT> The context to talk to, in place of the one in use
--dry-run Inspect and validate input without creating a run or charging anything
--id <ID> A UUID to reuse after a lost response, with identical input and terms
--org <ORG> Act for this org, by handle or id, in place of the context's account
--caller <CALLER> On the local host, override the default caller `local`
--json Print JSON. On whenever stdout is not a terminal
--anonymous On the local host, call without a caller
-y, --yes Confirm terminal prompts. Commands with terminal prompts refuse without a terminal unless this is given. Cloud deploys with --yes require an API key with deployments:write; CLI sessions use browser approval instead
--issuer <ISSUER> On the local host, the end user's issuer (unchecked)
--user <USER> On the local host, the end user's subject (unchecked)
-h, --help Print helpcrab workflow status
Read a run's checkpoints, result and continuation eligibility
Usage: crab workflow status [OPTIONS] <TARGET> <RUN>
Arguments:
<TARGET>
<RUN>
Options:
--context <CONTEXT> The context to talk to, in place of the one in use
--org <ORG> Act for this org, by handle or id, in place of the context's account
--json Print JSON. On whenever stdout is not a terminal
-y, --yes Confirm terminal prompts. Commands with terminal prompts refuse without a terminal unless this is given. Cloud deploys with --yes require an API key with deployments:write; CLI sessions use browser approval instead
-h, --help Print helpcrab workflow continue
Continue an eligible run using its original input and saved checkpoints
Usage: crab workflow continue [OPTIONS] <TARGET> <RUN>
Arguments:
<TARGET>
<RUN>
Options:
--context <CONTEXT> The context to talk to, in place of the one in use
--org <ORG> Act for this org, by handle or id, in place of the context's account
--json Print JSON. On whenever stdout is not a terminal
-y, --yes Confirm terminal prompts. Commands with terminal prompts refuse without a terminal unless this is given. Cloud deploys with --yes require an API key with deployments:write; CLI sessions use browser approval instead
-h, --help Print helpcrab workflow cancel
Stop new calls; an external request already accepted cannot be recalled
Usage: crab workflow cancel [OPTIONS] <TARGET> <RUN>
Arguments:
<TARGET>
<RUN>
Options:
--context <CONTEXT> The context to talk to, in place of the one in use
--org <ORG> Act for this org, by handle or id, in place of the context's account
--json Print JSON. On whenever stdout is not a terminal
-y, --yes Confirm terminal prompts. Commands with terminal prompts refuse without a terminal unless this is given. Cloud deploys with --yes require an API key with deployments:write; CLI sessions use browser approval instead
-h, --help Print help