Deploying

The CDK reconcile lifecycle — plan, deploy, prune, refresh, import and destroy — plus the flags that control confirmation, pruning and locking.

The CDK reconciles your code against the live workspace. All commands accept --dir <path> (defaults to the current directory) and resolve cargo.state.json relative to it.

Commands below are shown as cargo-ai cdk <command>. The CDK ships inside the Cargo CLI, so there’s no separate install or login. If you’d rather not install the CLI globally, the standalone cargo-cdk 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

cargo-ai cdk plan

Compiles your resources and diffs them against cargo.state.json — offline, no API calls. Output marks each resource + create, ~ update, = noop, or - delete (state-tracked but no longer in code).

Deploy

cargo-ai cdk deploy            # create/update; prompts before applying
cargo-ai cdk deploy --yes      # skip the prompt (required in CI / non-TTY)
cargo-ai cdk deploy --dry-run  # show the plan, change nothing

deploy applies in dependency order and persists state after each resource, so a crash mid-deploy leaves a recoverable cargo.state.json — 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:

cargo-ai cdk deploy --prune

Without --prune, the plan still shows what would be pruned and reminds you.

Refresh on deploy

cargo-ai cdk deploy --refresh

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-ai cdk import agent:sdr 1a2b3c4d-...

The CDK 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 CDK 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:

import { defineModel, definePlay, connectorRef, playRef } from "@cargo-ai/cdk";

// A connector that was connected via OAuth in the UI
export const contacts = defineModel("contacts", {
  connector: connectorRef("9c26…"),
  extractSlug: "fetchRecords",
});

// Chain a code-defined play after one that only exists in the workspace
export const followUp = definePlay("follow-up", {
  model: contacts,
  schedule: { type: "dependency", play: playRef("1a2b…") },
});

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 CDK — the uuid is injected as-is.

Rollback

cargo-ai cdk rollback

Restores cargo.state.json from cargo.state.bak.json, the snapshot taken before the last deploy/destroy/import. It restores the state file only — live resources are untouched — so follow it with cargo-ai cdk deploy --refresh to reconcile the workspace back to that state. Accepts --yes to skip the prompt and --force to steal a stale lock.

Destroy

cargo-ai cdk destroy --all                   # tear down everything in state
cargo-ai cdk destroy --target play:welcome   # just one resource

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 matches the workspace you intend.

Locking & --force

A deploy/destroy/import holds a lock (cargo.state.lock) for the whole read→plan→apply sequence so two concurrent runs can’t corrupt the state file. A lock whose holder has died is reclaimed automatically; to override a lock you believe is stale:

cargo-ai cdk deploy --force

Programmatic use

plan/apply are exported, so CI or the backend can reconcile the same way:

import { loadResources, apply, liveExecutors, liveReaders, readState, emptyState, writeState } from "@cargo-ai/cdk";

const nodes = await loadResources(root); // import the repo's resource files
const state = readState(root) ?? emptyState(workspaceUuid);
await apply({ nodes, state }, liveExecutors(api), (next) => writeState(root, next), liveReaders(api));