Make Cargo actually run something, or show what it would run — execute one connector action, run a multi-step workflow, trigger a batch across a whole segment or model, message an AI agent, build or edit a node graph, draw a workflow, tool or play as a diagram, and query the runtime tables (runs, ba

Cargo CLI — Orchestration Runtime operations for the Cargo platform. What do you want to run? 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]( 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 ](../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 ](../cargo diagnostics/SKILL.md) skill. Bootstrap Already signed in ( cargo ai whoami returns a workspace)? Skip to the next section. 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 ](../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. Plays vs tools: Both are backed by a workflow. A play is a segment driven automation — it reacts to data changes in a segment (records added, updated, removed). A tool is an on demand workflow — triggered manually, via API, or on a cron schedule. Workflows don't have a name field; use play list or tool list to find names and extract the workflowUuid . Retrieve in the UI: plays live at app.getcargo.io/workspaces/<WORKSPACE UUID /plays/<PLAY UUID and tools at app.getcargo.io/workspaces/<WORKSPACE UUID /tools/<TOOL UUID . Get <WORKSPACE UUID from cargo ai whoami under workspace.uuid . Designing a new tool or play? Check templates first — they are pre built node graphs for common automation patterns (enrichment pipelines, CRM syncs, lead scoring) and are an excellent starting point. List templates with cargo ai orchestration template list and inspect a specific one with cargo ai orchestration template get <slug . Templates are tagged by kind so you can find ones suited for tools ( "kind":"tool" ) or plays ( "kind":"play" ) right away. See references/examples/templates.md for the full guide. Compatibility rules: run create — only works with tool workflows (or no workflowUuid ). Play workflows return playNotCompatible . batch create — allowed data kinds depend on the workflow type: Play workflows: filter , recordIds , segment , change . Trigger a play with filter ; segment takes a standalone segment only, never the segmentUuid from play list . Tool workflows (or no workflowUuid ): file , records Quick reference Polling async operations All operations are asynchronous. Either poll until terminal state, or pass wait until finished to block. action execute returns a run. action execute batch returns a batch. They poll the same way: Result type Poll command Interval Done when Run run get <uuid 2s status is success , error , or cancelled Batch batch get <uuid 5s status is success , error , or cancelled Agent message message get <uuid 2s status is success or error For long running batches (1000+ records), increase the interval to 10 15s after the first minute. Execute actions Run a single action — no workflow or node graph needed. Find it first — action list Free, executes nothing. All query terms must match (AND); a hit on the action slug or name ranks above the integration, which ranks above the description. Returns {query, totalMatches, results[]} where each result carries name , description , score , an action object to paste straight into execute / execute batch / get output schema , the workspace connectors for that integration, credits (the cost table, when the action bills), and autocompletes (config fields that need a picked id — a HubSpot object type, a Slack channel). Defaults to 20 results, max 50. Action kinds: tool , connector , agent , native . See references/examples/actions.md for all action kinds, parameters, retry config, response shapes, and end to end examples. A top level action has no config — omit it. Inputs belong in data / records ; execute and execute batch take the action with no config key at all, which is exactly what action list hands back, so its result pastes straight in. ( "config": {} is still accepted there, harmlessly.) get output schema takes the same pair. The action object from action list , plus data when the action's output depends on its inputs — a HubSpot object type or a target sheet decides which fields come back ( data needs CLI ≥ 1.0.67 ; the config less action works from 1.0.66). Workflow nodes , an alert's actions , a play's healthAlertActions , and an agent's or MCP server's actions are where config still lives; that is a node's configuration, not an action's input. Inputs put in config are now dropped, not rejected. The guard that used to answer A top level action does not use action.config… is gone, so the action runs with no input — you get a provider side missing field error or an empty result that never mentions config . Check this first when a call comes back empty for no visible reason. execute batch bills per record. Pass a 10–20 record slice of records first, report the observed per record cost and hit rate, and get approval (with the full record count and credit estimate) before sending the rest — same gate as [Create a batch]( the sample gate). Resolve an action's output schema (without executing) Never guess what an action outputs. Two free sources — no run, no credits: 1. Connector actions: the integration catalog carries the output schema inline — integration get <slug (and integration list ) return actions.<actionSlug .output.schema next to the input config.jsonSchema . Not every action declares one. 2. Any action kind ( tool / connector / agent / native ) — resolve it with the same action object as action execute : Actions that declare no output schema fail with "Action has no output schema." (non zero exit, status 404) — that's the signal to fall back to inspecting runContext from a real run. Use these to: Know which fields a downstream node can read ( {{nodes.<slug .<field }} ) before wiring the graph. See an agent action's real output envelope

cargo-orchestration