CLI reference

Complete reference for the moda CLI. Install and authentication are covered in the CLI overview; 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://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.
Requests time out after 30 seconds per attempt and retry up to 3 times on 429/5xx and network errors (exceptions: ask uses a 250-second timeout and retries at most once, on network errors only; feedback never retries).

Setup and diagnostics

moda init

Interactive project setup: browser login, tenant selection, API key provisioning, agent-rules/skill install, prompt manifest creation with a best-effort first sync, and (by default) a server-side harness analysis. Non-interactive with --yes.

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).
`--remote` / `--local`	Run harness analysis server-side (default) or with a local coding agent.
`--analyst=auto\|claude\|codex\|cursor\|local-scan`	Analyst adapter for harness analysis.
`--sdk-integrate` / `--no-sdk-integrate`	Run your coding agent to install and wire the Moda SDK, or skip it.
`--ci-cd` / `--no-ci-cd`	Create a GitHub Actions Moda validation workflow, or skip it.
`--autosync` / `--no-autosync`	Create `.github/workflows/moda-autosync.yml` (syncs prompts and skills on push to `main`), or skip it.
`--harness-rescan` / `--no-harness-rescan`	Create `.github/workflows/moda-harness-rescan.yml` (see CI rescan), or skip it.
`--harness-rescan-paths=GLOBS`	Comma-separated path globs that scope the rescan workflow’s triggers (implies `--harness-rescan`).
`--tui` / `--no-tui`	Force or suppress the full-screen analyst dashboard on a TTY.
`--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.

moda provision --tenant-id=1f7c9a2e-4b3d-4c8e-9a1b-2d3e4f5a6b7c --label=ci-runner

moda status

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

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.

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.

moda manifest --json

Output (trimmed)

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

moda profiles use staging
moda config show

moda keys

moda keys list and moda keys create --name=<label> manage local key descriptors (metadata about which key belongs to which profile). moda keys rotate and moda keys revoke are not supported yet and exit with an error; revoke keys in the dashboard at Settings → Ingestion keys.

moda keys list

Sessions

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

moda auth login

Output

{ "status": "authenticated", "profile": null }

moda auth status

Reports session state without ever opening a browser. Exit code 0 = valid session, 4 = logged out. --online adds a 5-second API reachability probe.

moda auth status --online --json

Output

{
  "loggedIn": true,
  "profile": null,
  "expiresAt": "2026-09-15T09:14:02.000Z",
  "user": { "email": "dev@example.com" },
  "online": { "reachable": true, "ok": true, "tenantCount": 1 }
}

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.

moda auth token

moda auth whoami

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

moda auth whoami

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.

moda auth logout

Output

{ "status": "logged_out", "profile": null, "api_key_cleared": true }

Production data

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.

moda overview --days-back=30 --raw --json

Output (trimmed)

{
  "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": []
}

Flag	Default	Description
`--days-back`	7	Look-back window (1–90).
`--raw`	off	Return the raw `/overview` payload instead of the briefing.

moda clusters

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

moda clusters --parent-id=node_12

Output (trimmed)

{
  "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`.

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

moda clusters --search="calendar scheduling conflicts" --limit=3

Output (trimmed)

