Skip to main content

​
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. The same package also ships an MCP server for AI assistants — see MCP Server for that setup.

​
Prerequisites

​
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
FlagDefaultDescription
--days-back7Number 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
FlagDefaultDescription
--parent-id—Parent node ID to drill down (omit for root)
--time-rangeallall, 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 / FlagDefaultDescription
<node_id>requiredCluster node ID
--limit10Max results (1-100)
--offset0Pagination offset

​
conversations

Search and filter conversations. 
moda conversations --search="error"
moda conversations --time-range=24h --environment=production
moda conversations --user-id=user_123 --limit=5
FlagDefaultDescription
--search—Full-text search in summaries
--cluster-id—Filter by cluster node ID
--user-id—Filter by user ID
--time-rangeallall, 1h, 3d, 24h, 7d, 30d, 90d
--environmentallall, development, staging, production
--limit20Max results (1-100)
--offset0Pagination offset

​
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 / FlagDefaultDescription
<conversation_id>requiredConversation ID
--msg-indexmiddleMessage index to center on (0-indexed)
--window2Messages 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
FlagDefaultDescription
--days-back7Number of days to look back (1-90)
--limit10Max results (1-20)
--offset0Pagination 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
FlagDefaultDescription
--days-back7Number 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 / FlagDefaultDescription
<tool_name>requiredName of the tool to inspect
--subtype—Filter by error subtype
--days-back7Number of days to look back (1-90)
--limit5Max examples (1-20)
--offset0Pagination offset

​
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

VariableRequiredDefaultDescription
MODA_API_KEYYes—Your Moda API key (moda_sk_...)
MODA_BASE_URLNohttps://modaflows.comBase URL for the Data API

​
Troubleshooting

Export your API key before running commands:
export MODA_API_KEY="moda_sk_your_key_here"
The CLI connects to https://modaflows.com by default. Override with MODA_BASE_URL if needed.
Install globally: npm install -g @moda-ai/cli. Or use npx:
npx -p @moda-ai/cli moda overview
The same @moda-ai/cli package also includes an MCP server for AI assistants. See MCP Server for setup instructions.