> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following https://api.getcargo.io/INSTALL.md` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://raw.githubusercontent.com/getcargohq/cargo-skills/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits, valid for its first 30 days, and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# State & Drift

> How your project's deploy state links code to deployed Cargo resources, the cargo.state.json pointer you commit, the deploy lock, and detecting changes made outside the project with project refresh.

## Deploy state

Every deploy records a map from each code resource (`kind:slug`) to the real
uuid Cargo assigned it, plus its outputs and a content hash:

```json theme={null}
{
  "version": 1,
  "workspaceUuid": "fbe3...",
  "resources": {
    "connector:hubspot": {
      "hash": "sha256:…",
      "uuid": "9c26…",
      "outputs": { "uuid": "9c26…", "datasetUuid": "f12c…" }
    }
  }
}
```

That map is the authoritative link from code to deployed infra. Connectors and
models are slug-addressable and self-heal, but **plays, agents, tools, files and
MCP servers have no slug** — their stored uuid is the only way to re-find them.

**It lives in your workspace, not in the repo.** The repo commits a pointer to
it:

```json theme={null}
{
  "stateUuid": "8f2c…"
}
```

`cargo-ai project init` creates the state and writes that `cargo.state.json` as part
of the scaffold, so the pointer is in the first commit rather than appearing in
whichever teammate deploys first. It records only uuids, hashes and outputs —
**never secret values**.

> [!WARNING]
>
> **Commit `cargo.state.json`.** Without the uuid, a fresh checkout has no way to
> find the state it belongs to. Deleting it does not silently make a new one — a
> deploy stops and tells you to run `cargo-ai project state list` and
> `cargo-ai project state bind <uuid>`, because creating a replacement would orphan
> everything the old state tracks.

### One state per repo, at most 10 per workspace

A state belongs to a git repo, not to a workspace. Each `project init` creates its
own and commits its own uuid, so a workspace holding five GTM repos holds five
states and they never share a map. A workspace may hold 10 live states; creating
an eleventh is refused until one is removed.

| Situation | What to do |
| - | - |
| A second repo in the same workspace | Nothing — its own `project init` creates its own state |
| A second project inside one repo | `cargo-ai project state create` in that directory, giving it a second pointer |
| Staging and production | Two workspaces, so two states. Init or log in against the one you are targeting |
| A fork that should deploy independently | `cargo-ai project state create --force` — it copied the pointer, so until then it deploys over the original |
| Not on GitHub yet, or not ready | Push it, then `cargo-ai project state connect` |
| `project init` ran signed out | The pointer landed without a uuid. `cargo-ai login`, then `cargo-ai project state create` |
| `cargo.state.json` was lost | `cargo-ai project state list`, then `cargo-ai project state bind <uuid>` |
| The workspace already has 10 live states | `cargo-ai project state remove <uuid>` on one you no longer need, then create |

### Managing it

```bash theme={null}
cargo-ai project state list            # every state in the workspace, and which one you are on
cargo-ai project state create          # create one for this project and write the pointer
cargo-ai project state bind <uuid>     # point this project at an existing one
cargo-ai project state remove <uuid>   # drop a state. Does not delete the live resources it tracked
cargo-ai project state connect         # plan pull requests and deploy pushes from its GitHub repository
cargo-ai project state disconnect      # stop deploying from GitHub; the state and its resources stay
```

### Projects created before states moved to the workspace

Their `cargo.state.json` holds the resource map itself, and it keeps working:
`plan`, `deploy` and everything else read and write that file exactly as they
did. The file *is* the state, so losing it has no recovery path but git.

Moving one into the workspace is a single command, run once by one person:

```bash theme={null}
cargo-ai project state create   # map moves onto a new state, file becomes a pointer
git commit cargo.state.json
```

> [!NOTE]
>
> Nothing migrates a project on its own. The pointer has to reach your teammates
> through git — if a deploy moved the map for whoever ran it first, everyone
> still on the old file would carry on deploying from a state that had already
> moved.

