cargo-orchestration

[{"code":"oauth","match":"oauth","path":"SKILL.md"},{"code":"payment","match":"billing","path":"SKILL.md"},{"code":"install_cmd","match":"npm install -g","path":"SKILL.md"},{"code":"api_key_mention","match":"API key","path":"references/troubleshooting.md"},{"code":"oauth","match":"oauth","path":"references/troubleshooting.md"},{"code":"oauth","match":"OAuth","path":"references/troubleshooting.md"},{"code":"payment","match":"billing","path":"references/troubleshooting.md"},{"code":"install_cmd","match":"npm install -g","path":"references/troubleshooting.md"}]

# Filter syntax

Complete reference for building segment filter conditions in the Cargo CLI.

> **CRITICAL — common silent failure:**
> Every filter object uses the key `conjonction` — **not** `conjunction`.
> This is intentional (French spelling). A typo here does **not** throw an error — it simply returns no records.
> Double-check this spelling every time you write a filter. Search for `conjunction` in your JSON before running.

## Structure

A filter has two levels of nesting: top-level groups joined by a conjunction, and each group contains conditions joined by their own conjunction.

```json
{
  "conjonction": "and",
  "groups": [
    {
      "conjonction": "and",
      "conditions": [
        { "kind": "string", "columnSlug": "domain", "operator": "contains", "values": "acme" }
      ]
    }
  ]
}
```

- Top-level `conjonction`: `"and"` or `"or"` — joins the groups
- Group-level `conjonction`: `"and"` or `"or"` — joins the conditions within a group
- Empty filter (all records): `{"conjonction":"and","groups":[]}`

## Condition kinds and operators

### string

```json
{ "kind": "string", "columnSlug": "name", "operator": "is", "values": ["Acme Corp"] }
{ "kind": "string", "co

# Diagramming a node graph

A workflow the user can't see is a workflow they can't approve. A node graph is a
directed graph with routing, fallbacks, and paid steps in it — prose flattens all
three. Draw it instead: it costs nothing, and the command renders two formats from
the same graph — ASCII for a terminal, Mermaid for anything that renders Mermaid
(GitHub, the Cargo docs, a published page). See [The ASCII format](#the-ascii-format-cli--1056).

`cargo-ai orchestration node diagram` does it (**CLI ≥ 1.0.54**; `unknown command`
means the pin hasn't moved yet — bump per [`../../cargo/SKILL.md`](../../cargo/SKILL.md)
§ "At session start"). Free, runs nothing, no credits — same family as
`node validate`.

## When to draw one

- **At the plan gate**, before `release deploy-draft` / `cdk deploy` — the diagram
  *is* the "nodes and data flow" half of the plan ([`../../cargo/references/interaction.md`](../../cargo/references/interaction.md) §1).
- **When explaining an existing workflow, tool, or play** — "what does this play
  do?" is one command against its `workflowUuid`.
- **When reporting a trace** — the graph with the failing node marked red, next to
  the error ([`../../cargo-dia

# Prefer built-in actions + expressions over code/HTTP nodes

When building a workflow, **use the actions Cargo already provides plus template
expressions. Avoid `python`, `script` (JavaScript), and raw HTTP nodes unless you
genuinely have no other option.**

Code and raw-HTTP nodes feel flexible, but they are the hardest part of a workflow
to build and debug from the CLI: they fail in ways the native nodes don't, and you
can't see inside them as easily. Most of what they get used for is already a
one-line native node or a template expression.

## Use this instead

| Instead of writing… | Use |
| --- | --- |
| `python` / `script` to reshape, rename, or extract fields | a `variables` node — each value is a template expression, e.g. `{{nodes.start.email.split('@')[1]}}` |
| `python` / `script` to call an LLM and parse its JSON | the native `agent` node with `output.type:"jsonSchema"` — it returns structured JSON, no parsing (read it as `{{nodes.<slug>.answer.<field>}}`) |
| a raw **HTTP** request | the integration's **dedicated connector action** (e.g. `clearbit.enrichCompanyFromDomain`) — discover them with `connection integration get-documentation <slug>` |
| `python` / `script` to

# Creating nodes

## What is a custom node graph?

A **node graph** is a directed acyclic graph of steps that defines a workflow. Each graph must have exactly one `start` node (entry point) and one `end` node (exit point). Intermediate nodes perform actions — enrichments, transformations, branching, AI calls, etc. — and are linked together via `childrenUuids`.

Pass a custom node graph to override a tool's deployed release:

