Skip to main content
A resource says what exists. An execution says what to do, once: enroll these records into this play, or run this tool on this input. You declare it in code, cargo-ai project plan shows it, and the next cargo-ai project deploy runs it after the resources are applied. There are two:
  • defineBatch runs a workflow once per record: a play, a tool, or a workflow written inline with defineWorkflow.
  • defineRun runs a workflow once, on one input: a tool or an inline workflow. A play runs on records, so it only takes a batch.
An execution acts on the outside world. A play it enrolls records into may send emails or LinkedIn actions, and reverting the code does not take them back.

Declare a batch

  • id is 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.
  • workflow is what every record runs through: a play, a tool, or a defineWorkflow(...). An inline workflow runs as custom nodes, without being deployed as a resource.
  • data is where the records come from:
    • { kind: "filter", model, filter?, limit }: the model’s records matching the filter, at most limit. 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. path resolves like every other path in a project (see below), and mappings renames 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.
A play batch takes any kind but 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
The plan and the deploy read the same file however its path was written. A model, segment or workflow this project does not define is passed by ref: 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 in outputs/, 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
Each entry then keeps its executions in its own 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:
An execution Cargo refused stays in the ledger and does not run again: fix it and give it a new id. 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 in cargo.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.