Quickstart

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

You do not need an account first. --email mails a one-time code and creates the account and a workspace on first use, so there is no separate sign-up step and no browser at any point:

cargo-ai login --email you@company.com          # sends the code, then exits
cargo-ai login --email you@company.com --code 123456

Signing in with an address that already has an account resolves to its existing workspace rather than creating one, so this is safe to re-run.

In an agent or sandbox shell with no terminal to prompt at, the first call sends the code and exits — re-run it with --code. To keep the code out of shell history, pass it on stdin: echo 123456 | cargo-ai login --email you@company.com --code -

The alternatives: cargo-ai login --oauth signs in through the browser using the OAuth device flow, and cargo-ai login --token <your-api-token> uses a token you created under Settings > API. To target a specific workspace, pass --workspace-name "Acme GTM" or --workspace-uuid <uuid> at login, or set the CARGO_WORKSPACE_UUID environment variable — otherwise commands run against your 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":"you@example.com"},"workspace":{"name":"My Workspace"}}

In CI, or in an AI coding agent that already has a token, 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":"ada@acme.com"}' \
  --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.

Get started

Resources

Deploy

CLI

Skills

Reference

1. Install

2. Authenticate

3. Scaffold a workspace

4. Generate types (optional but recommended)

5. Plan and deploy

6. Run your tool

7. Wire a real data source (optional)

Next steps

Project layout

CLI, CDK & Skills

Connectors

Deploying

CLI

​1. Install

​2. Authenticate

​3. Scaffold a workspace

​4. Generate types (optional but recommended)

​5. Plan and deploy

​6. Run your tool

​7. Wire a real data source (optional)

​Next steps

Project layout

CLI, CDK & Skills

Connectors

Deploying

CLI

1. Install

2. Authenticate

3. Scaffold a workspace

4. Generate types (optional but recommended)

5. Plan and deploy

6. Run your tool

7. Wire a real data source (optional)

Next steps