Cargo Orchestration

Cargo CLI — Orchestration

Runtime operations for the Cargo platform.

What do you want to run?

Need to run something?
├── 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](#the-sample-gate).

> 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.

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-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.

Prerequisites

See [../cargo/references/prerequisites.md](../cargo/references/prerequisites.md) for install, login (--oauth / --token), JSON output conventions, and error shapes. Verify the session with cargo-ai whoami before running any of the commands below.

Discover resources first

Most commands require UUIDs. Always discover them before acting.

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)
cargo-ai orchestration template list       # all workflow templates (slug, name, kind)
cargo-ai ai agent list                     # all agents (uuid, name)
cargo-ai ai template list                  # all AI agent templates (slug, name, languageModelSlug)
cargo-ai storage model list                # all models (uuid, name, slug, columns)
cargo-ai storage dataset list              # all datasets
cargo-ai segmentation segment list         # all segments (uuid, name, modelUuid)
cargo-ai connection connector list         # all connectors

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//plays/ and tools at app.getcargo.io/workspaces//tools/. Get ` 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 . 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: segment, change, filter, recordIds
• Tool workflows (or no workflowUuid): file, records

Quick reference

# Single actions
cargo-ai orchestration action execute --action '{"kind":"tool","toolUuid":"","config":{}}' --data '{"domain":"acme.com"}'
cargo-ai orchestration action execute-batch --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"enrichCompany","config":{}}' --records '[{...},{...}]'
cargo-ai orchestration action get-output-schema --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"enrichCompany","config":{}}' # → {"schema": } without executing

# Workflows (chain multiple actions)
cargo-ai orchestration run create --workflow-uuid  --data '{"company":"Acme","domain":"acme.com"}'
cargo-ai orchestration run create --data '{"domain":"acme.com"}' --nodes '[...]'
cargo-ai orchestration batch create --workflow-uuid  --data '{"kind":"segment","segmentUuid":"..."}'

# AI agents
cargo-ai ai message create --chat-uuid  --parts '[{"type":"text","text":"..."}]'

# Data
cargo-ai orchestration query execute "SELECT count() FROM runs WHERE status='error'" # ClickHouse: spans, runs, batches, records
cargo-ai segmentation segment fetch --model-uuid  --filter '{"conjonction":"and","groups":[]}' --fetching-limit 100
# For SQL against workspace storage (Companies, Contacts, …), see the cargo-storage skill: `storage query execute`

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 | 2s | status is success, error, or cancelled | | Batch | batch get | 5s | status is success, error, or cancelled | | Agent message | message get | 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.

# One action, one record → returns a run
cargo-ai orchestration action execute \
  --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"enrichCompany","config":{}}' \
  --data '{"domain":"acme.com"}' \
  --wait-until-finished

# One action, many records → returns a batch
cargo-ai orchestration action execute-batch \
  --action '{"kind":"tool","toolUuid":"","config":{}}' \
  --records '[{"domain":"acme.com"},{"domain":"globex.com"}]' \
  --wait-until-finished

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.

> 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 (and integration list) return actions..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:

cargo-ai orchestration action get-output-schema \
  --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"enrichCompany","config":{}}'
# → {"schema": {"type": "object", "properties": {...}}}  — the JSON Schema is under the top-level "schema" key

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..}}) before wiring the graph.
• See an agent action's real output envelope — a default free-text agent resolves to {"schema":{"type":"object","properties":{"answer":{"type":"string"}}}}, which is why downstream references need {{nodes..answer...}}.
• Map an action's output onto storage columns without a throwaway run.

See references/examples/actions.md ("Resolve an action's output schema") for verified per-kind examples and the response/error shapes.

Create a run

A run processes a single record through a workflow. Use run create when you need to chain multiple actions together via a node graph, or when running an existing tool workflow.

Runs only work with tool workflows. Play workflows return playNotCompatible — use batch create instead.

cargo-ai orchestration run create \
  --workflow-uuid  \
  --data '{"company":"Acme","domain":"acme.com"}'
# → Poll with: cargo-ai orchestration run get 

