> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Moda setup, data, and investigation commands with flags and example output.

Reference for the documented `moda` CLI workflows. Install and authentication are covered in the [CLI overview](https://docs.moda.dev/cli/overview.md); this page lists each command by area.

Conventions used below:

* Flags accept `--flag=value` or `--flag value`. Boolean flags are `--flag`.
* Data commands call the [Data API](https://docs.moda.dev/data-api/overview.md) (`https://moda.dev/api/v1/data`, `x-api-key` auth) and require an API key (`MODA_API_KEY`, profile, or `~/.moda/config.json`). Numeric ranges are validated before the request is sent.
* Example outputs are shown as `--json` prints them (the raw payload, trimmed to representative fields). Piped and CI invocations get a `moda.agent.v1` envelope instead, with the same payload under `data` — see [Using the CLI from agents and CI](https://docs.moda.dev/cli/agents.md).
* Requests time out after 30 seconds per attempt. Reads (GET) retry up to 3 times on 429/5xx and network errors. Writes never retry automatically, because a 5xx or dropped connection can arrive after the server already applied the write (exception: `ask` uses a 250-second timeout and retries at most once, on network errors only).
* Commands follow `moda <noun> <verb>`: `traces list|search|get|state|spans`, `problems list|get|impact|feedback|reopen|linear|link`, `detections list|tools`, `review`, `reviews list`, `skills push`. The older names (`moda context`, `moda search`, `moda world-state`, `moda audit`, `moda problem`, `moda problem-feedback`, `moda emotions`, `moda frustrations`, `moda tool-failures`, `moda false-positive`, `moda skills sync`, ...) still work with the same flags and output, and print a deprecation notice (`meta.deprecated` in agent output); `moda <old-name> --help` names the new form.
* A trace is one full agent run, identified by its `conversation_id` (the trace ID). Data API paths and JSON fields keep the `conversation` / `conversation_id` names for backwards compatibility, and the legacy command and flag names noted below remain as aliases.

## Setup and diagnostics

### moda init

Interactive project setup with browser login, tenant selection, API key provisioning, the moda-cli skill for your coding agents, and optional SDK integration through your coding agent. Init uploads nothing from your repository to Moda. Use `--yes` for non-interactive setup.

```bash theme={"dark"}
moda init --yes --tenant-id=1f7c9a2e-4b3d-4c8e-9a1b-2d3e4f5a6b7c
```

| Flag | Description |
| - | - |
| `--yes` | Accept all defaults (non-interactive). |
| `--tenant-id=ID` | Tenant to provision (required non-interactively with multiple tenants; `MODA_TENANT_ID` also honored). |
| `--agent-skill` / `--no-agent-skill` | Install the moda-cli skill into detected coding agents (`.claude/skills/moda-cli`, `.cursor/rules`; the default), or skip it. |
| `--sdk-integrate` / `--no-sdk-integrate` | Run your coding agent to install and wire the Moda SDK, or skip it. |
| `--verification-id=ID` | Tag the SDK integration's test trace with this id instead of a generated one. The onboarding page passes its `onb_` id so its waiting room sees the trace. |
| `--connect-code=CODE` | Sign in with the one-time `mcc_` code included in the command copied from the Moda onboarding page, instead of opening a browser. Codes last 10 minutes and work once; only a real member of the workspace can mint or redeem one. The code signs in even when the CLI already has a session (the new session replaces it, and init says whose it replaced), and init provisions the code's workspace unless `--tenant-id` names it. A rejected code falls back to the existing session or to browser sign-in. |
| `--offline` | Skip the final online validation check. |

### moda provision

Headless API key provisioning for CI and agents. Prints exactly one JSON credentials document to stdout; exits 4 without a stored session and 5 when a multi-tenant account omits `--tenant-id`. Flags: `--tenant-id`, `--label` (default: hostname), `--save`, `--profile`. Full behavior and output are documented in the [CLI overview](https://docs.moda.dev/cli/overview.md#headless-provisioning-moda-provision).

```bash theme={"dark"}
moda provision --tenant-id=1f7c9a2e-4b3d-4c8e-9a1b-2d3e4f5a6b7c --label=ci-runner
```

### moda status

Concise local setup state (config, credentials, synced artifacts).

```bash theme={"dark"}
moda status --json
```

### moda doctor

Diagnoses local setup and data flow: config, auth, prompt manifest, harness artifacts, and (unless `--offline`) an online connectivity check. Flags: `--json`, `--offline`, `--online`.

```bash theme={"dark"}
moda doctor --json
```

### moda manifest

Machine-readable description of the CLI protocol: commands, global flags, env vars, exit codes, and stream events. `moda --json-schemas` prints the JSON Schemas for the agent output contract.

```bash theme={"dark"}
moda manifest --json
```

```json Output (trimmed) theme={"dark"}
{
  "schema_version": "moda.manifest.v1",
  "cli_version": "1.26.0",
  "invocations": ["bunx @moda-ai/cli", "npx -y @moda-ai/cli", "moda"],
  "exit_codes": [
    { "code": 0, "name": "ok", "meaning": "Command completed successfully." },
    { "code": 4, "name": "auth_required", "meaning": "Run login_command, then resume." }
  ]
}
```

### moda profiles / moda config

`moda profiles list|use <name>|create <name>|doctor [name]` manage local profiles (`prod`, `staging`, `local` by default). `moda config show [--profile=NAME]` prints the resolved configuration.

```bash theme={"dark"}
moda profiles use staging
moda config show
```

## Sessions

The CLI has two independent credentials, and the `auth` commands report both:

| Credential | Obtained by | Used for |
| - | - | - |
| `moda_ct_` session token | `moda auth login` (browser PKCE) | Control plane: `provision`, `init`, `auth token` |
| `moda_sk_` API key | `MODA_API_KEY`, `moda provision`, `moda init` | Every data command |

An API key on its own is enough for all data commands. You only need a browser session to mint new keys or run the onboarding wizard.

### moda auth login

Opens the browser PKCE login flow and stores a 30-day sliding CLI session. `--screen=signup` opens the signup screen instead.

```bash theme={"dark"}
moda auth login
```

```json Output theme={"dark"}
{ "status": "authenticated", "method": "browser", "profile": null }
```

**Non-interactive login.** `--api-key` authenticates with an API key and never opens a browser. The key is validated against the Data API before anything is written, then saved to `~/.moda/config.json`.

Three ways to supply it, safest first:

| Form | Key visible in argv? |
| - | - |
| `MODA_API_KEY` + `--api-key` or `--non-interactive` | No |
| `--api-key-stdin` (piped) | No |
| `--api-key=<key>` | **Yes** — readable by local process monitors and recorded in shell history |

```bash theme={"dark"}
MODA_API_KEY=moda_sk_... moda auth login --non-interactive
printf %s "$KEY" | moda auth login --api-key-stdin
moda auth login --api-key=moda_sk_...   # warns: key is exposed in argv
```

```json Output theme={"dark"}
{
  "status": "authenticated",
  "method": "api_key",
  "profile": null,
  "apiKeyCredential": { "masked": "moda_sk_...p3RQ" },
  "tenant_id": "43773cd2-7c6b-4087-887a-67f40266c765",
  "persisted": true
}
```

A key the API rejects (401/403) and a key that cannot be validated (network failure) both fail without persisting anything. `--non-interactive` takes the same path but additionally guarantees no browser opens even when no key is found — it exits with the commands that would mint one.

If `MODA_API_KEY` holds a **different** key than the one being saved, the environment still wins for every later command. Login reports this rather than a clean success: it warns on stderr, sets `"shadowed_by_env": true` and `"effective_credential": "env"`, and exits 3 (degraded). Unset `MODA_API_KEY` to use the saved credential.

### moda auth status

Reports the state of both credentials without ever opening a browser. Exit code 0 = at least one usable credential, 4 = neither. `--online` adds 5-second probes and reports where requests go: `GET /api/v1/data/whoami` (served by the frontend proxy and the backend alike, so it also confirms a base URL pointed at the backend) and, when a browser session exists, `GET /api/cli/context` (frontend only).

```bash theme={"dark"}
moda auth status --online --json
```

```json Output theme={"dark"}
{
  "loggedIn": true,
  "authenticated": true,
  "apiKeyCredential": {
    "present": true,
    "source": "env",
    "masked": "moda_sk_...p3RQ",
    "tenantId": "43773cd2-7c6b-4087-887a-67f40266c765"
  },
  "profile": null,
  "expiresAt": "2026-09-15T09:14:02.000Z",
  "user": { "email": "dev@example.com" },
  "online": {
    "baseUrl": "https://moda.dev",
    "reachable": true,
    "ok": true,
    "tenantCount": 1,
    "session": { "reachable": true, "status": 200, "ok": true },
    "dataApi": {
      "reachable": true, "status": 200, "ok": true,
      "tenantId": "43773cd2-7c6b-4087-887a-67f40266c765", "tenantName": "Acme Support",
      "keyKind": "tenant", "scope": "full"
    }
  }
}
```

`online.baseUrl` is the URL every request uses. `reachable` is true when either probe got an HTTP response; `ok` when every credential present was accepted. `dataApi` carries the key's tenant, kind and scope from `/whoami`; without a key it is an unauthenticated reachability check (a live Data API answers 401). `session` is present only with a browser session; a 404 there with a reachable `dataApi` means the base URL is the backend, and a warning says browser login needs the frontend URL. A 403 for an unknown or inaccessible tenant leaves the key counted and adds a warning naming the tenant fix.

`loggedIn` covers the browser session only; `authenticated` is true when either credential is usable, and the exit code follows `authenticated`. `apiKeyCredential.source` is `env`, `profile`, or `config` — `env` tells you a `MODA_API_KEY` is shadowing anything stored on disk. The raw key is never emitted.

Without `--online` this command does no network I/O, so `authenticated` reflects that a credential is **present**, not that it still works, and `apiKeyCredential.verified` is `null` (not checked). With `--online` the API key is probed too: a key the API rejects gets `verified: false`, stops counting toward `authenticated`, and exits 4. A key that cannot be reached stays `verified: false` but still counts, so a network blip never declares a good credential dead. Use `moda auth whoami` to verify a key on demand.

### moda auth token

Prints the bare session token plus a newline to stdout in every output mode (built for `$(moda auth token)` composition). Exits 4 when logged out; with `--json` it prints `{"error":"not_authenticated"}` instead of prose.

```bash theme={"dark"}
moda auth token
```

### moda auth api-key

Prints the saved `moda_sk_` API key (the one `moda init` stored, or `MODA_API_KEY` when set) plus a newline, in every output mode. Built for piping into one process or a secret store without echoing it. Exits 4 when no key is saved; with `--json` it prints `{"error":"no_api_key"}` instead of prose.

```bash theme={"dark"}
MODA_API_KEY="$(moda auth api-key)" npm run dev
moda auth api-key | wrangler secret put MODA_API_KEY
```

### moda auth whoami

Shows the authenticated user, session expiry, and available tenants.

```bash theme={"dark"}
moda auth whoami
```

With no browser session but a usable API key, it reports the key credential instead of failing — this is the command to run to prove a non-interactive login worked.

```json Output theme={"dark"}
{
  "profile": null,
  "credential": "api_key",
  "apiKeyCredential": {
    "source": "env",
    "masked": "moda_sk_...p3RQ",
    "verified": true
  },
  "tenant_id": "43773cd2-7c6b-4087-887a-67f40266c765",
  "session": null,
  "context": null
}
```

`verified: true` means the API accepted the key just now. If the API is unreachable the command exits 3 (degraded) with `verified: false` rather than claiming an identity it could not confirm. A rejected key is an error, not a logged-out state.

### moda auth logout

Revokes the session server-side (best effort) and clears local credentials — including the stored API key. If `MODA_API_KEY` is set in the environment it still takes precedence afterwards; unset it to fully sign out.

```bash theme={"dark"}
moda auth logout
```

```json Output theme={"dark"}
{ "status": "logged_out", "profile": null, "api_key_cleared": true }
```

## Production data

These commands reject flags they don't take: a typo or an unsupported filter exits `1` with the valid flags and a "did you mean", instead of being silently ignored. A flag the chosen mode would not send, a value flag given no value (`--user-id` alone), a malformed number (`--limit=0x10`, `--limit=2.5`) and an extra argument after an id fail the same way. `--days-back` and `--days_back` are the same flag. `--dry-run` is refused on these reads before any request is sent, and an unknown `--profile`/`MODA_PROFILE` fails instead of falling back to another profile. `traces`, `search`, and `clusters` window with `--time-range`, and the signal commands (`emotions`, `frustrations`, `hallucinations`, `tool-failures`, and others) window with `--days-back`. The other spelling is rewritten when it names the same span (`--days-back=7` is `--time-range=7d`, `--time-range=30d` is `--days-back=30`); one with no exact match, or both at once, fails.

### moda overview

Health briefing built from production data: data-flow status, local sync state (harness, prompts, skills), and the top finding. On a TTY it renders prose; `--raw` returns the raw Data API `/overview` payload instead.

```bash theme={"dark"}
moda overview --days-back=30 --raw --json
```

```json Output (trimmed) theme={"dark"}
{
  "period": { "days": 30 },
  "conversations": { "total": 1841, "trend_pct": 6.2 },
  "frustrations": { "total_analyzed": 412, "frustrated": 9, "at_risk": 14, "rate_pct": 2.2 },
  "tool_failures": { "total": 41, "conversations": 33, "tools": 3 },
  "top_clusters": [],
  "recent_activity": [],
  "processing": {
    "detectors": [
      { "family": "emotion", "enabled": false, "setting": "signals.frustration" },
      { "family": "custom_signal", "enabled": true, "setting": "signals.custom_signals" },
      { "family": "laziness", "enabled": true, "setting": null, "reason": "no_tenant_switch" }
    ]
  }
}
```

`processing.detectors` (`detectors` in the briefing) says whether each detector runs for the tenant: `enabled: false` means it is switched off (`setting` names the switch, from Settings → Account → Signal processing), `null` means the state could not be read, and `setting: null` means the detector has no tenant switch. A detector that is off reports zero detections, which does not mean traces are clean, so the briefing warns about it. The emotion stage, frustration included, reads `signals.frustration`.

| Flag | Default | Description |
| - | - | - |
| `--days-back` | 7 | Look-back window (1–90). |
| `--raw` | off | Return the raw `/overview` payload instead of the briefing. Not combinable with the trend flags. |
| `--compare` | off | Add `trends`: the dashboard KPIs for the window against the previous window of equal length (see below). |
| `--series` | off | Add `trends.series`: `[bucket, value]` arrays per hour (windows up to 2 days) or per day. Implies `--compare`. |
| `--since` | — | Trends window start (ISO date or datetime, UTC unless an offset is given). Not with `--days-back`. Implies `--compare`. |
| `--until` | now | Trends window end, inclusive. Needs `--since`. |
| `--agent-name` | — | Scope the trends `overview` section to one sub-agent (the Analytics agent selector). Names are in `trends.agent.options`. |
| `--unit` | `conversation` | Denominator of `trends.rates`: `conversation`, `segment` or `turn`. |

#### Did my change make it worse?

```bash theme={"dark"}
moda overview --compare --since=2026-10-17T14:00:00Z
moda overview --series --since=2026-10-17T14:00:00Z --agent-name=planner
```

`trends` comes from `GET /v1/data/trends`, which runs the dashboard's own loaders. Every one of them defines the previous window as the span of equal length just before the window, so `--since=<deploy time>` compares the time since the deploy with the same length of time before it. There is no separate `--compare-to` flag for that reason. Each figure is `{ current, previous, delta, delta_pct, spike? }`: `delta` is current minus previous (percentage points for a `_pct` rate) and `delta_pct` is the relative change.

```json Output (trends, trimmed) theme={"dark"}
{
  "window": { "from": "2026-10-17T14:00:00.000Z", "to": "2026-10-18T14:00:00.000Z", "previous_from": "2026-10-16T14:00:00.000Z", "previous_to": "2026-10-17T14:00:00.000Z", "days": 1, "bucket": "hour" },
  "agent": { "selected": "__all__", "label": "All agents", "options": [{ "agent": "planner", "label": "planner", "conversations": 812 }] },
  "overview": {
    "conversations": { "current": 1104, "previous": 1180, "delta": -76, "delta_pct": -6.4 },
    "negative_emotion_rate_pct": { "current": 31.2, "previous": 24.9, "delta": 6.3, "delta_pct": 25.3, "of": "analyzed traces", "n": { "current": [344, 1102], "previous": [292, 1173] } }
  },
  "rates": { "unit": "conversation", "units": { "current": 1104, "previous": 1180, "delta": -76, "delta_pct": -6.4 }, "laziness_pct": { "current": 0.4, "previous": 0.2, "delta": 0.2, "delta_pct": 100, "flagged": 4 } },
  "detectors": { "tool_failure": { "failures": { "current": 520, "previous": 310, "delta": 210, "delta_pct": 67.7, "spike": true } } },
  "series": { "bucket": "hour", "negative_emotion_rate_pct": [["2026-10-17T14:00Z", 28.1], ["2026-10-17T15:00Z", 33.4]] }
}
```

| Section | Dashboard source |
| - | - |
| `overview` | Analytics overview: traces, messages, negative emotion rate (per analyzed trace), failed tool calls (per call), hallucinations (a count). The only section `--agent-name` scopes. |
| `problems` | Problems trend card: analysed traces, traces with a signal, signal rate. `--days-back` windows only. |
| `rates` | Signals overview rate cards: each detector's share of units with a detection, per `--unit`. |
| `detectors` | Detector tab KPI tiles for emotion, tool failures, laziness and hallucination. |

Sections can disagree on a rate because each uses its own denominator; `rate_note` says which. With `--agent-name`, `problems`, `rates` and `detectors` are left out (their loaders have no sub-agent filter) and `trends.notes` says so. The `overview` section is the slowest read: a 30-day window on a large workspace can take about 40 seconds, and the CLI waits up to 90. A figure whose read failed is `null` with `unavailable: true`, never zero.

### moda clusters

Browse the use-case cluster hierarchy from the latest completed cluster run.

```bash theme={"dark"}
moda clusters --parent-id=node_12
```

```json Output (trimmed) theme={"dark"}
{
  "cluster_run": { "id": "run_2031", "num_categories": 8, "num_clusters": 42, "num_segments": 1930, "completed_at": "2026-08-10T00:00:00Z" },
  "breadcrumb": [{ "node_id": "node_12", "label": "Billing & refunds" }],
  "clusters": [
    { "node_id": "node_44", "label": "Refund retries", "summary": "Users retry failed refunds", "keywords": ["refund", "retry"], "segment_count": 118, "has_children": false, "depth": 1 }
  ],
  "meta": { "total_clusters": 42, "total_segments": 1930 }
}
```

| Flag | Default | Description |
| - | - | - |
| `--parent-id` | — | Drill into a category (omit for the root level). |
| `--time-range` | `all` | `all`, `1h`, `24h`, `3d`, `7d`, `30d`, `90d`. |
| `--cohort` | — | `builtin:<key>` or a saved cohort id: only the clusters the cohort's users reach, with the cohort's `segment_count` (the dashboard Topics page's cohort counts). `meta.cohort_segments` sums the level; `total_clusters`/`total_segments` stay the whole run. Needs `--time-range` `all`, `3d`, `7d` or `30d`; also scopes `--search`. |

Instead of walking the hierarchy, find a cluster by meaning with `--search`, or resolve a node deep link deterministically with `--node-id`:

```bash theme={"dark"}
moda clusters --search="calendar scheduling conflicts" --limit=3
```

```json Output (trimmed) theme={"dark"}
{
  "clusterRunId": "run_2031",
  "query": "calendar scheduling conflicts",
  "search_mode": "hybrid",
  "matches": [
    {
      "node_id": "node_36",
      "parent_id": "node_3",
      "node_type": "cluster",
      "label": "Managing and rescheduling calendar appointments",
      "keywords": ["rescheduling", "calendar"],
      "segment_count": 24,
      "ancestor_path": [{ "nodeId": "node_3", "label": "Scheduling", "depth": 0 }],
      "similarity": 0.81
    }
  ]
}
```

| Flag | Default | Description |
| - | - | - |
| `--search` | — | Cluster search query (2–200 characters). Routes to task-cluster search instead of the hierarchy walk. |
| `--node-id` | — | Resolve one node exactly (deep link); bypasses ranked search. |
| `--mode` | `hybrid` | `fuzzy`, `semantic`, `hybrid` — cluster search mode. `search_mode` in the response is what actually ran. |
| `--limit` | 30 | 1–50 (cluster search only). |

### moda cluster-traces

List traces in one cluster node. Legacy alias: `moda cluster-conversations`.

```bash theme={"dark"}
moda cluster-traces node_44 --limit=2
```

```json Output (trimmed) theme={"dark"}
{
  "cluster": { "node_id": "node_44", "label": "Refund retries", "segment_count": 118 },
  "conversations": [
    { "conversation_id": "conv_5e1a9c2b7d3f4680", "summary": "User retries a failed refund three times", "message_count": 21 }
  ],
  "pagination": { "limit": 2, "offset": 0, "total": 118, "has_more": true }
}
```

| Argument / flag | Default | Description |
| - | - | - |
| `<node_id>` | required | Cluster node ID. |
| `--limit` | 10 | 1–100. |
| `--offset` | 0 | Pagination offset (≤ 10,000). |

An unknown node ID returns `cluster: null` with an empty list, not an error.

### moda traces

Search and filter traces by summary text, cluster, user, environment, world state, and outcome. Legacy alias: `moda conversations`.

```bash theme={"dark"}
moda traces --world-state="refund,enterprise" --outcome=negative --limit=2
```

```json Output (trimmed) theme={"dark"}
{
  "conversations": [
    {
      "conversation_id": "conv_5e1a9c2b7d3f4680",
      "summary": "User retries a failed refund three times",
      "message_count": 21,
      "first_timestamp": "2026-08-14T18:02:10Z",
      "last_timestamp": "2026-08-14T18:41:55Z",
      "cluster_id": "node_44",
      "cluster_name": "Refund retries",
      "environment": "production"
    }
  ],
  "search_mode": "keyword",
  "pagination": { "limit": 2, "offset": 0, "total": 7, "has_more": true }
}
```

| Flag | Default | Description |
| - | - | - |
| `--search` | — | Ranked trace search over tasks (stored summaries when task search is unavailable) and message bodies: hybrid when embeddings exist, else keyword. `total_kind` is `matches` for a keyword run and `candidate_pool` for a ranked run (results may not contain the words). |
| `--cluster-id` | — | Filter by cluster node ID. |
| `--user-id` | — | Filter to one user. |
| `--time-range` | `all` | `all`, `1h`, `24h`, `3d`, `7d`, `30d`, `90d`. |
| `--since` / `--until` | — | Absolute UTC bounds, ISO 8601 date or datetime, both inclusive (a date-only `--until` covers that day). Intersect `--time-range`; at most 366 days. |
| `--environment` | `all` | `all`, `development`, `staging`, `production`. |
| `--world-state` | — | Keyword match (case-insensitive substring) over each trace's world state: its task goals and summaries, and for a trace the task engine owns its facts and the user's profile; comma-separated terms are ANDed. Max 200 characters. |
| `--outcome` | `any` | `negative` (a user frustration was detected in the trace) or `positive` (none was detected, including traces not yet analyzed). |
| `--include-world-state` | off | Attach each result's world-state summary (`hasData`, fact counts per segment; one extra request per row). |
| `--cohort` | — | `builtin:<key>` or a saved cohort id: only traces of the cohort's current members, as the dashboard trace list scopes them. With `--search` the keyword path runs. |
| `--limit` / `--offset` | 20 / 0 | Pagination (limit 1–100, offset ≤ 10,000). |

Each row also carries the state the dashboard trace list shows, read through the same loader: `processing_status` (`pending` until the pipeline completes the trace, then `complete`), `error_message`, `indexed_at` (when the trace was indexed) and `membership_score` (use-case confidence for `cluster_id`, 0–1; null when the dashboard places the trace in another use case). A pending trace is not fully processed, so its detections may be incomplete and missing detections do not mean it is clean; the CLI warns when a page holds pending or errored traces. The fields are null for a trace not in the list index yet, and `"trace_state": "unavailable"` means the state could not be read. `moda traces get` returns the same values in `trace_state`.

### moda traces search

Message-grain search across traces: keyword, semantic, or hybrid.

```bash theme={"dark"}
moda traces search "refund failed" --mode=hybrid --time-range=7d --limit=1
```

```json Output theme={"dark"}
{
  "query": "refund failed",
  "search_mode": "hybrid",
  "degrade_reason": "none",
  "results": [
    {
      "conversation_id": "conv_5e1a9c2b7d3f4680",
      "message_index": 12,
      "role": "user",
      "timestamp": "2026-08-14T18:22:41Z",
      "snippet": "The refund failed again after I retried the payment.",
      "score": 0.0328,
      "cluster_id": "node_44",
      "cluster_name": "Refund retries",
      "conversation_summary": "User retries a failed refund three times"
    }
  ],
  "totals": { "matched_conversations": 18, "prior_window_matched_conversations": 25 },
  "pagination": { "limit": 1, "returned": 1, "has_more": true }
}
```

| Argument / flag | Default | Description |
| - | - | - |
| `"<query>"` | required | 1–500 characters. |
| `--mode` | `hybrid` | `keyword`, `semantic`, or `hybrid`. |
| `--user-id` | — | Filter to one user. |
| `--time-range` | `all` | `all`, `1h`, `24h`, `3d`, `7d`, `30d`, `90d`. |
| `--since` / `--until` | — | Absolute UTC bounds, ISO 8601 date or datetime, both inclusive (a date-only `--until` covers that day). Intersect `--time-range`; at most 366 days. |
| `--limit` | 20 | 1–100. No offset — pagination is limit-only. |
| `--include-tool-io` | off | Include tool input/output blocks in results. |

`search_mode` in the response is the mode that actually ran: semantic and hybrid degrade to keyword when embeddings are unavailable (`degrade_reason: "semantic_unavailable"`, retry may fix) or no hit clears the relevance floor (`"below_relevance_floor"`, retry will not fix). Scores are not comparable across modes. Each result carries `conversation_id` + `message_index` — feed them to `moda traces get`.

If message-level search returns nothing but whole traces match, the CLI returns those traces instead (the same search as `moda traces --search`). Each result then has `match_grain: "trace"` and no score or message index, and a `fallback` block (`source: "traces_search"`, `search_mode`, `total`, `total_kind`) plus a warning explain it. When `fallback.search_mode` is not `keyword`, the traces are relevance-ranked related traces that may not contain the exact words, and `total` is the candidate pool rather than a match count. `fallback.has_more` and a `moda traces --search ... --offset` next command cover paging. With `--mode=keyword` the trace-level search is not run, because it is relevance-ranked and could not be shown as literal matches: a warning says so and `next_commands` offers the `moda traces --search` command instead. If the fallback request fails, the response carries a warning rather than looking like a clean empty result.

### moda traces get

Windowed context around one message in a trace.

```bash theme={"dark"}
moda traces get conv_5e1a9c2b7d3f4680 --msg-index=12 --window=1
```

```json Output (trimmed) theme={"dark"}
{
  "conversation_id": "conv_5e1a9c2b7d3f4680",
  "total_messages": 21,
  "summary": "User retries a failed refund three times",
  "context": {
    "center_index": 12,
    "from_index": 11,
    "to_index": 13,
    "messages": [
      { "index": 12, "role": "user", "content": "The refund failed again after I retried the payment.", "tool_calls": [], "tool_results": [], "timestamp": "2026-08-14T18:22:41Z" }
    ]
  }
}
```

| Argument / flag | Default | Description |
| - | - | - |
| `<conversation_id>` | required | Trace ID to read (or `--conversation-id`). |
| `--msg-index` | middle of the trace | Center message index. `null` or empty means no anchor (with a warning). |
| `--window` | 2 | Turns of context per side (0–5). `0` returns only the anchor message plus `total_messages`; above 5 is clamped to 5 with a warning. |
| `--metadata-only` | off | Returns only `summary` and `total_messages`, with `messages: []` and `metadata_only: true`. Can't be combined with `--window`. |
| `--all` | off | Whole transcript in order; can't be combined with `--msg-index`, `--window` or `--metadata-only`. |
| `--ids-from` | — | Batch: read targets one per line from `-` (stdin) or a file. |

**Batch reads.** Pass up to 25 targets in one call, as several positionals or with `--ids-from`, instead of one `moda traces get` per trace. A target is `<conversation_id>` or `<conversation_id>@<msg_index>` (the anchor; ids may contain `:`); `--window`, `--metadata-only` and `--all` apply to every target. A line may also be JSON, `{"id": "...", "msg_index": N}`, which is the only spelling for an id ending in `@<digits>`. Targets are read 4 at a time.

```bash theme={"dark"}
moda traces get telegram:8565459080@12 linq:c6f88988-aa@3 --window=1
printf '%s\n' conv_a@4 conv_b | moda traces get --ids-from=-
```

```json Output (trimmed) theme={"dark"}
{
  "results": [
    { "target": "telegram:8565459080@12", "ok": true, "data": { "conversation_id": "telegram:8565459080", "total_messages": 40, "context": { "center_index": 12, "messages": [] } } },
    { "target": "linq:c6f88988-aa@3", "ok": false, "error": { "code": "not_found", "message": "No trace found for id \"linq:c6f88988-aa\" in this tenant." } }
  ],
  "requested": 2,
  "returned": 2,
  "succeeded": 1,
  "failed": 1,
  "has_more": false,
  "remaining_targets": []
}
```

A failed target does not fail the call: the exit code is 1 only when every target failed. In `--agent` mode, if the combined envelope would go over the byte limit, the items that fit are returned, `has_more` is `true`, and `remaining_targets` plus a `next_commands` entry read the rest. One positional id keeps the single-trace output shown above.

### moda traces state

A trace's [world state](https://docs.moda.dev/concepts/analysis.md#world-state) as it is now: its tasks (open and finished, each with a timeline; a subtask names its parent task), the facts recorded for it, and the user's durable profile. Tasks and facts come from the task engine for a trace it owns (`source: "task_engine"`), and from the task tracker otherwise. There is no history of state changes.

```bash theme={"dark"}
moda traces state conv_5e1a9c2b7d3f4680
```

```json Output (trimmed) theme={"dark"}
{
  "hasData": true,
  "userId": "user_1842",
  "userDurableProfile": { "slots": { "user.plan": { "value": "enterprise" } }, "updatedAt": "2026-08-14T18:30:02Z", "slotCount": 6 },
  "conversationWarmstart": null,
  "segments": [
    {
      "segmentIndex": 0,
      "startMsgIdx": 0,
      "endMsgIdx": 0,
      "slots": {},
      "openThreads": [
        { "id": "refund_retry", "status": "open", "summary": "Retry the failed refund", "timeline": [{ "text": "Refund failed", "msg_index": 9 }], "subgoals": [] }
      ],
      "slotCounts": { "durable": 0, "segmentLocal": 0, "total": 0 }
    }
  ],
  "summary": { "segmentCount": 1, "lastUpdatedAt": "2026-08-14T18:30:02Z" }
}
```

`hasData: false` means no tasks or facts have been tracked for the trace (yet), or the trace does not exist; the CLI adds a warning, not an error.

| Argument / flag | Default | Description |
| - | - | - |
| `<conversation_id>` | required | Trace ID to read. |
| `--summary-only` | off | Return `segmentSummaries` (fact counts and top facts per segment) instead of the segments. |

**Retired flags.** World-state snapshots (`--snapshot`, with `--msg-index`, `--block-index`, `--segment-index`) and replay (`--replay`, with `--message-count`, `--format=frames|fold-inputs`) folded the world-state event log, which Moda no longer writes. The CLI rejects them with `retired_flag` (exit 1) and sends nothing; `errors[0].suggested_commands` names the replacements: `moda traces state <id>` for the current tasks and facts, and `moda traces get <id>` for the messages (`--msg-index=N` for a snapshot's turn, `--all` in place of a replay). `--event-limit` is still accepted and ignored, with a warning.

### moda traces spans

Raw OpenTelemetry span read for one trace, looked up by its trace ID (`conversation_id`) or by an OTLP `trace_id`: hierarchy, orphans, duplicates. Useful for debugging ingestion.

```bash theme={"dark"}
moda traces spans conv_5e1a9c2b7d3f4680
```

```json Output (trimmed) theme={"dark"}
{
  "summary": {
    "total_spans": 18,
    "by_type": { "llm": 9, "tool": 8, "agent": 1 },
    "trace_ids": ["4bf92f3577b34da6a3ce929d0e0e4736"],
    "orphan_count": 0,
    "duplicate_count": 0
  },
  "spans": [
    { "span_id": "00f067aa0ba902b7", "parent_span_id": null, "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "type": "llm" }
  ],
  "orphans": [],
  "duplicates": []
}
```

| Argument / flag | Default | Description |
| - | - | - |
| `<conversation_id\|trace_id>` | required | ID to audit. |
| `--kind` | `auto` | How to interpret the ID: `auto` (try it as an OTLP `trace_id`, then as a `conversation_id`), `trace`, `conversation`. |
| `--include-raw` | off | Attach verbatim raw event bodies. |
| `--limit` | 200 | Max spans (1–1,000). |
| `--ids-from` | — | Batch: read ids one per line from `-` (stdin) or a file. |

**Batch reads.** `moda traces spans <id1> <id2> ...` (or `--ids-from`) audits up to 25 ids in one call and returns the same `{ results: [{ target, ok, data | error }], ... }` shape as batch `moda traces get`. Ids are taken verbatim; `--cursor` cannot be combined with a batch, so follow each item's `next_commands` to page one trace.

### moda traces findings

Everything Moda flagged on a trace in one read: emotion, laziness, hallucination, tool failure and custom signal detections, each anchored to its message (`msg_index`), plus the Problems the trace is evidence for. There is no time window, so a trace older than `--days-back` does not read clean the way `moda detections list --conversation-id` does. Backed by `GET /v1/data/conversations/:id/findings`, which reads each family through the loader the dashboard uses.

```bash theme={"dark"}
moda traces findings conv_5e1a9c2b7d3f4680
moda traces findings conv_5e1a9c2b7d3f4680 conv_7a21 conv_9f03   # up to 25 ids (or --ids-from=-|<file>)
```

```json Output (agent, trimmed) theme={"dark"}
{
  "conversation_id": "conv_5e1a9c2b7d3f4680",
  "window": "all",
  "summary": { "detections": 21, "by_family": { "emotion": 5, "laziness": 1, "hallucination": 0, "tool_failure": 15, "custom_signal": 0 }, "problems": 2 },
  "families": {
    "emotion": { "state": "found", "count": 5, "enabled": true, "processed": true,
      "top": [{ "msg_index": 808, "family": "frustration", "polarity": "negative", "score": 0.95, "quote": "Why dont u write like me??" }], "more": 4 },
    "hallucination": { "state": "none", "count": 0, "enabled": null, "processed": true, "verified_claims": 1, "top": [] },
    "custom_signal": { "state": "not_run", "count": 0, "enabled": false, "processed": null, "top": [] }
  },
  "problems": { "count": 2, "processed": true,
    "top": [{ "problem_id": "7c6172a2-e37a-55f5-bbd2-1e8d72baf78b", "title": "Drafts recycle published or recently delivered content", "attribution_count": 1, "lifecycle": "open", "in_book": true }] }
}
```

Each family's `state` says what an empty result means: `found`; `none` (its detector ran on this trace and found nothing); `not_run` (the detector is off for the workspace, or has not processed this trace yet); `unknown` (nothing found, and the detector records nothing for a clean trace, as laziness does). Only `none` means clean. `enabled` is the workspace processing switch where one exists (`null` when there is none), and `processed` whether this trace has been through the detector (`null` when that is not recorded). `hallucination` lists contradicted claims and counts verified ones in `verified_claims`. A Problem's `in_book` says whether it is in the current Problems list; attributions older than the list's window are included. `next_commands` open each anchor with `moda traces get <id> --msg-index=<n> --window=2`. A missing trace is a `not_found` error (an item error in a batch).

| Argument / flag | Default | Description |
| - | - | - |
| `<conversation_id>` | required | One or more trace IDs (up to 25). |
| `--limit` | 3 | Detections shown per family in agent and human output (1–50). Counts always cover every detection. |
| `--ids-from` | — | Batch: read ids one per line from `-` (stdin) or a file. |

`--json` prints the full response: up to 50 rows per family with all their fields, and `count` for the total.

### moda detections list, family frustration

User frustration detections with evidence quotes. The CLI adds an `anchor` block per row (derived from `key_turns`/`user_quotes`) so agents can jump straight to `moda traces get`.

`moda detections list --family=frustration` is the frustration family of [`moda detections list --family=emotion`](#moda-detections-list-family-emotion) in the legacy field names: it reads the same data as `moda detections list --family=emotion:frustration` and the dashboard's Signals page, so the numbers match. `total_analyzed` is `conversations_analyzed`, `frustrated_count` is `by_family.frustration`, and `at_risk_count` counts listed rows with `is_frustrated: false` and `risk_score` ≥ 0.5. Rows also carry the emotion fields (`detection_id`, `family`, `elicitor`, `detection_grade`, `downgrade_reason`), and the response says `"source": "emotion_detections"`. Earlier versions read a legacy table that held only part of the analyzed traces, so they could disagree with `emotions`.

```bash theme={"dark"}
moda detections list --family=frustration --days-back=14 --limit=1
```

```json Output (trimmed) theme={"dark"}
{
  "summary": { "total_analyzed": 412, "frustrated_count": 9, "at_risk_count": 14, "frustration_rate_pct": 2.2 },
  "frustrations": [
    {
      "conversation_id": "conv_5e1a9c2b7d3f4680",
      "is_frustrated": true,
      "frustration_score": 0.91,
      "risk_score": 0.88,
      "primary_cause": "Refund tool errored twice; the agent asked the user to retry.",
      "user_quotes": [{ "turn": 12, "quote": "This is the third time I am asking.", "signal": "exasperation" }],
      "key_turns": [12, 16],
      "message_count": 21,
      "detected_at": "2026-08-15T07:03:11Z",
      "anchor": {
        "kind": "frustration",
        "conversation_id": "conv_5e1a9c2b7d3f4680",
        "msg_index": 12,
        "signal": "exasperation",
        "quote_preview": "This is the third time I am asking.",
        "all_turns": [12, 16],
        "no_anchor": false
      }
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "total": 9, "has_more": true }
}
```

| Flag | Default | Description |
| - | - | - |
| `--days-back` | 7 | 1–90. |
| `--limit` | 10 | 1–20. |
| `--offset` | 0 | Pagination offset. |
| `--user-id` | — | Scope every figure (summary, breakdown, list, total) to one end user. |
| `--conversation-id` | — | Scope every figure to one trace. |
| `--conversation-ids` | — | Scope every figure to several traces, comma-separated or a JSON array (up to 50). The server filters them in one request. Cannot be combined with `--conversation-id`. |
| `--ids-from` | — | The `--conversation-ids` values one per line, from a file or `-` (stdin). |
| `--include-window` | off | Attach a message window from the trace around each anchor. In agent output, rows leave out the embedded conversation window unless this is set; each row has `anchor` and `context_command` (`moda traces get <conversation_id> --msg-index=<msg_index> --window=2`) instead. |
| `--window` | 1 | Turns per side for `--include-window` (1–5). |
| `--compare` | off | Add `summary.compare`: the family's dashboard KPI tiles and rate for this window against the previous window of equal length. Also on `--family=emotion`, `laziness`, `hallucination`, `tool_failure` and `moda detections tools`. Covers the whole family, so not with `--user-id` or `--conversation-id`. |

### moda detections list, family emotion

Multi-family emotion detections: `frustration`, `sadness`, `confusion`, `anxiety`, `trust`, and `positive`. The summary always covers all families; `--family` filters the paginated detections list only.

```bash theme={"dark"}
moda detections list --family=emotion:confusion --days-back=7 --limit=1
```

```json Output (trimmed) theme={"dark"}
{
  "summary": {
    "conversations_analyzed": 11482,
    "by_family": { "frustration": 231, "sadness": 164, "confusion": 118, "anxiety": 51, "trust": 47, "positive": 1893 },
    "negative_rate_pct": 4.6,
    "positive_rate_pct": 17.3,
    "repair_rate_pct": 23.2
  },
  "signal_breakdown": [{ "family": "confusion", "signal": "repeated_clarification", "count": 61 }],
  "detections": [
    {
      "detection_id": "7404fcab-7141-4a04-9de9-e4b26659a755",
      "conversation_id": "conv_5e1a9c2b7d3f4680",
      "family": "confusion",
      "is_detected": true,
      "score": 0.84,
      "primary_cause": "Agent restated the plan three times without answering the pricing question.",
      "user_quotes": [{ "turn": 9, "quote": "I still don't understand what I'm being charged for.", "signal": "confusion" }],
      "key_turns": [9],
      "detected_at": "2026-08-15T11:02:44"
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "total": 118, "detected": 97, "at_risk": 21, "has_more": true }
}
```

`by_family` counts detected traces. The detections list also holds at-risk rows (`is_detected: false`, `risk_score` ≥ 0.5), so `pagination.total` is detected plus at-risk; `pagination.detected` and `pagination.at_risk` give the split.

| Flag | Default | Description |
| - | - | - |
| `--family` | — | `frustration`, `disapproval`, `sadness`, `confusion`, `anxiety`, `trust`, `positive`. Filters detections only. |
| `--user-id` | — | Scope every figure, summary included, to one end user. |
| `--conversation-id` | — | Scope every figure to one trace. |
| `--conversation-ids` | — | Scope every figure to several traces, comma-separated or a JSON array (up to 50). The server filters them in one request. Cannot be combined with `--conversation-id`. |
| `--ids-from` | — | The `--conversation-ids` values one per line, from a file or `-` (stdin). |
| `--days-back` | 7 | 1–90. Windows on analysis time, not `detected_at` (the anchor turn's timestamp, which can be much older on long-running traces). |
| `--limit` | 10 | 1–20. |
| `--offset` | 0 | 0–10,000. |
| `--include-window` | off | Keep each detection's `conversation_context` in agent output (it is left out by default; rows carry `context_command`). `--json` always keeps it. |

### moda detections list, family hallucination

Grounding detections: assistant claims that contradict or are verified against the trace's world state, with the rule that fired and the offending substring.

```bash theme={"dark"}
moda detections list --family=hallucination --kind=contradicted --limit=1
```

```json Output (trimmed) theme={"dark"}
{
  "summary": {
    "total_scored": 124,
    "contradicted_count": 29,
    "verified_count": 23,
    "ungrounded_count": 41,
    "ungrounded_rate": 0.331,
    "conversations_scored": 99,
    "rule_breakdown": [{ "source": "rule", "rule_id": "false_absence", "count": 17 }]
  },
  "detections": [
    {
      "conversation_id": "conv_5e1a9c2b7d3f4680",
      "message_index": 31,
      "kind": "contradicted",
      "label": "CONTRADICT",
      "confidence": 0.92,
      "rule_id": "false_absence",
      "violated_slot_key": "contact.email",
      "offending_substring": "I couldn't find a verified personal email for him.",
      "incident_id": null,
      "detected_at": "2026-08-15T09:41:07"
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "total": 29 }
}
```

Each hallucination names the Problems incident it comes from in `incident_id` (`null` for rows from before hallucinations came from validated incidents); `moda traces findings` shows it as `incident`.

| Flag | Default | Description |
| - | - | - |
| `--kind` | — | `contradicted` or `verified`. Filters the detections list. |
| `--conversation-id` | — | Scope to one trace (by trace ID). Note: this narrows the summary aggregates too, not just the list. |
| `--conversation-ids` | — | Scope every figure to several traces, comma-separated or a JSON array (up to 50). The server filters them in one request. Cannot be combined with `--conversation-id`. |
| `--ids-from` | — | The `--conversation-ids` values one per line, from a file or `-` (stdin). |
| `--days-back` | 7 | 1–90. |
| `--limit` | 10 | 1–20. |
| `--offset` | 0 | 0–10,000. |

The detections list contains only contradicted and verified rows; plain ungrounded rows appear in the summary counts but are not listed. `pagination` here has no `has_more` field — compute `offset + limit < total` client-side.

### moda detections list, per trace

By default emotion and frustration rows are one per trace and family (`"counting": "per_detection"`), and hallucination rows one per scored message (`"counting": "per_message"`), so `pagination.total` is not the dashboard's trace count. `--group-by=trace` reads the dashboard Signals tab's own list (the same loader): one row per trace in `traces`, the dashboard's filters and sort, and `"counting": "per_trace"`, so the total matches the dashboard for the same window and filters. Each filter below implies `--group-by=trace`. Laziness rows are always one per trace.

```bash theme={"dark"}
moda detections list --family=frustration --trajectory=building --sort=risk_score --limit=1
```

```json Output (trimmed) theme={"dark"}
{
  "counting": "per_trace",
  "counting_note": "pagination.total counts traces with a matching detected family ...",
  "filters": { "family": "frustration", "trajectory": "building", "sort": "risk_score" },
  "summary": { "conversations_analyzed": 2338, "negative_conversations": 212, "negative_rate_pct": 9.1 },
  "traces": [
    {
      "conversation_id": "conv_5e1a9c2b7d3f4680",
      "message_count": 21,
      "negative_detected": true,
      "families": [{ "family": "frustration", "score": 0.82, "trajectory": "building", "elicitor": "bot", "expressed_signals": ["exasperation"] }]
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "total": 37, "has_more": true },
  "processing": { "enabled": true, "setting": "signals.frustration" }
}
```

| Flag | Families | Description |
| - | - | - |
| `--group-by` | emotion, frustration, hallucination, laziness | `trace` reads per trace. The defaults are `detection` (emotion, frustration) and `message` (hallucination). |
| `--search` | all four | Substring of the trace ID (emotion and frustration also match the primary cause). |
| `--status` | all four | Emotion: `all` (any detected family, default) or `detected` (a negative family). Hallucination: `contradicted` (default) or `all`. Laziness: `all` (default) or `strong`. |
| `--elicitor` | emotion, frustration | `bot`, `external`, `self`, `ambiguous`. |
| `--trajectory` | emotion, frustration | `none`, `building`, `peak`, `resolved`, `sustained`. |
| `--signal` | emotion, frustration | Expressed signals, comma-separated (for example `sarcasm,anger`); a trace matches when any is expressed. |
| `--rule` | hallucination | One `rule_id` from `summary.rule_breakdown`; it scopes the summary too. |
| `--source` | hallucination | `rule`, `classifier`, `gpu`, `judge`, `human`. |
| `--sort` | all four | Emotion: `score` (default), `risk_score`, `detected_at`, `message_count`. Hallucination: `contradicted_count` (default), `verified_count`, `last_detected_at`. Laziness: `detections_count` (default), `strong_count`, `last_detected_at`. |
| `--order` | all four | `desc` (default) or `asc`. |
| `--cohort` | all four | `builtin:<key>` or a saved cohort id: only traces of the cohort's members, summary included. It implies `--group-by=trace` (laziness: list reads only, not with `--conversation-id`). The summary line names the cohort and the data carries `cohort`. |

The per-trace list has no user scope and no single-trace read, so `--user-id`, `--conversation-id` and `--include-window` (and `--kind` for hallucinations) are rejected with it. Its `summary` covers the whole window and ignores the list filters, except hallucination `--rule`.

### moda detections tools

Per-tool failure overview for the window.

```bash theme={"dark"}
moda detections tools --days-back=7
```

```json Output (trimmed) theme={"dark"}
{
  "summary": { "total": 41, "total_calls": 1876, "conversations": 33, "tools": 3, "failure_rate_pct": 2.2 },
  "tools": [
    {
      "tool_name": "lookupCustomer",
      "failure_count": 28,
      "total_count": 512,
      "failure_rate_pct": 5.5,
      "conversation_count": 22,
      "top_error": "TimeoutError: request to CRM timed out after 10000ms",
      "last_seen": "2026-08-15T22:41:09Z"
    }
  ]
}
```

| Flag | Default | Description |
| - | - | - |
| `--days-back` | 7 | 1–90. |
| `--cohort` | — | `builtin:<key>` or a saved cohort id: the dashboard Tool Failures leaderboard for the cohort's traces (`source: "dashboard_tool_failures"`). It counts failures only, so there are no `total_calls` or failure rates under a cohort. |

`moda detections list --family=custom_signal --signal-id=<signal_id>` also takes `--cohort`: only hits on traces of the cohort's members.

### moda detections tools, one tool

Failure subtypes and concrete examples for one tool. Each example carries a CLI-added `anchor` (trace ID + message index).

Example text (message bodies, tool results, error text) is returned whole. In `--agent` mode, if the envelope goes over its byte limit, whole trailing examples are dropped and `truncation.data.full_output_path` points at a file with every example. Each example's `context_command` (`moda traces get <conversation_id> --msg-index=<msg_index>`) opens the surrounding trace.

```bash theme={"dark"}
moda detections tools lookupCustomer --limit=1
```

```json Output (trimmed) theme={"dark"}
{
  "tool_name": "lookupCustomer",
  "subtypes": [
    { "subtype": "timeout.expired", "count": 21, "conversation_count": 17, "sample_error": "TimeoutError: request to CRM timed out after 10000ms", "last_seen": "2026-08-15T22:41:09Z" }
  ],
  "examples": [
    {
      "conversation_id": "conv_5e1a9c2b7d3f4680",
      "error_message": "TimeoutError: request to CRM timed out after 10000ms",
      "error_subtype": "timeout.expired",
      "msg_index": 9,
      "detected_at": "2026-08-15T22:41:09Z",
      "anchor": { "kind": "tool_failure", "conversation_id": "conv_5e1a9c2b7d3f4680", "msg_index": 9, "tool_name": "lookupCustomer", "error_subtype": "timeout.expired", "no_anchor": false }
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "total": 28, "has_more": true }
}
```

| Argument / flag | Default | Description |
| - | - | - |
| `<tool_name>` | required | Tool to inspect. |
| `--subtype` | — | Filter examples to one failure subtype, a value from the response's `subtypes` (e.g. `dependency.timeout`). An unknown subtype returns a warning listing valid ones. |
| `--days-back` | 7 | 1–90. |
| `--limit` | 5 | Examples per page, 1–20. |
| `--offset` | 0 | Pagination offset. |
| `--include-window` / `--window` | off / 1 | Attach message windows from the trace around each anchor. |

Both forms suggest `moda tools get <tool_name>` in `next_commands`: the tool's call count, success rate and schema.

### moda tools list

Every tool called in the window, failing or not: the dashboard Tool catalog. `calls`, `failed_calls` and `success_rate_pct` count recorded tool receipts; `moda detections tools` counts classified failures, so the two can differ (`metric_note` says so in every response).

```bash theme={"dark"}
moda tools list --sort=failure_rate --limit=2
```

```json Output (trimmed) theme={"dark"}
{
  "window": { "days_back": 7 },
  "filters": { "sort": "failure_rate" },
  "summary": { "total_calls": 1876, "unique_tools": 14, "total_conversations": 402 },
  "tools": [
    { "tool_name": "lookupCustomer", "calls": 512, "failed_calls": 28, "success_rate_pct": 94.53, "failure_rate_pct": 5.47, "conversation_count": 210, "effect_direction": "read", "target_system": "crm", "last_seen": "2026-08-15T22:41:09" },
    { "tool_name": "createTicket", "calls": 96, "failed_calls": 3, "success_rate_pct": 96.88, "failure_rate_pct": 3.13, "conversation_count": 80, "effect_direction": "write", "target_system": "zendesk", "last_seen": "2026-08-15T21:02:44" }
  ],
  "pagination": { "limit": 2, "offset": 0, "total": 14, "returned": 2, "has_more": true, "next_offset": 2 }
}
```

When `has_more` is true, `next_commands` holds the next page (`moda tools list --sort=failure_rate --limit=2 --offset=2`).

| Flag | Default | Description |
| - | - | - |
| `--days-back` | 7 | 1–90. |
| `--sort` | `calls` | `calls`, `failure_rate`, `failures` (failed calls), `traces`, `last_seen`; all descending, ties by tool name. |
| `--search` | — | Only tools whose name contains this text. |
| `--direction` | — | Only tools with this effect direction: `read`, `write`, `send`, `spawn`, `compute`, `unknown`. |
| `--limit` | 25 | Tools per page, 1–200. |
| `--offset` | 0 | Pagination offset, 0–10,000. |

### moda tools get

One tool: call stats, its registered definition (description and schema, or `null`) and the payload fields seen in recorded calls, usage per day (per hour under 7 days), its top failure categories with the newest failure of each, and recent calls. A tool with no calls in the window is `not_found`.

```bash theme={"dark"}
moda tools get lookupCustomer
```

```json Output (trimmed) theme={"dark"}
{
  "tool_name": "lookupCustomer",
  "window": { "days_back": 7, "bucket": "day" },
  "stats": { "calls": 512, "failed_calls": 28, "success_rate_pct": 94.53, "failure_detections": 31, "conversation_count": 210, "user_count": 188, "first_seen": "2026-08-09T00:12:40", "last_seen": "2026-08-15T22:41:09" },
  "definition": {
    "registered": { "description": "Look up a customer by email or id", "schema": { "type": "object", "properties": { "email": { "type": "string" } } }, "source": "MANUAL", "is_active": true, "updated_at": "2026-08-01T10:00:00.000Z" },
    "payloads_sampled": 512,
    "invalid_payloads": 0,
    "observed_fields": [{ "name": "email", "inferred_type": "string", "call_count": 498, "call_pct": 97.3, "common_values": [{ "value": "a@example.com", "count": 4, "pct": 0.8 }], "common_values_total": 10 }]
  },
  "usage": [{ "timestamp": "2026-08-15 00:00:00", "calls": 80, "failed_calls": 6 }],
  "failure_categories": {
    "total_failures": 31,
    "categories_total": 2,
    "categories": [
      {
        "category": "timeout.expired",
        "label": "Request timed out",
        "count": 21,
        "conversation_count": 17,
        "latest_failure": { "conversation_id": "conv_5e1a9c2b7d3f4680", "msg_index": 9, "tool_use_id": "toolu_01", "detected_at": "2026-08-15T22:41:09" },
        "context_command": "moda traces get conv_5e1a9c2b7d3f4680 --msg-index=9 --window=2",
        "examples_command": "moda detections tools lookupCustomer --subtype=timeout.expired --days-back=7"
      }
    ]
  }
}
```

`next_commands` start with `moda detections tools <tool_name>` (the failure rows). Agent output keeps 20 observed fields with three common values each and 5 recent calls, and cuts inputs and sample errors at 200 characters (`*_total` fields give the full counts); `--full` keeps everything. The registered schema is never cut.

| Argument / flag | Default | Description |
| - | - | - |
| `<tool_name>` | required | Tool to read (from `moda tools list`). |
| `--days-back` | 7 | 1–90. |
| `--full` | off | Keep observed values, tool class inputs and recent call inputs whole. |

### moda problems list

The Problems the dashboard shows, ranked. By default (`--view=auto`) the CLI asks the same question the dashboard's Problems page asks: when the tenant has a dream grouping published, the list is that grouping (each problem with its definition, fix, incidents, users and severity, in the dashboard table's order); otherwise it is the Book's ranked list (`problems` and `untrusted`). `view` in the output says which one you got. `--view=book` or `--view=dream` picks one. Both read the dashboard's own loaders, so counts, ranking and the date range match the dashboard. The CLI appends `dashboard_url`.

```bash theme={"dark"}
moda problems list
moda problems list --sort=users --limit=20
moda problems list --view=book --days-back=7
moda problems list --view=book --offset=10 --list-version=3f476d219fc9f4ec
```

```json Output (Book, trimmed) theme={"dark"}
{
  "view": "book",
  "summary": { "days_back": 30, "window_hours": 72, "open_problems": 4, "reopened": 1, "total_problems": 11, "signals_attributed": 132, "explained_coverage_pct": 78.6 },
  "problems": [
    {
      "problem_id": "3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b",
      "display_name": "CRM lookups time out during peak hours",
      "cause_statement": "lookupCustomer calls exceed the 10s timeout under load, so refund flows stall.",
      "lifecycle": "open",
      "rank_score": 42.5,
      "pressing_rank": 1,
      "rank_basis": "v4_impact",
      "affected_users": 19,
      "affected_conversations": 44
    }
  ],
  "untrusted": [],
  "pagination": { "offset": 0, "limit": 10, "returned": 1, "untrusted_returned": 0, "has_more": true, "next_offset": 10, "list_version": "3f476d219fc9f4ec" },
  "dashboard_url": "https://moda.dev/dashboard/problems"
}
```

```json Output (dream view, trimmed) theme={"dark"}
{
  "available": true,
  "view": "dream",
  "run": { "run_id": "7c1e...", "window_hours": 2160, "incidents": 4574, "users": 1716 },
  "summary": { "problems": 447, "incidents": 4574, "pinned_problem_ids": [] },
  "problems": [
    {
      "problem_id": "baa8f1bb-56f6-5bb9-a16c-cca9ca957c2d",
      "name": "Posts scheduled or published without explicit confirmation",
      "category": { "family_id": "agent_prompt", "name": "Agent prompt, skills and briefs" },
      "incidents": 44,
      "users": 38,
      "silent_share_pct": 62,
      "severity": { "tier": "P0", "rank": 310.7, "alert": true, "worst": "Unapproved post auto-published publicly." }
    }
  ],
  "worst_incidents": [],
  "pagination": { "offset": 0, "limit": 10, "returned": 10, "total": 447, "has_more": true, "next_offset": 10, "list_version": "5031dd43ed702b8a" }
}
```

| Flag | Default | Description |
| - | - | - |
| `--view` | `auto` | `auto` (what the dashboard shows), `book` or `dream`. |
| `--days-back` | Book 30; dream view: its run window | 1–90. On a dream-grouped tenant the Book's counts are recounted for the range; `summary.window_hours` is the rollup's own window. |
| `--limit` | 10 | 1–200 per page (per partition on the Book). The default keeps one page inside the agent byte budget. |
| `--offset` | 0 | Row to start at: `pagination.next_offset` of the previous page. |
| `--list-version` | — | `list_version` of the first page, passed with every later `--offset`. If a later page reports another version, the list changed: restart from the first page. |
| `--sort` | `rank` | `rank` or `users`; dream view: `severity` (its rank), `silent`; Book: `signals`, `problems`, `signal:<family>`. |
| `--dir` | `desc` | `desc` or `asc`. |
| `--cohort` | — | `builtin:<key>` or a saved cohort id: only the Problems the cohort's users hit, with its counts. |

`next_commands` carries the command for the next page. Dream problem ids are Book problem ids, so `moda problems get <id>` and its `--evidence`/`--traces` pages work for ids from either view.

### moda problems get

Open one Problem: the dossier, or a paged sub-resource view. In agent output the dossier is compact by default (`view: "compact"`): the header, the dossier summary, verification counts, the top 5 evidence rows with `conversation_id`, `msg_index` and a `context_command`, one line per investigation report, counts of what was left out under `omitted`, and next commands for `--evidence`, `--reports`, `--traces` and `--full`. `--full` (and `--json`) return the whole dossier, which includes the rubric, rank trend, sub-problems, verification results, evidence, affected traces, investigation reports, hierarchy, and representative stories.

```bash theme={"dark"}
moda problems get 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b
moda problems get 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --evidence --limit=10
moda problems get 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --reports
moda problems get 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --traces --family=tool_failure
moda problems get 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --feedback
moda problems get 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --view=dream --limit=3 --offset=3
moda problems get 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --trend --days-back=14
```

```json Output (dossier, trimmed) theme={"dark"}
{
  "found": true,
  "problem_id": "3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b",
  "alias_resolved": false,
  "header": { "display_name": "CRM lookups time out during peak hours", "lifecycle": "open", "rank_score": 42.5 },
  "trend": [{ "run_ts": "2026-08-15T00:00:00", "rank_score": 42.5, "total_attributions": 132 }],
  "verification": { "audit_pass_rate": 0.86, "judge_audit": { "passed": 12, "total": 14 } },
  "evidence": [{ "attribution_id": "a4b73e58-48de-4fb2-9c58-1c3d5e7f9a0b", "conversation_id": "conv_5e1a9c2b7d3f4680", "causal_rationale": "Timeout fired before the CRM responded.", "door": "rubric_match" }],
  "investigation_reports": { "items": [], "has_more": false, "next_cursor": null },
  "stories": []
}
```

| Argument / flag | Default | Description |
| - | - | - |
| `<problem_id>` | required | Problem ID (UUIDs from `moda problems`; merged-away IDs resolve to the surviving problem with `alias_resolved: true`). |
| `--full` | off | The whole dossier in agent output (the default there is the compact view). Dossier only; not combinable with the view flags. |
| `--evidence` | off | Paged attribution evidence (rationales, anchors, replay verification). |
| `--reports` | off | Paged investigation reports (mechanism, narrative, citations). |
| `--traces` | off | Paged affected traces with deep-link anchors. Legacy alias: `--conversations`. |
| `--feedback` | off | The problem's feedback queue and pending count. |
| `--limit` | 25 (evidence/traces), 20 (reports) | 1–50. |
| `--cursor` | — | Keyset cursor from the previous page's `next_cursor`. Opaque — pass it back verbatim. |
| `--family` | — | `--traces` filter: `tool_failure`, `emotion`, `laziness`, `hallucination`, `custom_signal`, `conversation_reader`. |
| `--door` | — | `--traces` filter: `rubric_match`, `local_causal_chain`. |
| `--trend` | off | Incidents and users per UTC day as `[date, value]` arrays, and incidents and signals for the last `--days-back` days (default 30) against the same number of days before (`compare`; `null` above 45 days because the history keeps 90). Reads `GET /v1/data/problems/:id/history`, the dashboard's problem history loader. Only `--days-back` combines with it. |
| `--view` | — | `dream`: the problem as the dashboard's dream page shows it (definition, fix, severity, and its incidents with the validator's verdicts, most serious first). Pages incidents with `--limit` (default 3) and `--offset`; `--days-back` sets the range (default the dream run's window). A problem outside the dream view is a not-found error that names the dossier command. |

At most one view flag per invocation. The dossier endpoint never returns 404 — an unknown or retired ID comes back `found: false` and the CLI adds a not-found warning. Sub-resource views require a canonical UUID (the CLI rejects other ids before the network). Cursors are not portable across different `--family`/`--door` filters.

### moda problems feedback

Close the loop on a Problem from the terminal: mark it fixed, dismiss it, rename it, or flag a bad attribution. Writes to the same reconcile queue as the dashboard.

```bash theme={"dark"}
moda problems feedback 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --action=mark_fixed
moda problems feedback 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --action=dismiss --reason="not actionable"
moda problems feedback 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --action=rename --new-name="CRM lookup timeouts"
```

```json Output theme={"dark"}
{ "success": true, "feedback_id": "5b0c2f1e-8d43-4a6a-9c1d-7e2f3a4b5c6d", "problem_id": "3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b", "action": "mark_fixed", "status": "pending", "duplicate": false }
```

| Argument / flag | Default | Description |
| - | - | - |
| `<problem_id>` | required | Canonical problem UUID. |
| `--action` | required | `mark_fixed`, `dismiss`, `flag_attribution`, `rename`. |
| `--reason` | — | Required for `dismiss` and `flag_attribution` (≤ 2,000 characters). |
| `--attribution-id` | — | Required UUID for `flag_attribution`; find IDs with `moda problems get <id> --evidence`. |
| `--new-name` | — | Required for `rename` (≤ 255 characters). |
| `--actor` | `moda-cli` | Recorded actor label. |

The write is idempotent while the previous identical submission is still pending (`duplicate: true`, no new row). The CLI enforces the conditional requirements locally, so a bad invocation fails before the network.

### moda problems linear

Show the Linear issue linked to a Problem. Requires the Linear integration to be connected (Integrations → Linear). In human mode the CLI also prints a one-line summary on stderr (`ENG-7 · In Progress · https://linear.app/...`), or a hint to run `moda problems link` when nothing is linked.

```bash theme={"dark"}
moda problems linear 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b
```

```json Output theme={"dark"}
{
  "problem_id": "3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b",
  "link": {
    "subjectKind": "problem",
    "subjectId": "3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b",
    "origin": "mcp",
    "issue": { "id": "9d1c2b3a-4e5f-4a6b-8c7d-0e1f2a3b4c5d", "identifier": "ENG-7", "url": "https://linear.app/acme/issue/ENG-7/crm-lookups-time-out", "teamId": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "stateName": "In Progress", "stateType": "started" },
    "createdAt": "2026-08-16T09:14:02.000Z",
    "lastSyncedAt": "2026-08-16T10:02:11.000Z"
  }
}
```

| Argument / flag | Default | Description |
| - | - | - |
| `<problem_id>` | required | Canonical problem UUID. |

`link` is `null` when no issue is linked.

### moda problems link

File a Problem as a Linear issue in your team's tracker, or link an existing issue with `--issue`. Requires the Linear integration to be connected (Integrations → Linear).

```bash theme={"dark"}
moda problems link 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --priority=2
moda problems link 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --issue=ENG-123
```

```json Output theme={"dark"}
{ "problem_id": "3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b", "created": true, "link": { "subjectKind": "problem", "origin": "mcp", "issue": { "identifier": "ENG-7", "url": "https://linear.app/acme/issue/ENG-7/crm-lookups-time-out", "stateName": "Todo", "stateType": "unstarted" } } }
```

| Argument / flag | Default | Description |
| - | - | - |
| `<problem_id>` | required | Canonical problem UUID. |
| `--issue` | — | Link this existing issue (`ENG-123` or its `linear.app` URL) instead of filing a new one. Cannot be combined with `--team-id`, `--title`, or `--priority`. |
| `--team-id` | integration default | Linear team to file into. Without it, the integration's default team is used; if none is set the command fails with a `--team-id` hint. |
| `--title` | the Problem's name | Issue title (trimmed, truncated to 255 characters). |
| `--priority` | — | 0–4: 0 none, 1 urgent, 2 high, 3 medium, 4 low. |

Filing is idempotent per Problem: an already-linked Problem returns its existing link with `created: false`. Linking fails if the Problem is already linked to a different issue.

### moda feedback

Flag wrong or missing data (or CLI quirks) to the Moda team. The note is required; IDs attach context.

```bash theme={"dark"}
moda feedback "cluster label looks wrong" --category=bad_cluster_label --cluster-id=node_44
```

```json Output theme={"dark"}
{ "submitted": true, "category": "bad_cluster_label", "severity": "low", "feedback_id": "5b0c2f1e-8d43-4a6a-9c1d-7e2f3a4b5c6d", "submitted_at": "2026-08-16T09:14:02Z" }
```

| Argument / flag | Default | Description |
| - | - | - |
| `"<note>"` | required | Up to 4,000 characters. |
| `--note` | — | The note, if not given as the argument. |
| `--category` | `other` | `bad_cluster_label`, `mismatched_frustration`, `missing_data`, `noisy_data`, `wrong_tool_failure`, `incorrect_loop`, `api_quirk`, `false_positive_attribution`, `misrouted_fix`, `harness_bug`, `other`. An unknown value is sent as `other` with `refs.raw_category`, and a warning lists the valid ones. |
| `--severity` | `low` | `info`, `low`, `medium`, `high`. |
| `--conversation-id`, `--cluster-id`, `--tool-name`, `--run-id` | — | Attach references (`--conversation-id` takes a trace ID). |
| `--<name>-id` | — | Any other id (`--problem-id`, `--fix-id`, `--attribution-id`, `--trace-id`, `--span-id`, `--message-index`) is attached to `refs`. |

### moda tail

Live-tail production activity: poll the Data API and emit one JSON line per newly seen item (NDJSON on stdout in every output mode — a tail is a stream, so the single-envelope agent contract does not apply). `Ctrl-C` stops it.

```bash theme={"dark"}
moda tail                                # new traces, every 15s
moda tail --signal=all --interval=30     # traces + emotion detections
moda tail --once --max-events=10         # one poll (baseline page), bounded
```

```json Output (one line per item) theme={"dark"}
{"type":"conversation","conversation_id":"conv_5e1a9c2b7d3f4680","timestamp":"2026-08-16T08:19:11","message_count":21,"environment":"production","cluster_name":"Refund retries","summary":"User retries a failed refund"}
{"type":"emotion","detection_id":"7404fcab-7141-4a04-9de9-e4b26659a755","conversation_id":"conv_5e1a9c2b7d3f4680","family":"frustration","primary_cause":"Refund tool errored twice.","detected_at":"2026-08-15T11:02:44"}
{"type":"tail_coverage","signal":"emotions","complete":false,"scanned":500,"total":3823,"coverage_pct":13.1,"pages_scanned":25,"detail":"..."}
```

| Flag | Default | Description |
| - | - | - |
| `--signal` | `traces` | `traces`, `emotions`, `all`. Legacy alias: `--signal=conversations` (same as `traces`). |
| `--interval` | 15 | Seconds between polls (5–3,600). |
| `--once` | off | One poll, then exit. |
| `--limit` | 20 | Traces page size per poll (1–50). |
| `--max-events` | — | Stop after N emitted stdout records, metadata included (enforced per record, so a large page never overshoots). |
| `--full-scan` | off | Emotions: scan the whole one-day window instead of the top-scoring prefix (many more requests, bounded by the API's offset ceiling of 10,000). |

Dedupe is in-memory per process: traces re-emit when they advance (`message_count` changes — long-running, single-trace-per-user tenants update in place); emotion detections emit once per `detection_id`. Trace records keep `"type":"conversation"` on the wire.

**Emotions coverage.** The emotions endpoint is ranked by score with no time ordering or cursor, so a tail cannot ask for "detections since X" — by default it follows the highest-scoring detections and emits a `tail_coverage` record per poll stating exactly what it scanned (`scanned`, `total`, `coverage_pct`, `complete`). On high-volume tenants the default poll covers a fraction of the day; use `--full-scan` when completeness matters more than request count. `--max-events` bounds every record on stdout, metadata included. When it is set, one slot is reserved for the coverage record so a capped tail still reports what it saw; at `--max-events=1` the data row keeps the slot and the coverage record is written to stderr instead, where it cannot affect a consumer's record count.

### moda cohorts

User cohorts, as the dashboard Users page defines them: six built-ins (`builtin:power_users`, `builtin:heavy_tool_users`, `builtin:frustrated`, `builtin:at_risk`, `builtin:new_this_week`, `builtin:silent_sufferers`) and the tenant's saved cohorts (a UUID). Each one's `ref` scopes a list with `--cohort=<ref>`: `problems list`, `traces list`, `detections list`, `detections tools` and `clusters`. A scoped list refreshes the cohort's membership snapshot first, as the dashboard does, and its summary names the cohort.

```bash theme={"dark"}
moda cohorts list
moda cohorts compare builtin:new_this_week builtin:power_users --days=30
moda problems list --sort=users --cohort=builtin:new_this_week
```

| Command | Description |
| - | - |
| `moda cohorts list [--include-archived]` | Built-ins first, then saved cohorts: `ref`, `name`, `definition`, `revision`. |
| `moda cohorts get <ref>` | One cohort. |
| `moda cohorts fields` | The fields and operators a definition can use. |
| `moda cohorts preview --file=<path>` | Member count and a sample of user ids for an unsaved definition (`--definition=<json>` inline). Writes nothing. |
| `moda cohorts compare <a> <b> [--days=7\|30\|90]` | Two cohorts side by side: size, health bands, tokens, top topic categories and failure mix. |
| `moda cohorts create --name=NAME --file=<path>` | Write. Saves a cohort (`--description`, `--pinned`, `--color=neutral\|blue\|green\|amber\|red\|violet`). Takes `--dry-run`. |
| `moda cohorts update <cohort_id>` | Write. Edits a saved cohort (same flags, plus `--note`). Built-in cohorts cannot be edited. Takes `--dry-run`. |

A definition is `{"version":1,"window":"24h|7d|30d|90d","where":{...}}`, for example `{"version":1,"window":"30d","where":{"field":"tool_failure_count","op":"gte","value":3}}`. A `--file` may hold the definition alone or a body with a `definition` key.

## Production intelligence

### moda investigate

Aggregates overview, tool failures, frustrations and the top 3 Problems into ranked findings with evidence references and next commands. `--tool=NAME` scopes to one tool; `--trace=ID` (legacy alias `--conversation=ID`) scopes only the frustration evidence to one trace.

The Problems are the first rows of the list `moda problems list` shows (its default `--view=auto`): the dream grouping when the tenant's dashboard shows one, in the dashboard table's order, otherwise the Book's ranked list. `data.problemsView` says which list was used (`view`: `dream` or `book`), the window its counts cover, and the `moda problems list` command that lists the same Problems in the same order. Without `--days-back`, dream counts cover the dream run's window, the dashboard's default range; the Book uses the investigation window. Problem ids from either view work with `moda problems get <id>`.

If every source fails, the command fails with that error (a rejected key is `auth_required`, exit 4). If some fail, the result is `degraded` (exit 3), `data.failedSources` names them, and the summary starts with `Incomplete:`; it never reports "no strong production issue" from reads that failed.

```bash theme={"dark"}
moda investigate --days-back=7 --tool=lookupCustomer
```

```json Output (trimmed) theme={"dark"}
{
  "schemaVersion": "production_investigation.v0.1",
  "daysBack": 7,
  "summary": { "text": "Top production finding: lookupCustomer is failing in production. lookupCustomer produced 28 failed call(s) in the last 7 day(s).", "confidence": "high" },
  "findings": [
    { "id": "finding_tool_failure_lookupCustomer", "kind": "tool_failure", "title": "lookupCustomer is failing in production", "severity": "critical", "confidence": "high", "impactScore": 115 }
  ],
  "nextCommands": ["moda detections tools lookupCustomer --days-back=7 --include-window", "moda problems list --view=dream --days-back=7"],
  "sourceStatus": { "overview": "ok", "tools": "ok", "frustrations": "ok", "problems": "ok" },
  "problemsView": { "view": "dream", "window": "the last 7 day(s)", "command": "moda problems list --view=dream --days-back=7" }
}
```

### moda failures

Same investigation, restricted to failure findings (frustration findings excluded). Flags: `--days-back`, `--tool`.

```bash theme={"dark"}
moda failures --tool=lookupCustomer
```

### moda ask

Ask Moda a production question in natural language. On a TTY the answer streams live; add `--no-stream` for a buffered request. If the stream can't start, the CLI switches to the buffered request. If it drops after the run started, the CLI fails instead of asking again (a second run would cost a second analysis). The first run may still finish; retry with `--no-stream`. The cloud request times out after `MODA_ASK_TIMEOUT_MS` (default 250 s); if Moda Cloud is unavailable the CLI synthesizes an answer from local Data API evidence and **exits 3** with `source: "local_fallback"` and `degraded: true`.

```bash theme={"dark"}
moda ask "what should I fix first?" --json
```

```json Output (trimmed) theme={"dark"}
{
  "schema_version": "moda.intelligence.v1",
  "source": "cloud",
  "degraded": false,
  "summary": { "text": "Fix lookupCustomer timeouts first.", "confidence": "high" },
  "answer_markdown": "The strongest production signal this week is lookupCustomer timing out in 5.5% of calls, affecting 22 traces...",
  "answer_claims": []
}
```

| Argument / flag | Default | Description |
| - | - | - |
| `"<question>"` | required | The question. |
| `--days-back` | 7 | Evidence window (1–90). |
| `--no-stream` | off | Disable live streaming on a TTY. |

## Agent-native commands

`moda agent context`, `moda agent next-action`, and `moda agent evidence <ref>` emit local Moda context and readiness diagnostics, prioritized next commands, and expanded evidence for coding agents. For the ranked production investigation use `moda investigate`. They default to agent JSON output in every environment. See [Using the CLI from agents and CI](https://docs.moda.dev/cli/agents.md).

```bash theme={"dark"}
moda agent next-action
```

## Managing Moda from the CLI

These commands do what the dashboard does. Each needs only an API key, and the tenant comes from the key. Writes take `--dry-run`: it validates the call, returns the exact request in `data.planned` (method, endpoint, body) and sends nothing, and its `next_commands` entry is the command that sends it (`requires_approval: true`). That includes `problems feedback`, `problems reopen`, `problems link`, `review`, `feedback`, `cohorts create|update` and the `signals` writes; `prompts promote` refuses `--dry-run` before any request.

| Task | Command |
| - | - |
| Sort or page traces | `moda traces --sort=recent\|longest\|slowest --offset=N` |
| Read a whole trace in order | `moda traces get <conversation_id> --all` |
| End users and one user's profile | `moda users [--window=30d --cohort=frustrated --sort=health_score --order=asc]`, `moda user <user_id>` (`--cohort` takes `builtin:<key>`, a saved cohort id or a built-in key) |
| User cohorts | `moda cohorts list [--include-archived]`, `get <ref>`, `fields`, `preview --file=<definition.json>`, `compare <a> <b> [--days=7\|30\|90]` |
| Save or edit a cohort | `moda cohorts create --name=NAME --file=<definition.json> [--description --pinned --color] [--dry-run]`, `moda cohorts update <cohort_id> [--name --file --note …] [--dry-run]` (archiving is dashboard-only) |
| Reopen a problem marked fixed | `moda problems reopen <problem_id> [--reason=TEXT]` (resolved problems return only via re-detection) |
| Draft and create a custom signal | `moda signals draft --note="…"`, `moda signals create --name --description --pass-criteria --fail-criteria [--polarity --locus --tool-names=a,b --file=body.json]` |
| Edit a custom signal and change its status | `moda signals update <id> …`, `moda signals activate\|pause\|delete <id>` (delete: drafts only) |
| Review and tune a custom signal | `moda signals examples <id> add\|update\|remove --conversation-id=…`, `refine`, `revise`, `proposals`, `accept`, `reject` |
| Find matches for a custom signal | `moda signals search <id>`, `search-status`, `search-stop`, `preview --file=detector.json` |
| Prompt registry | `moda prompts list\|show\|proposals\|usage\|decide` |
| Skills | `moda skills list\|show <key>` |
| Synced harnesses | `moda harness list\|show\|versions\|diff` |

API keys can't do these on purpose: manage members, invites and roles; mint API keys; manage billing, provider credentials or OAuth connections; create alert rules that message people; or archive an active custom signal. LLM-backed signal actions (draft, refine, revise, search, adding or updating a labeled example, and similar) are limited to 10 per minute per key.

## Next steps

* [Using the CLI from agents and CI](https://docs.moda.dev/cli/agents.md) — envelope schema, exit-code recipes, CI examples.
* [Data API overview](https://docs.moda.dev/data-api/overview.md) — the same data over HTTP.

## Problem impact by use case

The `affected-use-cases` mode returns affected-trace counts by use case for a problem.
The `trace-use-cases` mode resolves current use-case links for up to 25 trace IDs
from problem-attributed segments across their history; it does not apply the
`--days-back` window. Both derive results at read time.

`moda problems impact` uses the same live, segment-scoped calculation as the
dashboard. It returns counts, full analyzed-population denominators, the resolved
classification run, time boundaries, and a dashboard link. It stores no counters.

```bash theme={"dark"}
moda problems impact --mode=catalog
moda problems impact --node-id=node_0 --days-back=7
moda problems impact --node-id=node_0 --days-back=all
moda problems impact --problem-id=<uuid> --days-back=30
moda problems impact --node-id=node_0 --problem-id=<uuid> --mode=evidence
moda problems impact --node-id=node_0 --mode=trend --days-back=30
moda problems impact --mode=overview --days-back=7
moda problems impact --problem-id=<uuid> --mode=affected-use-cases
moda problems impact --problem-id=<uuid> --mode=trace-use-cases --conversation-ids='["trace_id"]'
```

`--days-back` accepts 1, 3, 7, 30, 90, or `all`. To continue evidence, pass the returned
`nextCursor` as `--cursor`, `runId` as `--run-id`, and `window.to` as `--to`, retaining
the same node, problem, and days. A classification change fails explicitly; fetch
a fresh catalog instead of interpreting an old node ID in a new run. Use
`--json` for plain JSON or `--agent` for the standard agent envelope.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.