There is no flag to choose between the two: the shape of the file decides.
Resources present means the file holds the state, a `stateUuid` means the
workspace does. Anything that let you contradict it would only ever deploy a
second copy of everything the pointer already tracks.

### Lock and sibling files

A deploy takes a lock on the state for its duration, so two runs cannot
interleave writes. A lock is released when the run ends, and one left by a run
that died expires after an hour; `--force` steals one you believe is stale.

Cargo also writes sibling files next to `cargo.state.json` — a
`cargo.state.bak.json` (local rollback snapshot), a `cargo.state.audit.jsonl`
(run log), a `cargo.state.lock` (local backend only), and a
`cargo.state.cache.json` (the last blob read from the workspace, so `project info`
can report what is deployed without a round trip). Only `cargo.state.json` is
committed; **git-ignore the rest**:

```gitignore theme={null}
.cargo-ai/            # generated by `project types`
cargo.state.lock
cargo.state.bak.json
cargo.state.cache.json
cargo.state.audit.jsonl
```

## Drift

Cargo compares your code against state. It can also compare against the live
workspace to catch changes made **outside** the project (e.g. someone edits an agent
in the Cargo UI, or deletes a folder).

### Detect (read-only)

```bash theme={null}
cargo-ai project refresh
```

Re-reads every state-tracked resource and reports each as `unchanged`,
`modified externally`, or `deleted externally`. It changes nothing.

A modified resource also names the fields the edit landed in, so you can see
whether re-applying your code over it would lose anything:

```
2 resource(s) drifted from code:
  modified externally: agent:sdr (release.systemPrompt, release.temperature)
  deleted externally: folder:archive
```

The fields are names only — state stores a hash per field, never the value, so
nothing a resource holds (a connector's credentials, say) is written to the file
you commit. A resource last deployed by an older CLI has no per-field baseline
and reports as `modified externally` with no fields until its next deploy.

### Correct

```bash theme={null}
cargo-ai project deploy --refresh
```

Folds the drift into the plan before applying:

* **Modified externally** → re-applies your code over it (**code wins**).
* **Deleted externally** → the deploy **stops** and asks you to re-run with
  `--recreate-deleted` before it will recreate anything — a deliberate gate so a
  resource someone removed on purpose doesn't silently come back.

> [!NOTE]
>
> Drift is measured against the state captured at the last deploy, not guessed
> from code — so it reflects real changes to the live resource. A transient read
> error is reported as `unknown`, never as a deletion, so a network blip can't
> trigger a mass re-create.

## Code and UI round-trips

Resources deployed from code remain fully editable in the Cargo UI — but the
project never reads those edits back into your files. What happens to UI work on
the next deploy follows directly from the hash model:

* **A plain `project deploy` compares code against state, not against the live
  workspace.** If you haven't changed a resource in code, it plans as
  `=` unchanged and is skipped — UI edits to it survive every deploy.
* **The moment you change that resource in code**, the next deploy pushes the
  full code spec and overwrites the resource — including anything changed in
  the UI since.
* **`project deploy --refresh` re-applies code over every externally-modified
  resource**, whether or not its code changed. Reach for it when you want to
  reset to what the repo says; avoid it while UI work is in flight.

The practical rule: **pick one owner per resource.** Starting a workflow in
code and finishing canvas-only parts in the UI works — but from then on treat
the UI as that resource's source of truth: leave its code definition alone, or
port the canvas changes back into code before touching it again. Run
`cargo-ai project refresh` before deploying to see exactly which resources have
diverged.

## Secrets and drift

Because `secret()` values are excluded from the content hash, **rotating a secret
does not show as drift** and a plain `deploy` won't push the new value (nothing
changed). To roll a rotated secret, re-apply the resource (make any other change,
or use `--refresh`). Use `env()` instead if you *want* a config value tracked in
the hash. See [Secrets & environments](https://docs.getcargo.ai/reference/secrets-and-environments.md) for
the full `secret()` vs `env()` rules and how to deploy the same code to a second
workspace.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.