{
  "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-conversations

List conversations in one cluster node.

moda cluster-conversations node_44 --limit=2

Output (trimmed)

{
  "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 conversations

Search and filter conversations by summary text, cluster, user, environment, world state, and outcome.

moda conversations --world-state="refund,enterprise" --outcome=negative --limit=2

Output (trimmed)

{
  "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`	—	Text match on conversation summaries and message bodies.
`--cluster-id`	—	Filter by cluster node ID.
`--user-id`	—	Filter to one user.
`--time-range`	`all`	`all`, `1h`, `24h`, `3d`, `7d`, `30d`, `90d`.
`--environment`	`all`	`all`, `development`, `staging`, `production`.
`--world-state`	—	Keyword match (case-insensitive substring) over world-state slots and the durable user profile; comma-separated terms are ANDed. Max 200 characters.
`--outcome`	`any`	`positive` (high blended segment score, not frustrated) or `negative` (low blended score or frustrated).
`--include-world-state`	off	Attach each result’s world-state summary (one extra request per row).
`--limit` / `--offset`	20 / 0	Pagination (limit 1–100, offset ≤ 10,000).

moda search

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

moda search "refund failed" --mode=hybrid --time-range=7d --limit=1

Output

{
  "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`.
`--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 context.

moda context

Windowed context around one message in a conversation.

moda context conv_5e1a9c2b7d3f4680 --msg-index=12 --window=1

Output (trimmed)

{
  "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	Conversation to read.
`--msg-index`	middle of the conversation	Center message index.
`--window`	2	Turns of context per side (1–5).

moda world-state

A conversation’s world state: durable user profile, per-segment slots, open threads, and the event stream.

moda world-state conv_5e1a9c2b7d3f4680 --summary-only

Output (trimmed)

{
  "hasData": true,
  "userId": "user_1842",
  "userDurableProfile": { "slots": { "plan": "enterprise" }, "updatedAt": "2026-08-14T18:30:02Z", "slotCount": 6 },
  "segments": [
    {
      "segmentIndex": 0,
      "startMsgIdx": 0,
      "endMsgIdx": 14,
      "slots": { "refund_status": "failed" },
      "openThreads": ["refund retry"],
      "slotCounts": { "durable": 2, "segmentLocal": 3, "total": 5 }
    }
  ],
  "summary": { "eventCount": 42, "segmentCount": 2, "lastUpdatedAt": "2026-08-14T18:30:02Z" }
}

Argument / flag	Default	Description
`<conversation_id>`	required	Conversation to read.
`--summary-only`	off	Omit the per-message event stream.
`--event-limit`	2000	Max events to return (1–5,000).

Point-in-time snapshot — the folded slot state at an exact (msg_index, block_index) tick: what the agent believed at that turn.

moda world-state conv_5e1a9c2b7d3f4680 --snapshot --msg-index=42

Output (trimmed)

{
  "found": true,
  "segmentIndex": 1,
  "msgIndex": 41,
  "blockIndex": 2,
  "slots": { "refund_status": { "value": "failed", "msg_index": 38, "receipt_id": "rcpt_91" } }
}

msgIndex/blockIndex in the response are the tick of the last applied state change at or before the requested tick. An unknown conversation (or no state at that tick) returns found: false with empty slots and the CLI adds a not-found warning.

Flag	Default	Description
`--snapshot`	off	Fold state up to the requested tick.
`--msg-index`	0	0–100,000.
`--block-index`	0	0–100,000. Events at `msg-index` with a block at or below this are included.
`--segment-index`	—	Scope the fold to one segment.

Replay — state evolution over time, frame by frame or as raw fold inputs.

moda world-state conv_5e1a9c2b7d3f4680 --replay --message-count=50
moda world-state conv_5e1a9c2b7d3f4680 --replay --format=fold-inputs

Frames mode returns exactly --message-count frames (msgIndex, slots, openThreads, hasSnapshot), carrying state forward between frames; --message-count is required in frames mode — the API returns no frames without it, so the CLI rejects the invocation up front. fold-inputs mode returns the raw keyframes and events (snake_case fields, no count needed). hasData: false means the conversation has no state; the CLI adds a not-found warning.

Flag	Default	Description
`--replay`	off	Return state over time instead of the current state.
`--message-count`	—	Frames to fold (1–1,000,000). Required with `--format=frames`.
`--format`	`frames`	`frames` or `fold-inputs`.

moda audit

Raw span read for a conversation or trace: hierarchy, orphans, duplicates. Useful for debugging ingestion. Alias: moda trace.

moda audit conv_5e1a9c2b7d3f4680

Output (trimmed)

{
  "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`	`auto` (try trace, then conversation), `trace`, `conversation`.
`--include-raw`	off	Attach verbatim raw event bodies.
`--limit`	200	Max spans (1–1,000).

moda step-scores

Graph-PRM step scores for one conversation: per-segment progress curves, the first bad step, and the blended rollup. This is the reward evidence that moda problems and moda ask cite.

moda step-scores conv_5e1a9c2b7d3f4680

Output (trimmed)

{
  "conversation_id": "conv_5e1a9c2b7d3f4680",
  "segments": [
    {
      "segment_id": "seg_3f2a",
      "segment_status_at_scoring": "closed",
      "failure_type": { "failure_type": "tool_misuse", "score": 0.71 },
      "steps": [
        { "unit_id": "unit_18", "message_index": 12, "progress_score": 0.44, "first_bad_step_probability": 0.62, "first_bad_step_reason": "Retried the refund tool without changing arguments." }
      ]
    }
  ],
  "rollup": { "blended_score": 0.58, "segment_count": 2, "weighted_segment_count": 1.6, "total_weight": 2.0 }
}

Argument	Default	Description
`<conversation_id>`	required	Conversation to read.

An unknown or not-yet-scored conversation returns the empty shape (segments: [], rollup: null) with a CLI warning — the API does not 404. Very large conversations can exceed the output budget; the payload is then replaced with a truncation stub (truncated, original_bytes).

moda frustrations

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 context. Frustration is the legacy single-family view. The current multi-family emotion model — frustration, sadness, confusion, anxiety, trust, positive — is served by moda emotions, which analyzes a much larger sample. Prefer emotions for new work.

moda frustrations --days-back=14 --limit=1

Output (trimmed)

{
  "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.
`--include-window`	off	Attach a conversation window around each anchor.
`--window`	1	Turns per side for `--include-window` (1–5).

moda emotions

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

moda emotions --family=confusion --days-back=7 --limit=1

Output (trimmed)

{
  "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, "has_more": true }
}

Flag	Default	Description
`--family`	—	`frustration`, `sadness`, `confusion`, `anxiety`, `trust`, `positive`. Filters detections only.
`--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 conversations).
`--limit`	10	1–20.
`--offset`	0	0–10,000.

moda hallucinations

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

moda hallucinations --kind=contradicted --limit=1

Output (trimmed)

{
  "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.",
      "detected_at": "2026-08-15T09:41:07"
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "total": 29 }
}

Flag	Default	Description
`--kind`	—	`contradicted` or `verified`. Filters the detections list.
`--conversation-id`	—	Scope to one conversation. Note: this narrows the summary aggregates too, not just the list.
`--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 tool-failures

Per-tool failure overview for the window.

moda tool-failures --days-back=7

Output (trimmed)

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

moda tool-failure-detail

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

moda tool-failure-detail lookupCustomer --limit=1

Output (trimmed)

{
  "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.
`--days-back`	7	1–90.
`--limit`	5	1–20.
`--offset`	0	Pagination offset.
`--include-window` / `--window`	off / 1	Attach conversation windows around each anchor.

moda problems

The ranked cross-signal problem list (what to fix first). The CLI appends dashboard_url for the corresponding dashboard page.

moda problems --days-back=30 --limit=1

Output (trimmed)

{
  "summary": { "days_back": 30, "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,
      "affected_users": 19,
      "affected_conversations": 44
    }
  ],
  "untrusted": [],
  "dashboard_url": "https://moda.dev/dashboard/problems"
}

Flag	Default	Description
`--days-back`	30	1–90.
`--limit`	25	1–25.

moda problem

Open one Problem: the full dossier, or a paged sub-resource view. The dossier includes the rubric, rank trend, sub-problems, verification results, evidence, affected conversations, investigation reports, confidence, hierarchy, and representative stories.

moda problem 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b
moda problem 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --evidence --limit=10
moda problem 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --reports
moda problem 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --conversations --family=tool_failure
moda problem 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --feedback

Output (dossier, trimmed)

{
  "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`).
`--evidence`	off	Paged attribution evidence (rationales, anchors, replay verification).
`--reports`	off	Paged investigation reports (mechanism, narrative, citations).
`--conversations`	off	Paged affected conversations with deep-link anchors.
`--feedback`	off	The problem’s feedback queue and pending count.
`--limit`	25 (evidence/conversations), 20 (reports)	1–50.
`--cursor`	—	Keyset cursor from the previous page’s `next_cursor`. Opaque — pass it back verbatim.
`--family`	—	`--conversations` filter: `tool_failure`, `emotion`, `laziness`, `hallucination`, `prm_dip`.
`--door`	—	`--conversations` filter: `rubric_match`, `local_causal_chain`.

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

moda problem-feedback 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --action=mark_fixed
moda problem-feedback 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --action=dismiss --reason="not actionable"
moda problem-feedback 3f2a9c1e-8b4d-4e6f-9a2b-1c3d5e7f9a0b --action=rename --new-name="CRM lookup timeouts"

Output

{ "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 problem <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 feedback

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

moda feedback "cluster label looks wrong" --category=bad_cluster_label --cluster-id=node_44

Output

{ "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.
`--category`	`other`	`bad_cluster_label`, `mismatched_frustration`, `missing_data`, `noisy_data`, `wrong_tool_failure`, `incorrect_loop`, `api_quirk`, `other`.
`--severity`	`low`	`info`, `low`, `medium`, `high`.
`--conversation-id`, `--cluster-id`, `--tool-name`, `--run-id`	—	Attach references.

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.

moda tail                                # new conversations, every 15s
moda tail --signal=all --interval=30     # conversations + emotion detections
moda tail --once --max-events=10         # one poll (baseline page), bounded

Output (one line per item)

{"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`	`conversations`	`conversations`, `emotions`, `all`.
`--interval`	15	Seconds between polls (5–3,600).
`--once`	off	One poll, then exit.
`--limit`	20	Conversations 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: conversations re-emit when they advance (message_count changes — long-running, single-conversation-per-user tenants update in place); emotion detections emit once per detection_id. 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.

Production intelligence

moda investigate

Aggregates overview, tool failures, and frustrations into ranked findings with evidence references and next commands. --tool=NAME scopes to one tool; --conversation=ID records the conversation you are investigating.

moda investigate --days-back=7 --tool=lookupCustomer

Output (trimmed)

{
  "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 tool-failure-detail lookupCustomer --include-window"],
  "sourceStatus": { "overview": "ok", "tools": "ok", "frustrations": "ok" }
}

moda failures

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

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

moda ask "what should I fix first?" --json

Output (trimmed)

{
  "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 conversations...",
  "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.

Prompt management

Code-first prompt workflow — see Prompt management for concepts and Workflow for the end-to-end guide. Running moda prompts with no subcommand is equivalent to moda prompts status.

moda prompts init

Creates .moda/prompts.yml if absent (never overwrites). The default manifest discovers prompts/**/*.prompt.{md,json,yaml,yml}.

moda prompts init

Output

{
  "manifest": ".moda/prompts.yml",
  "lockfile": ".moda/prompts.lock.json",
  "promptPaths": ["prompts/**/*.prompt.md", "prompts/**/*.prompt.json", "prompts/**/*.prompt.yaml", "prompts/**/*.prompt.yml"]
}

moda prompts status / moda prompts diff

Local-only comparison of discovered prompt files against .moda/prompts.lock.json. No network call. diff is an alias for status (it is not a textual diff). Per-prompt state is new, changed, unchanged, or deleted.

moda prompts status

Output (trimmed)

{
  "manifest": ".moda/prompts.yml",
  "lockfile": ".moda/prompts.lock.json",
  "total": 3,
  "changed": 1,
  "new": 0,
  "deleted": 0,
  "prompts": [
    { "key": "support.triage", "sourcePath": "prompts/support/triage.prompt.md", "contentHash": "b41f0c…", "lockedHash": "a92c7e…", "versionId": "pver_1f2e3d4c5b6a79880911223344556677", "state": "changed" }
  ]
}

moda prompts sync

Uploads all discovered prompts (unchanged ones are server-side no-ops — versions are content-addressed and immutable), moves each prompt’s current pointer to the synced version, and writes .moda/prompts.lock.json.

moda prompts sync

Output (trimmed)

{
  "synced": [
    { "key": "support.triage", "promptId": "prompt_0a1b2c3d4e5f60718293a4b5", "versionId": "pver_1f2e3d4c5b6a79880911223344556677", "contentHash": "b41f0c…", "sourcePath": "prompts/support/triage.prompt.md" }
  ],
  "lockfile": ".moda/prompts.lock.json"
}

Flag	Default	Description
`--dry-run`	off	Compute IDs without writing anything (no lockfile update).
`--watch`	off	Poll local files and re-sync on change.
`--interval`	2500	Poll interval in ms for `--watch` (min 1,000).

moda prompts promote

Moves a release label (dev, staging, prod) to a specific version. Returns the updated prompt with all versions.

moda prompts promote support.triage --label=prod --version=pver_1f2e3d4c5b6a79880911223344556677

Argument / flag	Description
`<key>`	Prompt key (required).
`--label`	`dev`, `staging`, or `prod` (required).
`--version`	Target version ID from the lockfile (`--version-id` is an alias; required).

A dev promotion moves the same pointer that every sync overwrites, so it is replaced by the next moda prompts sync. Use staging/prod for stable release labels.

moda prompts ab

Judged A/B replay comparison between a baseline and a candidate prompt. Builds (or reuses) a replay set, runs both arms, and reports a verdict — the candidate wins only with strictly more passed cases. See Experiments.

moda prompts ab --baseline=prompts/support/triage.prompt.md --candidate=prompts/support/triage-v2.prompt.md --conversations=conv_5e1a9c2b7d3f4680,conv_8c33d2f1a09b44e7

The command polls the run every 15 seconds and prints per-case results plus the final verdict; --no-wait returns immediately after enqueueing.

Flag	Default	Description
`--baseline` / `--candidate`	required	Prompt file paths or synced prompt keys.
`--set-id`	—	Reuse an existing replay set (`--replay-set-id` alias).
`--conversations`	—	Comma-separated conversation IDs to build a set from.
`--cases`	5	Cases for an auto-generated set.
`--lookback-days`	30	Window for auto-generated cases.
`--seeds`	3	Seeds per case (max 10).
`--model`	—	Assistant model override for the replay.
`--sync`	off	Run `moda prompts sync` first.
`--no-wait`	off	Return after enqueue instead of polling.
`--timeout` / `--poll-interval`	2 h / 15 s	Polling bounds.
`--tenant-id`	from config	Tenant to run in.

moda prompts propose

Generates a revised, unlabeled candidate version from a failed A/B run’s failure evidence.

moda prompts propose support.triage --from-run=run_9d2e --set-id=rset_31ab --out=prompts/support/triage-v2.prompt.md

Argument / flag	Default	Description
`<key>`	required	Prompt key (`--prompt-key` alias).
`--from-run`	required	Source A/B run ID (`--from-run-id` / `--run-id` aliases).
`--set-id`	required	Replay set ID (`--replay-set-id` alias).
`--max-dossiers`	8	Failure dossiers fed to the revision (max 16).
`--out`	—	Write the candidate content to a file.
`--gate`	off	Auto-run an A/B of candidate vs. baseline over the replay set.
`--promote-on-win`	off	Promote the candidate to `prod` only on a strict win (requires `--gate`).

Skills

Moda can distill recurring agent behavior into skill files and sync them with your repo. Skill commands talk to the Ingestion API host (MODA_INGEST_URL) and the control plane using your API key.

moda skills gen

Kicks off tenant-wide skill generation and returns a run ID.

moda skills gen

Output

accepted: true
generation_run_id: 51f2b3a4-9c8d-4e7f-a1b2-c3d4e5f6a7b8
follow progress: moda skills status 51f2b3a4-9c8d-4e7f-a1b2-c3d4e5f6a7b8

Flags: --source=all|sdk, --max-sessions=N, --start-at=ISO, --end-at=ISO, --wait.

moda skills status

Status, outcome, and recent events for a generation run (latest run when no ID is given). Exits 1 when the run failed.

moda skills status 51f2b3a4-9c8d-4e7f-a1b2-c3d4e5f6a7b8

moda skills pull

Downloads tenant-generated skills into .claude/skills/**/SKILL.md (and .cursor/rules), tracked in .moda/skills.yml.

moda skills pull --status=proposed

Flag	Default	Description
`--status`	`approved`	`approved`, `proposed`, or `all`.

moda skills sync

Pushes local .claude/skills/**/SKILL.md files up to Moda. --dry-run shows what would be pushed.

moda skills sync --dry-run

moda skills proposals / moda skills proposal apply

moda skills proposals list [--status=ready_for_pr] lists skill improvement proposals with baseline/candidate pass rates. moda skills proposal apply <proposal-id> writes the proposed SKILL.md locally and acknowledges the proposal; it exits 1 if the local write succeeded but the acknowledgment failed (re-run to retry).

moda skills proposals list

Harness

The harness commands produce and sync the cited map of your agent codebase. The supported path for analysis is the Moda GitHub App (see Harness); the CLI analyze path is experimental.

moda harness analyze

Produces a cited harness report. Gated: without --experimental or MODA_HARNESS_ANALYZE_CLI=1 it prints a pointer to the GitHub App and exits 1.

moda harness analyze --json

Output (gated)

{
  "schema": "harness_analyze_disabled.v0.1",
  "status": "disabled",
  "reason": "cli_analyze_gated",
  "message": "Harness analysis now runs automatically via the Moda GitHub App — connect your repo in the Moda dashboard (Settings → Integrations). To run the experimental CLI analyze anyway, pass --experimental or set MODA_HARNESS_ANALYZE_CLI=1."
}

Flag	Description
`--experimental`	Opt in to CLI analysis (or set `MODA_HARNESS_ANALYZE_CLI=1`).
`--remote`	Upload a safe source snapshot and analyze server-side (no local coding agent needed).
`--github-actions`	GitHub Actions OIDC mode — no Moda API key on the runner.
`--analyst=claude\|codex\|cursor\|local-scan`	Local analyst adapter.
`--yes`	Skip the read-plan approval prompt.

moda harness pull

Fetches a server-side analyze run (status while running, the report when done). --sync also syncs a passing report. --run-id targets a specific run; otherwise the run recorded in .moda/harness-remote-run.json is used.

moda harness pull --sync

moda harness validate-report / approve / sync

validate-report checks .moda/harness-report.json citations. approve --yes validates and writes a hash-bound approval file; sync --from-report uploads the approved report to Moda Cloud (it refuses unapproved reports) and writes .moda/sync-state.json. moda sync and moda sync harness are top-level aliases for harness sync; moda sync prompts aliases moda prompts sync.

moda harness approve --yes
moda harness sync --from-report .moda/harness-report.json

moda harness scan / candidates / agents / explain

Local, no-LLM inspection commands:

moda harness scan — discover local runtime agents and write .moda/harness.json (--json for structured output).
moda harness candidates — static candidate pre-pass with file:line citations (--out=PATH).
moda harness agents — list detected runtime agents and families.
moda harness explain [--agent=<id>] — explain the discovered harness graph.

moda harness explain --agent=agent_support

moda harness delete

Permanently deletes a synced harness from Moda Cloud.

moda harness delete my-harness-key --yes

Agent-native commands

moda agent context, moda agent investigate, moda agent next-action, and moda agent evidence <ref> emit local Moda context, readiness diagnostics, prioritized next commands, and expanded evidence for coding agents. They default to agent JSON output in every environment. See Using the CLI from agents and CI.

moda agent next-action

Next steps

Using the CLI from agents and CI — envelope schema, exit-code recipes, CI examples.
Data API overview — the same data over HTTP.
Prompt management workflow — the full prompts loop these commands drive.
Harness CI rescan — the generated rescan workflow in detail.

​Setup and diagnostics

​moda init

​moda provision

​moda status

​moda doctor

​moda manifest

​moda profiles / moda config

​moda keys

​Sessions

​moda auth login

​moda auth status

​moda auth token

​moda auth whoami

​moda auth logout

​Production data

​moda overview

​moda clusters

​moda cluster-conversations

​moda conversations

​moda search

​moda context

​moda world-state

​moda audit

​moda step-scores

​moda frustrations

​moda emotions

​moda hallucinations

​moda tool-failures

​moda tool-failure-detail

​moda problems

​moda problem

​moda problem-feedback

​moda feedback

​moda tail

​Production intelligence

​moda investigate

​moda failures

​moda ask

​Prompt management

​moda prompts init

​moda prompts status / moda prompts diff

​moda prompts sync

​moda prompts promote

​moda prompts ab

​moda prompts propose

​Skills

​moda skills gen

​moda skills status

​moda skills pull

​moda skills sync

​moda skills proposals / moda skills proposal apply

​Harness

​moda harness analyze

​moda harness pull

​moda harness validate-report / approve / sync

​moda harness scan / candidates / agents / explain

​moda harness delete

​Agent-native commands

​Next steps

Setup and diagnostics

moda init

moda provision

moda status

moda doctor

moda manifest

moda profiles / moda config

moda keys

Sessions

moda auth login

moda auth status

moda auth token

moda auth whoami

moda auth logout

Production data

moda overview

moda clusters

moda cluster-conversations

moda conversations

moda search

moda context

moda world-state

moda audit

moda step-scores

moda frustrations

moda emotions

moda hallucinations

moda tool-failures

moda tool-failure-detail

moda problems

moda problem

moda problem-feedback

moda feedback

moda tail

Production intelligence

moda investigate

moda failures

moda ask

Prompt management

moda prompts init

moda prompts status / moda prompts diff

moda prompts sync

moda prompts promote

moda prompts ab

moda prompts propose

Skills

moda skills gen

moda skills status

moda skills pull

moda skills sync

moda skills proposals / moda skills proposal apply

Harness

moda harness analyze

moda harness pull

moda harness validate-report / approve / sync

moda harness scan / candidates / agents / explain

moda harness delete

Agent-native commands

Next steps