Skip to main content
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

Compiles your resources and diffs them against this project’s deploy state. Output marks each resource + 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 default deploy never deletes. To remove resources you deleted from code:
Without --prune, the plan still shows what would be pruned and reminds you.

Refresh on deploy

Re-reads the live resources first and folds any out-of-band drift into the plan: a resource edited in the UI re-applies (code wins). A resource deleted in the UI is not silently recreated — the deploy stops and asks you to either re-run with --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:
Cargo reconstructs the resource’s outputs and records it so the next deploy is a no-op. Imported resources are treated as adopted: a later 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 a xxRef(uuid) — a typed reference to a live resource the repo doesn’t manage:
Available refs: 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

Restores this project’s deploy state from the snapshot taken before the last deploy/destroy/import. It restores the state only — live resources are untouched — so follow it with 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

Blanket teardown is opt-in: 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.
destroy and deploy --prune delete real Cargo resources. With --yes they skip the prompt — double-check --dir and that cargo.state.json points at the state for the workspace you intend.

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:
Go through the backend rather than readState/writeState. Those read and write the committed file directly, so against a project whose state lives in the workspace they would see nothing deployed, create a second copy of every resource, and overwrite the pointer with the map they built. writeState refuses that, but the backend is the path that works.