moda CLI workflows. Install and authentication are covered in the CLI overview; this page lists each command by area.
Conventions used below:
- Flags accept
--flag=valueor--flag value. Boolean flags are--flag. - Data commands call the Data API (
https://moda.dev/api/v1/data,x-api-keyauth) 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
--jsonprints them (the raw payload, trimmed to representative fields). Piped and CI invocations get amoda.agent.v1envelope instead, with the same payload underdata— see Using the CLI from agents and CI. - 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:
askuses 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.deprecatedin agent output);moda <old-name> --helpnames 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 theconversation/conversation_idnames 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.
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 status
Concise local setup state (config, credentials, synced artifacts).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 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.
Output (trimmed)
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.
Sessions
The CLI has two independent credentials, and theauth commands report both:
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.
Output
--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:
Output
--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).
Output
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.
moda auth api-key
Prints the savedmoda_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.
moda auth whoami
Shows the authenticated user, session expiry, and available tenants.Output
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. IfMODA_API_KEY is set in the environment it still takes precedence afterwards; unset it to fully sign out.
Output
Production data
These commands reject flags they don’t take: a typo or an unsupported filter exits1 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.
Output (trimmed)
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.
Did my change make it worse?
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.
Output (trends, trimmed)
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.Output (trimmed)
Instead of walking the hierarchy, find a cluster by meaning with
--search, or resolve a node deep link deterministically with --node-id:
Output (trimmed)
moda cluster-traces
List traces in one cluster node. Legacy alias:moda cluster-conversations.
Output (trimmed)
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.
Output (trimmed)
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.Output
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.Output (trimmed)
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.
Output (trimmed)
--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 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.
Output (trimmed)
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.
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.
Output (trimmed)
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.
Output (agent, trimmed)
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).
--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 ananchor 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 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.
Output (trimmed)
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.
Output (trimmed)
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.
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.Output (trimmed)
incident_id (null for rows from before hallucinations came from validated incidents); moda traces findings shows it as incident.
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.
Output (trimmed)
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.Output (trimmed)
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-addedanchor (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.
Output (trimmed)
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).
Output (trimmed)
has_more is true, next_commands holds the next page (moda tools list --sort=failure_rate --limit=2 --offset=2).
moda tools get
One tool: call stats, its registered definition (description and schema, ornull) 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.
Output (trimmed)
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.
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.
Output (Book, trimmed)
Output (dream view, trimmed)
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.
Output (dossier, trimmed)
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.Output
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.
Output
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).
Output
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.Output
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.
Output (one line per item)
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.
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.
Output (trimmed)
moda failures
Same investigation, restricted to failure findings (frustration findings excluded). Flags:--days-back, --tool.
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.
Output (trimmed)
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.
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.
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 — envelope schema, exit-code recipes, CI examples.
- Data API overview — the same data over HTTP.
Problem impact by use case
Theaffected-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.
--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.