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 (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 . 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 — build from dedicated actions + expressions (action → expression → HTTP → script , in that order): expressions are inline JavaScript, where the logic goes (inline in one field, a shared variables node, or a script ), native actions to prefer over code/HTTP, and expression traps (silent empty paths, ISO strings arriving as Date , testing with expression eval ) 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 and print {"error": "...", "status": ..., "body": ...} to stderr (the API's own errorMessage or reason is inside error and body ). 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 . file is rejected ( invalidDataKind ), and a filter or recordIds on a model other than the play's is rejected ( modelDoesNotBelongToPlay ). Tool workflows (or no workflowUuid ): usually file or records ; the model backed kinds are not refused for a tool 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 , cancelled , or skipped ( run.finishedAt set) Batch batch get <uuid 5s status is success , error , cancelled , or skipped ( batch.finishedAt set) Agent message message get <uuid 2s status is success , error , or cancelled 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). Returns every match unless you pass limit . Action kinds: tool , connector , agent , native (plus worker , which calls a hosted worker with workerUuid , method , path ). 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. Unknown inputs are refused before the run; inputs put in config are stripped. action execute and execute batch check a connector or native action's inputs against its schema before creating anything (the MCP execute action tools and an agent's action calls do too): an undeclared key — top level or nested inside a declared object — fails with invalidData naming it ( Unknown field: secs ; in a batch Record 1: Unknown field: fields.job titles , and one bad record refuses the whole batch). Extra top level columns on a batch record still pass, tool actions are not checked, and inside a workflow node an unknown key is still dropped silently. A config key is different: the guard that used to answer A top level action does not use actio

cargo-orchestration