Cargo Orchestration

Cargo CLI — Orchestration

Runtime operations for the Cargo platform.

What do you want to run?

Need to run something?
├── Don't know the action yet    → action list <keywords>
├── One action, one record       → action execute
├── One action, many records     → action execute-batch
├── Multiple actions chained
│   ├── One-off / ad-hoc         → run create --nodes (one record)
│   │                              batch create --nodes (many records)
│   └── Reusable workflow        → build a tool, then run create --workflow-uuid
│                                  or batch create --workflow-uuid
├── Conversational AI agent      → message create
└── Testing ONE node of a
    workflow you're building     → node execute (debug only — see below)

Fanning out across many records (`action execute-batch`, `batch create`)? Sample first. Run 10–20 records, report the observed cost and hit-rate, then ask the user to approve the full enrollment — quoting the record count and the credit estimate. See Create a batch → the sample gate.

Every node execution costs 0.01 credits — 1 credit per 100 — whatever the node is. branch, filter, switch, variables and the rest carry no provider price, but they are not free: the charge is per execution, so a graph's cost has two terms, (provider cost × records) + (nodes × records ÷ 100). On step-heavy, action-light graphs the second term dominates. It shows up in no per-node field — not executions[].creditsUsedCount, not spans.execution_credits_used_count — only in billing usage get-metrics --unit orchestration.executions. Quote both terms in the approval message (`../cargo-gtm/references/cost-discipline.md` §1).

Find the action before you hand-write the JSON. cargo-ai orchestration action list <keywords> searches the integration catalog, Cargo native actions, workspace tools, and agents in one call — free, runs nothing — and each result carries a ready-to-paste action object (with connectorUuid already filled in), the action's credit costs, and its autocomplete slugs. Narrow with --kind connector|native|tool|agent, --integration-slug <slug>, --limit (default 20, max 50). unknown command means the CLI predates it — refresh.

`action execute`, not `node execute`, is the default for running something. node execute is a debug surface for a node that already lives in a workflow: it requires --workflow-uuid, --release-uuid, --node, --computed-config and --context (all five, enforced client-side), and it bills like any live call. If you just want an operation's output — enrich a domain, call a connector action, invoke a tool or agent — use action execute / action execute-batch with a small --action + --data payload. Only reach for node execute when verifying one node's behavior before running the full graph.

Terminology: An orchestration tool is a saved on-demand workflow (listed via tool list). An action is a single operation you execute without building a workflow — it can embed a saved orchestration tool (kind: "tool"), call a third-party connector (kind: "connector"), invoke an AI agent (kind: "agent"), or run a built-in platform operation (kind: "native").

Composing a node graph? Prefer built-in actions + expressions. Use the actions Cargo already provides plus template expressions; avoid python, script (JS), and raw HTTP nodes unless you truly have no alternative. Reshape data → variables; call an LLM and get parsed JSON → native agent node; call an API → the integration's dedicated connector action; route → branch/filter/switch. See `references/node-selection.md`.

Show the graph, don't describe it. Before deploying a draft, and whenever the user asks what a workflow or play does, draw it: cargo-ai orchestration node diagram --workflow-uuid <uuid> --format ascii --raw (free, runs nothing; --format needs CLI ≥ 1.0.56, the command itself ≥ 1.0.54). Routing, fallback edges, and which steps bill are what the user is actually approving, and prose flattens all three. Pick the format by where the output goes: ascii renders a picture a person can read in a terminal or a chat reply; mermaid (the default) is source code, correct only when you are pasting into a PR, a doc, or a page that renders it. Sources, the ASCII legend, cost marking, and the duplicate-slug footgun: `references/node-diagram.md`.

References:

references/examples/actions.md — action execute and execute-batch examples references/examples/tools.md — tool (on-demand workflow) examples references/examples/plays.md — play (segment-driven automation) examples references/examples/agents.md — AI agent chat examples references/examples/templates.md — pre-built workflow templates references/examples/queries.md — orchestration query execute (ClickHouse: runs/batches/spans/records) SQL examples. For storage query (workspace storage), see the cargo-storage skill. references/examples/segments.md — segment fetch and filter examples references/nodes.md — full node creation guide (kinds, native actions, expressions, validation, routing) references/node-diagram.md — draw a node graph as a Mermaid flowchart (node diagram): every source (workflow / draft / release / run / raw nodes), marking paid nodes, highlighting a failing node, and why diagrams key on uuid rather than slug references/node-selection.md — how to pick the right node and avoid unnecessary `python` nodes (decision table, native LLM agent node, template-expression limits, the silent-undefined footgun, inspecting node data via runContext, Pyodide sandbox limits, what survives a delay, group result access) references/filter-syntax.md — complete filter condition reference references/polling.md — async polling patterns, error handling, retry strategies references/response-shapes.md — full JSON response structures references/troubleshooting.md — common errors, plus a "Debugging a workflow run" section for runs that succeed but produce wrong output (wrong-branch routing, empty downstream values)

Diagnosing after the fact? For the ordered forensic runbooks built on these surfaces — trace one run, sweep a batch for errors grouped by root cause, profile a play's credit spend — load the `cargo-diagnostics` skill.

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

Most commands require UUIDs. Always discover them before acting.

cargo-ai orchestration action list <query>  # actions across connectors, native, tools, agents (+ credits)
cargo-ai orchestration play list            # all plays (name, workflowUuid, modelUuid, segmentUuid)
cargo-ai orchestration tool list            # all tools (name, workflowUuid, description)
cargo-ai orchestration workflow list        # all workflows (uuid only — no name)