Cargo CLI

Command-line interface for the Cargo API. Manage workspaces, storage, orchestration, connections, billing, and more from the terminal; for a complete feature overview, see the Cargo CLI Overview.

Requirements

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

Installation

Install from npm (global):

npm install -g @cargo-ai/cli

Or run once with npx without installing:

npx @cargo-ai/cli orchestration workflow list

Authentication

A single cargo-ai login command supports two modes — pass exactly one of --token or --oauth:

# 1. Sign in with an existing workspace-scoped API token
cargo-ai login --token <your-api-token>

# 2. Sign in via your browser using the OAuth 2.0 Device Authorization Flow
cargo-ai login --oauth

Credentials are stored in ~/.config/cargo-ai/credentials.json (file mode 0600).

# Check current auth status
cargo-ai whoami

# Remove saved credentials
cargo-ai logout

Browser sign-in (--oauth)

cargo-ai login --oauth runs the standard OAuth 2.0 Device Authorization Flow (similar UX to gh auth login) against the Cargo OAuth provider, prints a verification URL and user code, opens your default browser, and polls until you complete sign-in. On success the access token is written to ~/.config/cargo-ai/credentials.json.

The CLI ships with a built-in OAuth client, so no setup is required. Advanced users can override the provider via --client-id, --domain, and --audience.

Workspace selection

API tokens (--token) are workspace-scoped, so the workspace is implicit and nothing is persisted alongside the token.

OAuth sessions (--oauth) are user-scoped, so after authentication the CLI picks a default workspace and saves it next to the token:

• One workspace: it is selected automatically.
• Multiple workspaces: you are prompted to pick one (in a TTY); in non-interactive shells the CLI prints the list and asks you to re-run with --workspace-uuid <uuid>.

Pass cargo-ai login --oauth --workspace-uuid <uuid> to skip the prompt. CARGO_WORKSPACE_UUID (or per-command --workspace-uuid flags where supported) overrides the saved default at runtime.

Environment variables (override)

Environment variables take precedence over saved credentials, useful for CI or temporary overrides.

| Variable | Default | Description | | ---------------------- | ------------------------- | ------------------------------------------------------------------------------------------- | | CARGO_API_TOKEN | — | Your Cargo API token (Bearer auth) | | CARGO_BASE_URL | https://api.getcargo.io | API base URL | | CARGO_WORKSPACE_UUID | — | Workspace UUID for workspace-scoped commands (some commands also accept --workspace-uuid) |

Usage

Command structure: cargo-ai <domain> <sub> <action>.

After a global install, run:

cargo-ai <domain> <sub> <action>

Without installing, use npx:

npx @cargo-ai/cli <domain> <sub> <action>

All commands output JSON to stdout.

Help

cargo-ai --help
cargo-ai orchestration --help
cargo-ai orchestration workflow --help

Domains and example commands

| Domain | Description | Example commands | | ------------------------ | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | init | Workspace initialisation (user, workspace, datasets, etc.) | cargo-ai init | | orchestration | Workflows, plays, runs, batches, tools, templates | cargo-ai orchestration workflow list, cargo-ai orchestration run list --workflow-uuid <uuid> | | workspaceManagement | Workspaces, users, tokens, roles, folders | cargo-ai workspaceManagement workspaces list, cargo-ai workspaceManagement token list | | storage | Datasets, models, relationships, runs, records | cargo-ai storage dataset list, cargo-ai storage model list | | connection | Connectors and integrations | cargo-ai connection connector list, cargo-ai connection integration list | | billing | Usage and subscription | cargo-ai billing subscription get, cargo-ai billing usage get-metrics --payload '{"from":"2025-01-01","to":"2025-01-31"}' | | segmentation | Segments and changes | cargo-ai segmentation segment list, cargo-ai segmentation change list --payload '{}' | | revenue-organization | Allocations, capacities, members, territories | cargo-ai revenue-organization member list, cargo-ai revenue-organization territory list | | expression | Recipes and expression evaluation | cargo-ai expression recipe list, cargo-ai expression eval evaluate --payload '{}' | | system-of-record | System of record, client, logs | cargo-ai system-of-record sor list, cargo-ai system-of-record log list --payload '{}' | | user-management | Current user (no workspace context) | cargo-ai user-management user get-current | | ai | AI templates, agents, releases, chats, MCP, files | cargo-ai ai template list, cargo-ai ai agent list, cargo-ai ai file list | | context | Context repository, runtime sandbox, and knowledge graph | cargo-ai context repository get, cargo-ai context runtime browse --path <path>, cargo-ai context graph get | | hosting | Cargo Hosting apps (Vite SPAs), workers, and deployments | cargo-ai hosting app list, cargo-ai hosting worker list, cargo-ai hosting deployment list --payload '{}' | | workflow | Workflow SDK developer tools: per-workspace type sync/codegen | cargo-ai workflow sync (SDK deploy lives at cargo-ai orchestration release deploy-draft --file <path>) |

Commands that accept complex payloads use a --payload <json> option (e.g. cargo-ai orchestration play create --payload '{"name":"My Play",...}'). Use --help on any subcommand for options.

orchestration release deploy-draft

Deploy a draft release of an existing workflow. Two input modes share the same command:

# Compile a Workflow SDK module and deploy it
cargo-ai orchestration release deploy-draft --file ./my-workflow.ts

# Preview the compiled nodes + form fields without deploying
cargo-ai orchestration release deploy-draft --file ./my-workflow.ts --dry-run

# Pin an explicit version + description
cargo-ai orchestration release deploy-draft --file ./my-workflow.ts --workflow-uuid <uuid> --version 2.0.0 --description "New enrichment path"

# Power-user path: deploy raw wire-format JSON
cargo-ai orchestration release deploy-draft --workflow-uuid <uuid> --nodes '[…]' --form-fields '[…]'

--file <path> loads a @cargo-ai/workflow-sdk module (its export default defineWorkflow(...)) and sources nodes / formFields / description from the compiled output. With --file:

• --workflow-uuid is optional — when omitted, the command best-effort matches the compiled slug against existing workflows' template.slug and errors if the match is missing or ambiguous.
• --version defaults to the next minor bump over the latest existing release (or 1.0.0 for the first).
• --description defaults to the compiled workflow's description.
• --nodes / --form-fields are rejected (they're sourced from the module).

Without --file, --workflow-uuid, --nodes, and --form-fields are all required (raw JSON path). Constraint either way: there is no workflow-create endpoint, so the target workflow must already exist.

Other release verbs (list, get <uuid>, get-deployed, get-draft, update-draft) live under the same group — see cargo-ai orchestration release --help.

Agent Skills

Cargo Skills teaches AI coding agents (Claude Code, Cursor, Windsurf, GitHub Copilot, etc.) how to use the Cargo CLI. Install the skill to let your agent build, run, and manage revenue automation workflows programmatically:

npx skills add getcargohq/cargo-skills

Development

# Build
npm run build

# Run with tsx (no build)
npm run dev
# then in another terminal: npx tsx src/index.ts orchestration workflow list

# Type-check and lint
npm run type:check
npm run lint:check

License

See the project for license information.