Docs

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_ID

Status 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_ID

Continuation 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 help

crab 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 help

crab 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 help

crab 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 help

crab 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 help

crab 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