Update to Cargo CLI

{
  "name": "cargo-segmentation",
  "description": "Define and use segments — named, saved filters over a Cargo model that become the audience for a batch run, a play trigger, or an export. Triggers: \"build a segment of\", \"filter my contacts where\", \"who matches this criteria\", \"save this as a list\", \"how many companies match\", \"the Closed-Won segment\", \"everyone who has not been emailed\", \"target only accounts that\", \"what is in this segment\", \"narrow this down to\". Filter JSON uses `conjonction` (not `conjunction`) — misspelling it fails silently. Skip when: running something over the segment — use cargo-orchestration; exporting its rows — use cargo-analytics; ad-hoc SQL over the model — use cargo-storage.",
  "included_files": [
    {
      "relative_path": "references/response-shapes.md",
      "size_in_bytes": 4434
    },
    {
      "relative_path": "references/troubleshooting.md",
      "size_in_bytes": 4144
    },
    {
      "relative_path": "skill-metadata.json",
      "size_in_bytes": 704
    }
  ],
  "skill_md_contents": "---\nname: cargo-segmentation\ndescription: \"Define and use segments — named, saved filters over a Cargo model that become the audience for a batch run, a play trigger, or an export. Triggers: \\\"build a segment of\\\", \\\"filter my contacts where\\\", \\\"who matches this criteria\\\", \\\"save this as a list\\\", \\\"how many companies match\\\", \\\"the Closed-Won segment\\\", \\\"everyone who has not been emailed\\\", \\\"target only accounts that\\\", \\\"what is in this segment\\\", \\\"narrow this down to\\\". Filter JSON uses `conjonction` (not `conjunction`) — misspelling it fails silently. Skip when: running something over the segment — use cargo-orchestration; exporting its rows — use cargo-analytics; ad-hoc SQL over the model — use cargo-storage.\"\nversion: \"1.0.0\"\ncompatibility: 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\nhomepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Segmentation\n\nSegments are the **audience layer** of a Cargo workspace: a named, saved filter over one model that answers \"which records do I mean?\" Everything downstream — a batch run, a play trigger, a CSV export, a change feed — takes a segment (or a segment-shaped filter) as its input.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> Filter condition kinds and operators live in [`../cargo-orchestration/references/filter-syntax.md`](../cargo-orchestration/references/filter-syntax.md) — the single source of truth for filter JSON.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use\n                                        # alternatives: --oauth (browser) · --token <api-token> (CI)\ncargo-ai whoami                         # confirm the active workspace before any write\n```\n\nEvery 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.\n\n## Key concepts\n\n| Term | What it is |\n|---|---|\n| **Filter** | A JSON object (`{conjonction, groups[].conditions[]}`) evaluated against one model's columns. Ephemeral on its own. |\n| **Segment** | A filter **saved** with a name, a `modelUuid`, and a `slug`. Has a `uuid`, a live `recordsCount`, and a history. This is what plays, batches, and exports reference. |\n| **Change** | One computed delta of a segment between two syncs — how many records were `added`, `updated`, `removed`, `unchanged`. The basis of every \"notify me when someone enters this audience\" motion. |\n| **Tracking columns** | The subset of columns (`--tracking-column-slugs`) whose value changes count as an `updated` record. Without them a record only ever registers as added or removed. |\n\n**Filter vs segment — pick deliberately.** A one-off question (\"how many companies have >100 employees?\") wants `segment fetch` with an inline filter and no saved object. An audience you will run something against, schedule against, or track over time wants a real `segment create` — because only a saved segment produces changes.\n\n## Discover resources first\n\nAlways list before creating. A workspace usually already holds the segment you are about to duplicate.\n\n```bash\ncargo-ai segmentation segment list                    # all segments (uuid, name, slug, modelUuid, recordsCount)\ncargo-ai storage model list                           # find the modelUuid a segment must target\ncargo-ai storage column list --model-uuid <uuid>      # the column slugs your filter conditions reference\n```\n\nSegments created automatically by a play are named `GENERATED_PLAY_SEGMENT` and carry `fromPlay: true` — **never edit or remove those by hand**; they belong to the play that owns them.\n\n**Retrieve in the UI:** segments live under the model at `app.getcargo.io/workspaces/<WORKSPACE_UUID>/models/<MODEL_UUID>`. Get `<WORKSPACE_UUID>` from `cargo-ai whoami`.\n\n## Quick reference\n\n```bash\ncargo-ai segmentation segment list\ncargo-ai segmentation segment get <segment-uuid>\ncargo-ai segmentation segment create --name \"<name>\" --model-uuid <uuid> --filter '<json>'\ncargo-ai segmentation segment update --uuid <segment-uuid> --filter '<json>'\ncargo-ai segmentation segment remove <segment-uuid>\ncargo-ai segmentation segment fetch    --model-uuid <uuid> --filter '<json>' --limit 50\ncargo-ai segmentation segment download --model-uuid <uuid> --filter '<json>'\ncargo-ai segmentation change list  --segment-uuid <segment-uuid>\ncargo-ai segmentation change fetch --uuid <change-uuid> --kinds added --limit 50\ncargo-ai segmentation record fetch --model-uuid <uuid> --ids <id[,id…]>\n```\n\n## Building a filter\n\nThe full condition catalogue — every `kind` (`string`, `number`, `date`, `boolean`, `array`, `relation`) and every operator — is in [`../cargo-orchestration/references/filter-syntax.md`](../cargo-orchestration/references/filter-syntax.md). The shape:\n\n```json\n{\n  \"conjonction\": \"and\",\n  \"groups\": [\n    {\n      \"conjonction\": \"and\",\n      \"conditions\": [\n        { \"kind\": \"number\", \"columnSlug\": \"employee_count\", \"operator\": \"greaterThan\", \"value\": 100 },\n        { \"kind\": \"string\", \"columnSlug\": \"email\", \"operator\": \"isNotEmpty\" }\n      ]\n    }\n  ]\n}\n```\n\n> **`conjonction`, not `conjunction`.** The French spelling is intentional and it is the single most expensive typo in the CLI: a misspelled key does not error — the filter silently matches nothing, and you conclude the data is empty. Grep your JSON for `conjunction` before every call.\n\nMatch-everything filter: `{\"conjonction\":\"and\",\"groups\":[]}`.\n\n## Size the audience before you build it\n\nCounting is free; running anything over an audience is not. Establish the size first, then decide.\n\n```bash\n# 1. How many records match? — inline filter, no saved object, 1 row back\ncargo-ai segmentation segment fetch \\\n  --model-uuid <uuid> \\\n  --filter '{\"conjonction\":\"and\",\"groups\":[{\"conjonction\":\"and\",\"conditions\":[\n      {\"kind\":\"number\",\"columnSlug\":\"employee_count\",\"operator\":\"greaterThan\",\"value\":100}]}]}' \\\n  --limit 1\n\n# 2. Happy with the shape? Save it as the real audience.\ncargo-ai segmentation segment create \\\n  --name \"Mid-market accounts\" \\\n  --model-uuid <uuid> \\\n  --filter '<same json>' \\\n  --column-slugs \"name,domain,employee_count\" \\\n  --tracking-column-slugs \"employee_count,funding_stage\"\n```\n\n`segment get <uuid>` then reports `recordsCount` — the authoritative size. Cite that number, not your own estimate, before proposing a paid run over the segment.\n\n## Fetch vs download vs record fetch\n\n| Command | Returns | Use for |\n|---|---|---|\n| `segment fetch --model-uuid --filter` | Records inline as JSON, paginated (`--fetching-limit`, `--fetching-offset`) | Inspecting a handful of rows, counting, previewing a filter before saving it |\n| `segment download --model-uuid --filter` | A signed URL to the full dataset | Handing the whole audience to the user or another tool — see [`../cargo-analytics/SKILL.md`](../cargo-analytics/SKILL.md) |\n| `record fetch --model-uuid --ids <ids>` | Specific records by id | Re-reading rows a change feed just told you about |\n\n`segment fetch --sync` refreshes the underlying data sources before evaluating; `--enrich` returns joined/derived values. Both cost time, so leave them off for a size check.\n\n**Never page a large segment into the conversation.** Use `--limit 3` to see the shape, then `download` for the rest.\n\n## Changes — the delta feed\n\nEvery time a segment syncs, Cargo computes a change: how the membership moved. This is what turns a static list into a signal.\n\n```bash\n# What deltas exist for this segment?\ncargo-ai segmentation change list --segment-uuid <segment-uuid>\n# → { \"changes\": [ { \"uuid\", \"totalRecordsCount\", \"addedRecordsCount\",\n#                    \"updatedRecordsCount\", \"removedRecordsCount\",\n#                    \"unchangedRecordsCount\", \"createdAt\" } ] }\n\n# Which records actually entered the audience in that delta?\ncargo-ai segmentation change fetch --uuid <change-uuid> --kinds added --limit 50\n```\n\n`--kinds` is **required** on `change fetch` and takes `added`, `updated`, `removed`, or `unchanged` (comma-separated). Returned rows carry the `_kind`, `_id`, `_title`, and `_time` meta-columns alongside the model's own columns.\n\n`updatedRecordsCount` is always `0` unless the segment was created with `--tracking-column-slugs` — the tracked columns define what \"updated\" means. Set them at creation time when the segment is meant to feed a monitoring motion.\n\nA segment's most recent delta is also inlined on `segment list` / `segment get` as `lastChange`, so a \"what moved?\" question rarely needs a second call.\n\n## What consumes a segment\n\nSegments are an input, not an outcome. Once one exists:\n\n- **Run something over it** — batch a connector action or workflow across every member: [`../cargo-orchestration/SKILL.md`](../cargo-orchestration/SKILL.md). Batches enroll from a segment; sample 10–20 records and get explicit approval before enrolling the full audience.\n- **Trigger a play on entry** — a play whose trigger is a segment fires as records enter it. Play triggers use `kind: \"filter\"` and generate their own `GENERATED_PLAY_SEGMENT`; see [`../cargo-orchestration/references/examples/plays.md`](../cargo-orchestration/references/examples/plays.md).\n- **Export it** — [`../cargo-analytics/SKILL.md`](../cargo-analytics/SKILL.md) (`segment download` needs `--model-uuid`, *not* `--segment-uuid` — a frequent 400).\n- **Watch it** — alert when the audience empties, stalls, or spikes: [`../cargo-observability/SKILL.md`](../cargo-observability/SKILL.md).\n- **Act on it as GTM** — signal segments (job change, funding, tech intent) drive the recipes in [`../cargo-gtm/SKILL.md`](../cargo-gtm/SKILL.md).\n- **Declare it as code** — `defineSegment` in [`../cargo-cdk/SKILL.md`](../cargo-cdk/SKILL.md) when the audience should live in git.\n\n## Gotchas\n\n- **`conjonction`, never `conjunction`** — silent empty result, no error.\n- **`segment download` takes `--model-uuid`, not `--segment-uuid`.** The filter travels with the request; the segment UUID is not a valid input there.\n- **`change fetch` needs `--uuid` (the *change* UUID) plus `--kinds`.** Passing the segment UUID returns a 400.\n- **`change list` needs `--segment-uuid`.** Calling it bare returns a 400 complaining that `segmentUuid` is undefined.\n- **`--help` on `change` and `record` subcommands prints the parent help** rather than the subcommand's flags (CLI ≥ 1.0.48). Use the Quick reference above; file a report if it still bites.\n- **A segment belongs to exactly one model.** Cross-model audiences are a relationship + filter on the joined column, not two segments.\n- **`fromPlay: true` segments are owned by a play.** Editing one changes what that play targets; removing one breaks it.\n- **`--limit` on a segment caps membership**, it is not a display page size — `--fetching-limit` is the page size.\n\n## When the CLI fails\n\nTwo failed attempts on the same command, or behavior that contradicts this skill, goes to the team:\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"<one-line summary>\" \\\n  --description \"<commands run, errorMessage verbatim, expected vs actual, UUIDs>\"\n```\n"
}