```bash
cargo-ai orchestration run create \
  --workflow-uuid <tool.workflowUuid> \
  --data '{"domain":"acme.com"}' \
  --nodes '[...]'
```

Also works with `batch create --nodes`. Cannot be combined with `--release-uuid`.

**Always validate first** — use `node validate` to catch structural errors before running:

```bash
cargo-ai orchestration node validate --nodes '[...]'
```

**Then show it before you deploy it.** `node validate` proves the graph is
well-formed, not that it does what the user wanted. Render it as a Mermaid
flowchart — [`node-diagram.md`](node-diagram.md) — and let them check the routing
and the paid steps against their intent. The two go together: validate, diagram,
ask, deploy.

## Node shape

Every node in the `--nodes` JSON array has the

# Async polling reference

All runs, batches, and agent messages in Cargo are asynchronous. This file is the single source of truth for polling patterns, intervals, terminal states, and error handling.

## Skip polling with `--wait-until-finished`

For runs and batches, pass `--wait-until-finished` to `run create` or `batch create` to block until the operation reaches a terminal state and return the final result directly — no manual polling needed:

```bash
# Blocks until the run finishes, returns the final run result
cargo-ai orchestration run create \
  --workflow-uuid <uuid> \
  --data '{"domain":"acme.com"}' \
  --wait-until-finished

# Blocks until the batch finishes, returns the final batch result
cargo-ai orchestration batch create \
  --workflow-uuid <uuid> \
  --data '{"kind":"filter","modelUuid":"...","filter":{"conjonction":"and","groups":[]}}' \
  --wait-until-finished
```

Use `--wait-until-finished` for short-lived runs or when you need the result immediately. For large batches (1000+ records) or long-running workflows, manual polling gives you more control and visibility.

## Polling table

| Operation | Create command | Poll command | Interval | Terminal state |
|--

# Response shapes

JSON response structures returned by Cargo CLI commands used in the `cargo-orchestration` skill.

## cargo-ai orchestration play list

```json
{
  "plays": [
    {
      "uuid": "play-uuid",
      "name": "Enrich new companies",
      "workflowUuid": "workflow-uuid",
      "modelUuid": "model-uuid",
      "segmentUuid": "segment-uuid",
      "changeKinds": ["added", "updated"],
      "runCreationRule": "always",
      "isEnabled": true,
      "schedule": null,
      "description": "Enriches companies when they enter the segment",
      "healthThreshold": 80,
      "folderUuid": "folder-uuid-or-null",
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-15T00:00:00Z"
    }
  ]
}
```

**Key fields:** `name` (match by name), `workflowUuid` (needed for run/batch commands), `modelUuid`, `segmentUuid` (the segment the play watches).

## cargo-ai orchestration tool list

```json
{
  "tools": [
    {
      "uuid": "tool-uuid",
      "name": "Company Enrichment",
      "workflowUuid": "workflow-uuid",
      "description": "Enriches a company record with firmographic data",
      "creditsCost": { "kind": "minMax" },
      "triggers": [],
      "isReadOnly

# Troubleshooting

Common errors and recovery steps for `cargo-orchestration` commands.

> For async polling patterns, partial batch failures, and retry node configuration, see `references/polling.md`.

## General

| Symptom                                      | Cause                            | Fix                                                                       |
| -------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------- |
| `{"errorMessage": "..."}` with non-zero exit | Any CLI error                    | Read the `errorMessage` — it usually says exactly what's wrong            |
| `command not found: cargo-ai`                | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli`     |
| `Unauthorized` or `Forbidden`                | Bad or expired credentials       | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token <token>`; verify with `cargo-ai whoami` |

## Runs and batches

| Symptom                             | Cause                                              | Fix                        

---
name: cargo-orchestration
description: "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, batches, spans, records) with SQL. Triggers: \"run this on all my contacts\", \"execute the action\", \"kick off a batch\", \"build a workflow\", \"schedule a play\", \"make it run every morning\", \"ask the agent\", \"show me the workflow\", \"what does this tool do\", \"visualize this play\", \"draw the graph\", \"explain this workflow\", \"how many runs failed today\", \"what is the output schema for this action\", \"add a step that\". Skip when: explaining why a run misbehaved — use cargo-diagnostics; downloading result files — use cargo-analytics; committing the workflow as code — use cargo-cdk."
version: "1.11.1"
compatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token
homepage: https://github.com/getcargohq/cargo-skills
metadata:
  author: