.ts file under the project root, and each define* call registers a resource as a side effect. There is no manifest — the files are the interface.
A worked layout
A project that exercises every resource type and wires them together looks like this.cargo-ai project init <dir> scaffolds the repo around it — the tree below is
what grows inside infra/ as you declare things. For a guided walkthrough that
builds and deploys the whole tree, see the End-to-end recipe:
How the loader works
- Every
.tsfile is imported. Importing registers whateverdefine*calls it contains. To add a resource, add a file. - Handles create dependencies.
define*returns a handle whose outputs (uuid,datasetUuid, …) are deferred tokens. Passing a handle into another builder (e.g.connector: hubspot, or an agent’suses: [enrich]) both orders the deploy and injects the real uuid. The dependency graph is your variable graph. - Bundle directories are skipped. A subdirectory with its own
package.json(a worker or app bundle) is treated as content to upload, not a resource file to import. - Executions load after the resources. Every
.tsfile inoutputs/, besidecargo.json, is imported once the resource files are, so adefineBatchordefineRunthere can import the play or tool it runs. Thecargo.jsonbelow can name other folders instead. Nothing else outside the project is imported: ascripts/folder stays untouched.
cargo.json
A cargo.json makes a folder a Cargo project, the way package.json does for
an npm package. Every command looks for the nearest one above where it runs, up
to the repository root, so it works from any folder in the project: infra/,
outputs/, scripts/.
resourcesis the directory every.tsfile of which is a resource.executionslists the directories whose.tsfiles declare executions, in place of the defaultoutputs/. Every file in them is imported, as inresources, so keep only executions there.
cargo.state.json and the default outputs/ sit in it. A
repository holding several projects has a cargo.json in each, and a command
belongs to the nearest one.
cargo-ai project init writes one. A command run where there is none stops and
prints the one to add, rather than guessing the project from what the folders
hold. A repository scaffolded before cargo.json existed adds it once, beside
its cargo.state.json:
cargo.state.json inside infra/, commands stop
until it is moved beside cargo.json, and say how.
cargo.state.json
Your project’s deploy state is the authoritative map from each code resource
(kind:slug) to the real uuid Cargo assigned it, plus outputs and a content
hash. It lives in your workspace; cargo.state.json is the pointer to it that
project init writes and every later run follows.
The lock/backup/cache/audit siblings are ephemeral — git-ignore them:
Adding a project to a repository you already have
Runinit inside it — in its own folder (cargo-ai project init cargo) or at
the root (cargo-ai project init .). It never replaces a file that is already
there: a README or a CI workflow of the same name is kept and listed. An
existing package.json only gains the scripts and dependencies the project
needs (it is rewritten with two-space indentation), and an existing
.gitignore only gains the patterns it lacks. An existing cargo.state.json
keeps the state it names.
init doesn’t commit or push in a repository that already exists — what
else is in progress there is yours. Review what it wrote, commit and push it
(after npm install, so package-lock.json matches package.json), then
connect the project to the repository:
git init and git remote add
rather than cloned doesn’t know its default branch, so name it with
--branch <name>.
Which init do I want?
There are several scaffold/init commands — don’t confuse them:
Next steps
Connectors
Start wiring in your data sources.
Deploying
The full reconcile lifecycle and its flags.
State & drift
How state tracks live resources and detects out-of-band changes.