# Or wait synchronously — blocks until the run reaches a terminal state and returns the final result
cargo-ai orchestration run create \
  --workflow-uuid  \
  --data '{"company":"Acme","domain":"acme.com"}' \
  --wait-until-finished

Also supports --release-uuid to pin a specific release.

Cancelling runs:

cargo-ai orchestration run cancel --workflow-uuid  --uuids run-uuid-1,run-uuid-2

See references/examples/tools.md for file uploads, monitoring, and cancellation. See references/nodes.md for custom node graphs.

Create a batch

> Sample first, then ask before enrolling everything — blocking. A batch fans one workflow across every record in its data source, so a mistake and a full bill land together. Never enroll a full segment/file/model on the first attempt: run a 10–20 record sample, report what it cost and returned, then ask the user to approve the full enrollment with the record count and credit estimate in the question. Mechanics below; the spend rules behind it are [../cargo-gtm/references/cost-discipline.md](../cargo-gtm/references/cost-discipline.md).

The sample gate

1. Count the pool first (free). Never quote an estimate from a guess:

cargo-ai segmentation segment get           # → recordsCount (also on `segment list`)
cargo-ai storage query execute "SELECT count() FROM ."   # for a filter/model source
# For a file source: wc -l on the CSV, minus the header row.

2. Run 10–20 records through the exact workflow and config. Sample by data kind:

# Play workflow, segment source → reuse the segment's own filter, capped by `limit`
cargo-ai segmentation segment get           # → copy .filter and .modelUuid
cargo-ai orchestration batch create \
  --workflow-uuid  \
  --data '{"kind":"filter","modelUuid":"","filter":,"limit":15}' \
  --wait-until-finished

# Play workflow, explicit records → pick 10–20 ids
cargo-ai orchestration batch create \
  --workflow-uuid  \
  --data '{"kind":"recordIds","modelUuid":"","ids":["id-1","…","id-15"]}'

# Tool workflow, inline records → slice the array
cargo-ai orchestration batch create \
  --workflow-uuid  \
  --data '{"kind":"records","records":[ /* first 15 only */ ]}'

# Tool workflow, file → upload a truncated CSV (header + 15 rows), not the full file
head -n 16 leads.csv > leads-sample.csv
cargo-ai workspaceManagement file upload --file ./leads-sample.csv

limit is the sampling lever for kind: "filter". kind: "segment" and kind: "change" have no limit — they always enroll the whole set, so sample via filter or recordIds and switch to segment only for the approved full run.

3. Report the sample, then ask. The confirmation must carry both numbers the user needs to decide:

Sample: 15 of 1,240 records · 6.2 credits (0.41/record) · 13/15 enriched (87%)
Full enrollment: 1,225 remaining records ≈ 502 credits (balance: 780)

Enroll all 1,225? Or:
  1. Enroll all 1,225 (≈502 cr, leaves ~278)
  2. Trim scope — e.g. the 610 records with a domain set (≈250 cr)
  3. Stop here and review the sample output first

Wait for an explicit answer. Do not enroll the full set on an unanswered question, and don't treat approval of the sample as approval of the full run. Skip the gate only when the batch is free (no paid nodes) and small, or when the user has already named the scope and approved the cost this session.

Batches process multiple records at once. Allowed data kinds depend on the workflow type:

• Play workflows: segment, change, filter, recordIds
• Tool workflows (or no workflowUuid): file, records

# Play workflow — run on a segment
cargo-ai orchestration batch create \
  --workflow-uuid  \
  --data '{"kind":"segment","segmentUuid":"..."}'

# Tool workflow — run on a file
cargo-ai orchestration batch create \
  --workflow-uuid  \
  --data '{"kind":"file","s3Filename":"..."}'
# → Poll with: cargo-ai orchestration batch get

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [getcargohq](https://github.com/getcargohq)
- **Source:** [getcargohq/cargo-skills](https://github.com/getcargohq/cargo-skills)
- **License:** MIT
- **Homepage:** https://getcargo.ai

Install and usage instructions live in the source repository linked above.