Quickstart

Install the Cargo CLI, authenticate, scaffold a workspace, define a tool, and deploy it — end to end.

This walks you from zero to a deployed, runnable tool. It takes a few minutes and one login shared by the CLI, the CDK, and Cargo Skills.

1. Install

npm install -g @cargo-ai/cli

Without a global install, prefix every command with npx @cargo-ai/cli instead of cargo-ai.

2. Authenticate

Log in with your API token (create one under Settings > API in your Cargo workspace):

cargo-ai login --token <your-api-token>

To target a specific workspace, set the CARGO_WORKSPACE_UUID environment variable — otherwise commands run against the token’s default workspace.

API token values are shown only once at creation time. Store them immediately in a secrets manager (GitHub Secrets, AWS Secrets Manager, 1Password, …).

Verify:

cargo-ai whoami
# → {"user":{"email":"[e-mail]"},"workspace":{"name":"My Workspace"}}

In CI or an AI coding agent, you can skip cargo-ai login entirely and set the token via the CARGO_API_TOKEN environment variable — it takes precedence over saved credentials: export CARGO_API_TOKEN=<your-api-token>.

3. Scaffold a workspace

cargo-ai cdk init my-workspace
cd my-workspace
npm install

cdk init writes a starter project (pass --template full for the complete, wired example described in Project layout). The blank default gives you a single cargo.ts with one AI-powered tool — it needs no third-party API keys, so you can deploy and run it with nothing but your Cargo login:

cargo.ts

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

const enrichFlow = defineWorkflow(
  "enrich-contact",
  {
    input: z.object({ email: z.string() }),
    output: z.object({ company: z.string() }),
  },
  ({ input, ai }) => {
    const company = ai(
      `What company owns the email domain of ${input.email}? Reply with just the company name.`,
    );
    return { company };
  },
);

export const enrich = defineTool("enrich", {
  workflow: enrichFlow,
  description: "Enrich a contact with firmographic data.",
  emojiSlug: "mag",
});

4. Generate types (optional but recommended)

cargo-ai cdk types

This reads your workspace and writes typed connector/model config and the uses.<key>.<action> action registry into .cargo-ai/, so your editor autocompletes real action slugs.

5. Plan and deploy

cargo-ai cdk plan               # offline diff — no API calls
cargo-ai cdk deploy             # create everything; writes cargo.state.json

deploy applies in dependency order and records each resource’s real uuid in cargo.state.json. Commit that file — the next deploy only changes what changed.

6. Run your tool

cargo-ai orchestration tool list                         # → workflowUuid
cargo-ai orchestration run create \
  --workflow-uuid <uuid> \
  --data '{"email":"[e-mail]"}' \
  --wait-until-finished

The run’s output includes the company name — your first deployed tool, end to end. It’s also live in your workspace at app.getcargo.io, where you can open it in the visual editor and inspect its runs.

7. Wire a real data source (optional)

Connectors bring your CRM, warehouse, and enrichment providers into the same file — for example HubSpot, using a private-app token kept out of git with secret():

cargo.ts

export const hubspot = defineConnector("hubspot", {
  integration: "hubspot",
  config: { method: "privateApp", accessToken: secret("HUBSPOT_API_KEY") },
});

export const contacts = defineModel("contacts", {
  connector: hubspot,
  extractSlug: "fetchRecords",
});

export HUBSPOT_API_KEY=...      # secret() reads this at deploy time
cargo-ai cdk deploy             # only the new resources are created

secret() reads from process.env at deploy time. See Secrets & environments for secret() vs env(), the CARGO_* variables, and deploying the same code to a second workspace.

Next steps

Project layout

How the loader turns a folder of files into a workspace.

CLI, CDK & Skills

The three ways to drive Cargo — and when to reach for each.

Connectors

Link your CRM, warehouse, enrichment, and AI providers.

Deploying

plan, deploy, prune, refresh, import, and destroy.

CLI

Run tools, trigger plays, and query your data from the terminal.