cargo-ai project reconciles your code against the live workspace. All commands accept
--dir <path> (defaults to the current directory) and resolve this project’s
deploy state relative to it, through the cargo.state.json that names it.
Commands below are shown as cargo-ai project <command>. The engine ships inside
the Cargo CLI, so there’s no separate install or login. If you’d rather not install
the CLI globally, the project-local bin, npx @cargo-ai/cdk <command>,
exposes the identical subcommands; in a scaffolded project, npm run plan /
deploy / types are shortcuts for the common ones.
Plan
+ create, ~ update, = noop, or - delete
(state-tracked but no longer in code). It changes nothing, in the workspace or
on disk.
Connect the repository to the project and Cargo runs this on every pull request
for you, as a comment and a check — see GitHub.
Deploy
deploy applies in dependency order and persists state after each resource,
so a crash mid-deploy leaves a recoverable state — just re-run.
1
Create
First deploy creates every resource and writes state.
2
No-op
Re-deploy with no code changes does nothing.
3
Update
Change one resource; only it updates.
Prune
By defaultdeploy never deletes. To remove resources you deleted from code:
--prune, the plan still shows what would be pruned and reminds you.
Refresh on deploy
--recreate-deleted (to restore it) or remove it from your code (if the
deletion was intentional). See State & drift.
Import
Bind an existing live resource to a code resource — recover a lost state link, or adopt pre-existing infra:destroy
releases them (drops them from state) rather than deleting infra the project didn’t
create.
Referencing existing resources
You don’t have to import (or define) a resource just to point at it. Every builder that takes a handle also accepts axxRef(uuid) — a typed reference to
a live resource the repo doesn’t manage:
connectorRef, modelRef, folderRef,
playRef, memberRef, segmentRef, plus toolRef / agentRef for
workflow uses. The kind is branded, so a modelRef can’t be passed where a
connector is expected. Referenced resources stay unmanaged: they’re never
deployed, pruned, or destroyed by the project — the uuid is injected as-is.
Members are the exception worth knowing: defineMember("alice@acme.com") adopts
the live member with that email, so a territory doesn’t have to hardcode uuids
that only exist in one workspace.
Rollback
cargo-ai project deploy --refresh to reconcile the
workspace back to it. Accepts --yes to skip the prompt and --force to steal
a stale lock.
Destroy
destroy refuses unless you pass --all or
--target <id> (so --yes alone can’t wipe a workspace). It deletes by uuid in
dependency-safe order (dependents first) and releases adopted resources
instead of deleting them. A --target that still has dependents — or that
isn’t in state — is rejected rather than silently skipped.
Locking & --force
A deploy/destroy/import holds a lock on the state for the whole read→plan→apply
sequence so two concurrent runs can’t corrupt it — across machines, not just
across processes on one. A lock left by a run that died expires after an hour;
to override one you believe is stale:
Programmatic use
plan/apply are exported, so CI or the backend can reconcile the same way:

