CLI

Overview

The Moda CLI gives you direct terminal access to your conversation analytics. Query dashboards, search conversations, investigate frustrations, and debug tool failures without leaving your shell.

Prerequisites

Node.js 18+
A Moda API key (get one here)

Installation

npm install -g @moda-ai/cli

Or use without installing:

npx -p @moda-ai/cli moda overview

Agent Skill

Install the Agent Skill so your AI assistant knows how to use the CLI:

npx skills add ModaLabs/moda-cli

Set your API key:

export MODA_API_KEY="moda_sk_your_key_here"

Commands

overview

Get a high-level dashboard of your conversation analytics.

moda overview
moda overview --days-back=30

Flag	Default	Description
`--days-back`	7	Number of days to look back (1-90)

Returns total conversations, trend percentage, frustration rate, tool failure summary, top clusters, and recent activity.

clusters

Browse the topic cluster hierarchy.

moda clusters                              # Root-level categories
moda clusters --parent-id=node-abc         # Drill into a category
moda clusters --time-range=7d              # Filter by time

Flag	Default	Description
`--parent-id`	—	Parent node ID to drill down (omit for root)
`--time-range`	`all`	`all`, `1h`, `3d`, `7d`, `24h`, `30d`, `90d`

cluster-conversations

List conversations belonging to a specific cluster.

moda cluster-conversations <node_id>
moda cluster-conversations node-abc --limit=20

Argument / Flag	Default	Description
`<node_id>`	required	Cluster node ID
`--limit`	10	Max results (1-100)
`--offset`	0	Pagination offset

conversations

Search and filter conversations. The --world-state and --outcome flags let you find conversations by what the agent has learned (world-state slots and durable user profile) and by how they went.

moda conversations --search="error"
moda conversations --time-range=24h --environment=production
moda conversations --user-id=user_123 --limit=5
# Positive conversations that mention "enterprise" in their world state
moda conversations --world-state="enterprise" --outcome=positive
# Multiple keywords are ANDed; attach each result's world state
moda conversations --world-state="refund,billing" --include-world-state

Flag	Default	Description
`--search`	—	Full-text search in summaries
`--cluster-id`	—	Filter by cluster node ID
`--user-id`	—	Filter by user ID
`--time-range`	`all`	`all`, `1h`, `3d`, `24h`, `7d`, `30d`, `90d`
`--environment`	`all`	`all`, `development`, `staging`, `production`
`--world-state`	—	Keyword(s) matched (case-insensitive substring) against world-state content — both segment slots and carried-in durable profile slots. Comma-separated terms are ANDed (all must appear).
`--outcome`	`any`	`any`, `positive`, or `negative`. `positive` = a high blended segment score (graph PRM) and no frustration; `negative` = a low blended segment score or a frustrated conversation.
`--include-world-state`	off	Attach each result’s world-state summary (slots + segment summaries).
`--limit`	20	Max results (1-100)
`--offset`	0	Pagination offset

World-state search is keyword-based, not key=value: slot key naming isn’t standardized across agents, so a keyword matches anywhere in a conversation’s world-state content (slot keys, values, and durable profile).

PRM scoring is segment-grain: --outcome judges conversations that have per-segment scores on a weighted blend of their segment closing scores (unit-count weighted, recency-decayed, lifecycle-status weighted). Conversations without segment scores — history from before scoring moved to segment grain — are judged on the legacy whole-conversation closing score. The step-scores endpoint (GET /v1/data/conversations/:id/step-scores) returns segments[] (per-terminal-segment score curves, newest scoring pass per segment) and rollup (the weighted blend, null until the segment lane has scored the conversation); its top-level steps[] curve comes from the retired whole-conversation lane and is populated only for those pre-cutover conversations.

search

Search message anchors with keyword, semantic, or hybrid retrieval. Results always include conversation_id, message_index, snippet, and score. Unit-backed tenants may also return unit_id, content_block_index, block_type, tool_name, and chunk_index.

moda search "refund policy"
moda search "database timeout" --mode=semantic --time-range=7d
moda search "tool failed" --include-tool-io

Argument / Flag	Default	Description
`<query>`	required	Text to retrieve
`--mode`	`hybrid`	`keyword`, `semantic`, or `hybrid`
`--user-id`	—	Scope to one user
`--time-range`	`all`	`all`, `1h`, `3d`, `24h`, `7d`, `30d`, `90d`
`--include-tool-io`	off	Include substantive tool-use and tool-result units; degenerate content remains excluded
`--limit`	20	Max results (1-100)

world-state

Get a single conversation’s world state — the structured slots, open threads, and the event log of how they were learned.

moda world-state <conversation_id>
moda world-state <conversation_id> --summary-only
moda world-state <conversation_id> --event-limit=500

Argument / Flag	Default	Description
`<conversation_id>`	required	Conversation ID
`--summary-only`	off	Return segment summaries only (omit the event stream)
`--event-limit`	2000	Max world-state events to return (1-5000)

context

Get a window of messages from a conversation.

moda context <conversation_id>
moda context <conversation_id> --msg-index=5
moda context <conversation_id> --window=3

Argument / Flag	Default	Description
`<conversation_id>`	required	Conversation ID
`--msg-index`	middle	Message index to center on (0-indexed)
`--window`	2	Messages before and after center (1-5)

Returns messages centered around the specified index: window messages before + center message + window messages after.

frustrations

Get user frustration detections with inline evidence.

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

Flag	Default	Description
`--days-back`	7	Number of days to look back (1-90)
`--limit`	10	Max results (1-20)
`--offset`	0	Pagination offset

Each result includes frustration score, trajectory, primary cause, user quotes, signal breakdown, and inline conversation context.

tool-failures

Get tool failure overview.

moda tool-failures
moda tool-failures --days-back=30

Flag	Default	Description
`--days-back`	7	Number of days to look back (1-90)

tool-failure-detail

Get detailed failure info for a specific tool.

moda tool-failure-detail <tool_name>
moda tool-failure-detail search --subtype=SEARCH_NO_RESULTS

Argument / Flag	Default	Description
`<tool_name>`	required	Name of the tool to inspect
`--subtype`	—	Filter by error subtype
`--days-back`	7	Number of days to look back (1-90)
`--limit`	5	Max examples (1-20)
`--offset`	0	Pagination offset

feedback

Flag wrong or missing data (a cluster label that doesn’t fit, a frustration that doesn’t match its transcript, an empty result that shouldn’t be) or a CLI quirk. Feedback is tenant-scoped and goes straight to the Moda team.

moda feedback "cluster label looks wrong" --category=bad_cluster_label --cluster-id=<node_id>
moda feedback "search finds nothing for a conversation I can open" --category=missing_data --conversation-id=<id>

Argument / Flag	Default	Description
`"<note>"`	required	What looked wrong and why (max 4000 chars)
`--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`	—	Attach the conversation you were inspecting
`--cluster-id`	—	Attach a cluster node id
`--tool-name`	—	Attach a tool name
`--run-id`	—	Attach a run id

The CLI nudges callers toward this command: successful agent envelopes carry a meta.tip, and interactive terminals print a one-line tip after each successful command (hide it with MODA_CLI_TIPS=0).

prompts

Manage code-first prompt versions from your repo.

moda prompts init
moda prompts status
moda prompts diff
moda prompts sync
moda prompts sync --watch
moda prompts promote support.triage --label=prod --version=pver_abc123

Command	Effect
`moda prompts init`	Creates `.moda/prompts.yml`
`moda prompts status`	Read-only local status
`moda prompts diff`	Read-only local diff/status
`moda prompts sync`	Uploads changed prompt versions and writes `.moda/prompts.lock.json`
`moda prompts sync --watch`	Watches local prompt files and syncs when hashes change
`moda prompts promote`	Moves a `dev`, `staging`, or `prod` label to a synced version

Runtime calls should use Moda.prompt(...).render(...) or moda.prompt(...).render(...) so spans include prompt metadata. See Prompt Management.

Common Workflows

Daily Health Check

moda overview --days-back=1
moda frustrations --days-back=1 --limit=5
moda tool-failures --days-back=1

Debugging Frustrated Users

# Find frustrated conversations
moda frustrations --days-back=7

# Get context around the frustration point
moda context <conversation_id> --msg-index=<key_turn>

Investigating Tool Failures

# Which tools are breaking?
moda tool-failures

# What errors? See examples with context
moda tool-failure-detail <tool_name>

Exploring User Intents

# What categories exist?
moda clusters

# Drill into a category
moda clusters --parent-id=node-abc

# See example conversations
moda cluster-conversations node-abc --limit=10

Output

All commands output JSON to stdout. Pipe to jq for filtering:

moda overview | jq '.frustrations'
moda frustrations | jq '.frustrations[].primary_cause'
moda tool-failures | jq '.tools[] | {name: .tool_name, failures: .failure_count}'

Environment Variables

Variable	Required	Default	Description
`MODA_API_KEY`	Yes	—	Your Moda API key (`moda_sk_...`)
`MODA_BASE_URL`	No	`https://moda.dev`	Base URL for the Data API

Troubleshooting

MODA_API_KEY environment variable not set

Export your API key before running commands:

export MODA_API_KEY="moda_sk_your_key_here"

No data returned

Verify your API key at moda.dev/settings
Try --days-back=30 for a wider time range
Ensure conversations are being ingested (see Quickstart)

Connection errors

The CLI connects to https://moda.dev by default. Override with MODA_BASE_URL if needed.

Command not found

Install globally: npm install -g @moda-ai/cli. Or use npx:

npx -p @moda-ai/cli moda overview

Getting Started

Ingestion

Frameworks

Prompt Management

Harness

Data API

Overview

Prerequisites

Installation

Agent Skill

Commands

overview

clusters

cluster-conversations

conversations

search

world-state

context

frustrations

tool-failures

tool-failure-detail

feedback

prompts

Common Workflows

Daily Health Check

Debugging Frustrated Users

Investigating Tool Failures

Exploring User Intents

Output

Environment Variables

Troubleshooting

​Overview

​Prerequisites

​Installation

​Agent Skill

​Commands

​overview

​clusters

​cluster-conversations

​conversations

​search

​world-state

​context

​frustrations

​tool-failures

​tool-failure-detail

​feedback

​prompts

​Common Workflows

​Daily Health Check

​Debugging Frustrated Users

​Investigating Tool Failures

​Exploring User Intents

​Output

​Environment Variables

​Troubleshooting

Overview

Prerequisites

Installation

Agent Skill

Commands

overview

clusters

cluster-conversations

conversations

search

world-state

context

frustrations

tool-failures

tool-failure-detail

feedback

prompts

Common Workflows

Daily Health Check

Debugging Frustrated Users

Investigating Tool Failures

Exploring User Intents

Output

Environment Variables

Troubleshooting