Cargo AI

Cargo CLI — AI

Agent resource management: creating and configuring agents, attaching knowledge for retrieval-augmented generation (RAG), connecting MCP servers, and managing agent memories.

For using agents (sending messages, multi-turn chat, polling), use cargo-orchestration. For uploading knowledge files and building knowledge libraries (the content domain), use `cargo-content`. This skill covers how that knowledge attaches to an agent. For workspace administration — folders (used to organize agents and files), users, API tokens, roles, and submitting reports when the CLI fails — use `cargo-workspace-management`.

See references/response-shapes.md for full JSON response structures. See references/troubleshooting.md for common errors and how to fix them. See references/examples/agents.md for agent CRUD and configuration examples. See references/examples/mcp-servers.md for MCP server creation and management examples.

Bootstrap

Already signed in (cargo-ai whoami returns a workspace)? Skip to the next section.

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

Every command prints JSON to stdout; failures exit non-zero with {"errorMessage": "..."}. Anything that creates a run or a batch is async — pass --wait-until-finished or poll the matching get. When the full skill bundle is installed, `../cargo/references/prerequisites.md` adds the CLI version pin, token scopes, and the admin-only surface.

Discover resources first

cargo-ai ai agent list                     # all agents (uuid, name, description)
cargo-ai ai template list                  # all AI agent templates (slug, name)
cargo-ai ai mcp-server list                # all MCP servers (uuid, name)
cargo-ai ai memory list --scope agent --agent-uuid <uuid>  # agent memories
# Knowledge files & libraries live in the content domain — see cargo-content:
#   cargo-ai content file list   /   cargo-ai content library list

Retrieve in the UI: agents live at app.getcargo.io/workspaces/<WORKSPACE_UUID>/agents/<AGENT_UUID>. Get <WORKSPACE_UUID> from cargo-ai whoami under workspace.uuid.

Quick reference

cargo-ai ai agent list
cargo-ai ai agent get <agent-uuid>
cargo-ai ai agent create --name <name> --icon-color blue --icon-face 🤖
cargo-ai ai agent update --uuid <agent-uuid> --name <name>
cargo-ai ai agent remove <agent-uuid>
cargo-ai ai release list --agent-uuid <uuid>
cargo-ai ai release get <release-uuid>
cargo-ai ai release get-draft --agent-uuid <uuid>
cargo-ai ai release update-draft --agent-uuid <uuid> --language-model-slug gpt-4o
cargo-ai ai release deploy-draft --agent-uuid <uuid>
cargo-ai ai template list                  # full detail; there is no `template get`
cargo-ai ai mcp-server list
cargo-ai ai mcp-server create --name "Internal Tools"
cargo-ai ai mcp-server update --uuid <mcp-server-uuid> --name "Updated Name"
cargo-ai ai mcp-server remove <mcp-server-uuid>
cargo-ai ai mcp-client connect --name "My MCP" --url https://mcp.example.com/sse
cargo-ai mcp                               # serve the platform MCP over stdio
cargo-ai mcp --server <mcp-server-uuid>    # serve a curated workspace MCP server instead
cargo-ai ai memory list --scope agent --agent-uuid <uuid>
cargo-ai ai memory update --mem0-id <id> --scope agent --agent-uuid <uuid> --content "Updated memory"
cargo-ai ai memory remove --mem0-id <id> --scope agent --agent-uuid <uuid>

Agents

Agents are AI resources with configured instructions, a language model, actions, and optional resources.

Before creating an agent from scratch, check existing templates — they capture proven patterns for common use cases (lead research, classification, email drafting) and give you a ready-made system prompt, model, and temperature to start from:

cargo-ai ai template list          # browse patterns — full detail, not a summary
# there is no `template get`: `list` already returns systemPrompt, temperature,
# languageModelSlug, actions and resources, so select the one you want
cargo-ai ai template list | jq '.templates[] | select(.slug == "<slug>")' 

# List all agents
cargo-ai ai agent list

# Get a single agent (includes deployed release details)
cargo-ai ai agent get <agent-uuid>

# Create an agent
cargo-ai ai agent create \
  --name "Lead Researcher" \
  --icon-color blue --icon-face 🤖 \
  --description "Researches leads and enriches data"

# Update an agent
cargo-ai ai agent update --uuid <agent-uuid> \
  --name "Senior Lead Researcher" \
  --description "Updated description"

# Move to a folder (find folder UUIDs via cargo-workspace-management)
cargo-ai ai agent update --uuid <agent-uuid> --folder-uuid <folder-uuid>

# Remove an agent
cargo-ai ai agent remove <agent-uuid>

Agent icon: --icon-color must be one of: grey, green, purple, yellow, blue, red. --icon-face is an emoji string.

Folders: Folder creation, listing, and management lives in `cargo-workspace-management` (cargo-ai workspaceManagement folder list/create/...). Use that skill to discover or create the <folder-uuid> you pass to --folder-uuid here.

Releases

Releases are versioned snapshots of an agent's configuration (system prompt, actions, resources, model, temperature). Agents execute against their deployed release.

# List releases for an agent
cargo-ai ai release list --agent-uuid <uuid>

# Get a specific release
cargo-ai ai release get <release-uuid>

# Get the current draft release (editable)
cargo-ai ai release get-draft --agent-uuid <uuid>

# Update the draft release
cargo-ai ai release update-draft --agent-uuid <uuid> \
  --system-prompt "You are a lead research assistant..." \
  --language-model-slug gpt-4o \
  --temperature 0.3 \
  --max-steps 10

# Deploy the draft release (makes it live)
cargo-ai ai release deploy-draft --agent-uuid <uuid> \
  --integration-slug openai \
  --language-model-slug gpt-4o \
  --actions '[]' \
  --mcp-clients '[]' \
  --resources '[]' \
  --capabilities '[]' \
  --suggested-actions '[]' \
  --description "Added research actions"

Structured output & heartbeat — not yet exposed as CLI flags

The release API payload (both draft/update and draft/deploy) accepts two fields that `release update-draft` / `release deploy-draft` do not surface as flags (verified against the CLI source — there is no --output / --output-schema or --heartbeat):

The generic --options flag does not carry these — the API's options only holds {connectorUuidsByIntegrationSlug, modelUuidsByIntegrationSlug}. Until the flags ship, set these with a direct API call against the same endpoints the CLI uses:

# Structured (JSON Schema) output on the draft release
curl -sS -X PUT "$CARGO_API_BASE/v1/ai/releases/draft/update" \
  -H "Authorization: Bearer $CARGO_TOKEN" -H "Content-Type: application/json" \