cargo-ai project plan shows it, and the next cargo-ai project deploy runs it
after the resources are applied.
There are two:
defineBatchruns a workflow once per record: a play, a tool, or a workflow written inline withdefineWorkflow.defineRunruns a workflow once, on one input: a tool or an inline workflow. A play runs on records, so it only takes a batch.
Declare a batch
idis what Cargo remembers the execution by. It must be unique in the project: lowercase letters, digits, hyphens and underscores. Start it with a date and executions run in the order you wrote them.workflowis what every record runs through: a play, a tool, or adefineWorkflow(...). An inline workflow runs as custom nodes, without being deployed as a resource.datais where the records come from:{ kind: "filter", model, filter?, limit }: the model’s records matching the filter, at mostlimit. The limit is required, so a filter never runs on more records than you wrote down.{ kind: "segment", segment }: the records in a segment.{ kind: "recordIds", model, ids }: exactly these records.{ kind: "form", records }: records written in code, as the workflow’s form takes them. Cargo checks each against the form.{ kind: "file", path, mappings? }: the rows of a CSV in the repository, uploaded by the deploy that runs the batch.pathresolves like every other path in a project (see below), andmappingsrenames columns to the workflow’s inputs. A file can be at most 50 MB; load larger data into a model and batch on a filter or segment.
file, and its model must be the play’s own. A
tool or inline workflow batch takes any kind, and Cargo checks each record
against the workflow’s form before it runs.
A file’s path resolves the way defineFile and defineWorker paths do: a
relative one against the project directory (infra/). Name it from the batch’s
own file instead, and the CSV can sit beside it:
outputs/2026-10-20-import/import.ts
modelRef(uuid), segmentRef(uuid), or workflowRef(uuid) for the workflow
behind a play or tool, which is what a batch names. A playRef or toolRef
carries only the play’s or tool’s own uuid, so it is refused. A preview cannot
read a referenced workflow’s steps, so one that runs on a merge always needs
approval.
Declare a run
data is the workflow’s input. Leave it out for a workflow that takes none.
Where they live
Executions live inoutputs/, in any folder under it, and every .ts file
there is imported: the folder is what declares them, as infra/ does for
resources, so nothing outside it is read and your scripts and tests are never
run. That is the outputs/ beside the project’s
cargo.json, at the root of a
project repo: outputs/2026-10-14-expansion-pilot/.
A cargo.json can name other folders
in its executions, which then replace outputs/. A * in a folder name
matches any folder there, so an archive whose entries also hold scripts can name
only the folders that declare executions:
cargo.json
executions/ folder, and the
rest of the entry is never imported.
Plan and deploy
cargo-ai project plan lists every execution that has not run yet, and the ones
that have:
cargo-ai project deploy applies the resources first, so an execution can use a
play or tool created in the same change, then starts each pending execution as a
batch or a run. The deploy prints each one with the batch or run it started, and
exits non-zero if one did not start, without stopping the ones after it:
--draft never runs executions.
From a connected repository, the pull request previews each
execution, and the merge’s deploy starts only what that preview approved.
Exactly once
The project’s deploy state keeps a ledger of the executions that have run, written before each one starts. It lives with the state in your workspace, so every deploy, from any checkout or from CI, reads the same one. A project whose state is still kept incargo.state.json refuses to run executions until
cargo-ai project state create moves it there.
That ledger, not the code, decides what runs:
There is no retry. To run something again, add an execution with a new id.

