Cargo CDK

Define your entire Cargo workspace in code — connectors, models, plays, tools, agents, MCP servers, context, segments, capacities, territories, folders, files, workers and apps — and deploy it declaratively, the same way you'd manage cloud infrastructure with Pulumi or the AWS CDK. For a complete overview, see the Cargo CDK docs.

Requirements

• Node.js 22.x
• A Cargo API token (create in your workspace under Settings → API)

Installation

@cargo-ai/cdk gives you both the define* builders you import in your resource files and the cargo-cdk command to deploy them:

npm install @cargo-ai/cdk
npx @cargo-ai/cdk --help

cargo-cdk is a project-local tool — run it through the scaffolded npm run scripts or npx @cargo-ai/cdk, the way you'd use the AWS CDK or SST. Don't install it globally: a global cargo-cdk on your PATH would clash with the AWS CDK. (If you also use the AWS CDK inside the same project, always call this one as npx @cargo-ai/cdk to disambiguate.)

Authenticate with the Cargo CLI (or set a token for CI):

npm install -g @cargo-ai/cli          # the Cargo CLI — `cargo-ai login` + the `cargo-ai cdk` alias
cargo-ai login --oauth                # browser sign-in
# …or, for CI / non-interactive (no CLI needed):
export CARGO_API_TOKEN=<your-api-token>

Login writes ~/.config/cargo-ai/credentials.json, which cargo-cdk reads (along with the CARGO_API_TOKEN / CARGO_WORKSPACE_UUID env vars). Everywhere below you run the CDK one of two ways: npm run <script> for the everyday commands (a scaffolded project wires up types / plan / deploy), or npx @cargo-ai/cdk <command> for any command — both resolve the project-local cargo-cdk bin. The cargo-ai cdk <command> alias works too.

Quick start

Scaffold a starter project from a template — npx @cargo-ai/cdk runs the CDK with no global install:

npx @cargo-ai/cdk init my-workspace --template full  # every resource type, wired up
# or: npx @cargo-ai/cdk init my-workspace             # minimal 'blank' template
# or: npx @cargo-ai/cdk init --list-templates         # see all templates
# or: npx @cargo-ai/cdk init my-tam --from getcargohq/cargo-cookbooks/signal-based-tam
#     scaffold from a GitHub source (owner/repo[/folder][@ref]); a cookbook
#     folder also pulls its required siblings via the repo's cargo.scaffold.json
cd my-workspace && npm install

Or add a resource file yourself — importing a file is registration, there's no manifest to maintain:

// my-workspace/contacts.ts
import { defineConnector, defineModel, secret } from "@cargo-ai/cdk";

// `secret()` reads the value at deploy time and keeps it out of state and the
// content hash — use it for credentials. The config shape is per-integration
// (HubSpot takes a Private App token or an OAuth refresh token); run
// `npx @cargo-ai/cdk types` to have it type-checked (see Typed config below).
export const hubspot = defineConnector("hubspot", {
  integration: "hubspot",
  config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
});

// Pass the connector handle as `connector` — the model depends on it, so the
// CDK creates the connector first and injects its dataset uuid.
export const contacts = defineModel("contacts", {
  connector: hubspot,
  extractSlug: "fetchRecords",
});

export HUBSPOT_API_KEY=...        # secret() reads this at deploy time
npm run plan                      # offline diff — no API calls   (runs `cargo-cdk plan`)
npm run deploy                    # create everything, write cargo.state.json

(The scaffolded package.json wires npm run types / plan / deploy to the project-local cargo-cdk. Or run any command directly with npx @cargo-ai/cdk <command>.)

Re-running deploy only changes what changed; an unchanged workspace is a no-op.

Typed config

defineConnector and defineModel config are typed against your workspace's actual integration schemas. Generate the types once:

npm run types          # or: npx @cargo-ai/cdk types

They land in .cargo-ai/. Add it to your tsconfig include with an explicit glob — a bare .cargo-ai (a dot-dir) is ignored by TypeScript:

