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 (no default: omit it and every match comes back). 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? Build it from dedicated actions + expressions, in this order:

1. A dedicated action. Search first with action list <keywords> (free): connector actions, native actions (agent, modelUpsert, branch, group…), tools.
2. An expression for the glue. It's inline JavaScript in the field that needs the value: reshaping, payloads, conditions, arrays.
3. HTTP, only if step 1 found no action for that API.
4. A script node, only if the logic can't fit in an expression.

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.