Quickstart

This walks you from zero to a deployed, runnable tool. It takes a few minutes and one login shared by the CLI, your project, 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 --agentid signs an agent in as its own AgentID. The command prints an Auth0 URL and waits for the redirect. Open that URL once. A second visit starts a different sign-in. It does not open the Cargo app. When AgentID shows an auth token, approve it within 5 minutes with agentmail inboxes authorize --inbox-id <inbox> --auth-token <token> --accept-disclosure true. cargo-ai login --oauth signs a person 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 project init my-workspace
cd my-workspace
npm install

project init scaffolds a project repo from the Cargo template (getcargohq/cargo-manifest), with the project in infra/. Run it without a directory to be asked instead. init installs the dependencies for you; the npm install above is only there if you declined or it failed. There is one install, at the repo root — infra/ is a source directory with no manifest of its own. Every project command below finds infra/ from the repo root, so you can stay where you are. Declaring a resource is writing a file under infra/ and importing it — here is one AI-powered tool that needs no third-party API keys, so you can deploy and run it with nothing but your Cargo login:

infra/tools/enrich.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 project 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 project plan               # diff against this project's deploy state
cargo-ai project deploy             # create everything; record it in the state

deploy applies in dependency order and records each resource’s real uuid in this project’s deploy state, which lives in your workspace. Commit cargo.state.json — it is the pointer that finds it. 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 project — for example HubSpot, using a private-app token kept out of git with secret():

infra/connectors/hubspot.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 project deploy             # only the new resources are created

secret() reads from process.env at deploy time. To keep the key in the workspace instead of your shell, use workspaceEnv("HUBSPOT_API_KEY"). See Secrets & environments for how the three helpers differ, 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.

Commands, project & 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

Commands, project & 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

Commands, project & 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