// tsconfig.json
"include": ["*.ts", ".cargo-ai/**/*.d.ts"]

After that, config is checked against the integration's schema — e.g. HubSpot is a discriminated union, so the editor completes method and requires the matching credential, and secret() is accepted wherever a credential is expected. A uuid-reference config field (e.g. an extractor's modelUuid / relatedModelUuid) is typed as In<string>, so you can pass a resource handle's uuid directly (modelUuid: accounts.uuid) to wire the dependency — no cast — or a literal uuid string. Re-run npm run types after adding or changing workspace integrations.

Typing is a bonus, never a gate: an integration you haven't synced (or a custom one) falls back to a loose Record<string, unknown>, so deploy still works without ever running npm run types.

Defining resources

Every Cargo resource has a define* builder that returns a handle. Wire resources together by passing one handle to another — the dependency graph is just your variable graph. Pass the handle directly (or xxRef("uuid") for a resource you didn't define in code); no .uuid at the call site. Where a reference takes per-call options, wrap it as { ref, …options }.

import { defineAgent, defineTool, defineWorkflow } from "@cargo-ai/cdk";

const flow = defineWorkflow("enrich", { input, output }, ({ input, ai }) => …);
export const enrich = defineTool("enrich", { workflow: flow, emojiSlug: "mag" });

export const sdr = defineAgent("sdr", {
  connector: openai,                              // the LLM connector (or connectorRef("…"))
  languageModel: "gpt-4o",
  systemPrompt: "Qualify inbound leads.",
  // everything the agent can call or read — one array, kind inferred per handle
  uses: [
    { ref: contacts, readOnly: true },            // a data model (handle + options)
    enrich,                                        // a tool (bare handle)
    hunter.actions.findEmail,                              // an action off a connector handle
  ],
});

See Defining Resources for every builder (connectors, models, plays, tools, agents, MCP servers, context, segments, capacities, territories, folders, files, workers, apps) and the slug rules.

Native object and unified models (kind: "native") and the context repository (defineContext) have their own guides: Object models, Unification, and Context.

Commands

In a scaffolded project, the everyday commands are npm run scripts:

npm run types     # generate per-workspace types for typed config
npm run plan      # offline: diff the code against cargo.state.json
npm run deploy    # create/update resources, write cargo.state.json

Run any command — including the ones without a script — with npx @cargo-ai/cdk:

npx @cargo-ai/cdk init <directory>      # scaffold from a template (--template, --list-templates) or GitHub (--from owner/repo[/folder][@ref])
npx @cargo-ai/cdk deploy --prune        # also delete resources removed from code
npx @cargo-ai/cdk deploy --refresh      # re-read live resources, re-apply out-of-band changes
npx @cargo-ai/cdk refresh               # read-only: report resources that drifted from code
npx @cargo-ai/cdk import <id> <uuid>    # bind an existing live resource into state
npx @cargo-ai/cdk rollback              # restore cargo.state.json from the pre-deploy snapshot
npx @cargo-ai/cdk destroy --target <id> # tear down one resource
npx @cargo-ai/cdk destroy --all         # tear down everything in state

Every command also works as cargo-ai cdk <command> if you have the global Cargo CLI installed — same engine, same login.

Common flags: --dir <path>, --yes (skip the prompt — required in CI), --json, and --force (steal a stale state lock). See Deploying.

State & drift

npm run deploy writes cargo.state.json — the link from your code to the resources Cargo created. Commit it (losing it orphans resources; recover a link with npx @cargo-ai/cdk import). It records only uuids, hashes and outputs — never secret values.

Git-ignore the generated types and the working files the CDK writes alongside it (but commit cargo.state.json):

.cargo-ai/
cargo.state.lock
cargo.state.bak.json
cargo.state.audit.jsonl

npx @cargo-ai/cdk refresh reports resources changed or deleted outside the CDK (e.g. edited in the Cargo UI); npx @cargo-ai/cdk deploy --refresh re-applies your code over them. See State & Drift.

Documentation

Full documentation: docs.getcargo.ai/cdk.