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

# CLI

> Query your conversation analytics from the terminal

## 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](https://moda.dev/settings))

## Installation

```bash theme={"dark"}
npm install -g @moda-ai/cli
```

Or use without installing:

```bash theme={"dark"}
npx -p @moda-ai/cli moda overview
```

### Agent Skill

Install the [Agent Skill](https://github.com/ModaLabs/moda-cli) so your AI assistant knows how to use the CLI:

```bash theme={"dark"}
npx skills add ModaLabs/moda-cli
```

Set your API key:

```bash theme={"dark"}
export MODA_API_KEY="moda_sk_your_key_here"
```

## Commands

### overview

Get a high-level dashboard of your conversation analytics.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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 successful, progressing/recovered segment that is not frustrated; `negative` = the inverse.                                              |
| `--include-world-state` | off     | Attach each result's world-state summary (slots + segment summaries).                                                                                                                     |
| `--limit`               | 20      | Max results (1-100)                                                                                                                                                                       |
| `--offset`              | 0       | Pagination offset                                                                                                                                                                         |

<Note>
  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).
</Note>

### world-state

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

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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.

```bash theme={"dark"}
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                  |

### prompts

Manage code-first prompt versions from your repo.

```bash theme={"dark"}
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](/prompt-management/overview).

## Common Workflows

### Daily Health Check

```bash theme={"dark"}
moda overview --days-back=1
moda frustrations --days-back=1 --limit=5
moda tool-failures --days-back=1
```

### Debugging Frustrated Users

```bash theme={"dark"}
# 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

```bash theme={"dark"}
# Which tools are breaking?
moda tool-failures

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

### Exploring User Intents

```bash theme={"dark"}
# 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:

```bash theme={"dark"}
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

<AccordionGroup>
  <Accordion title="MODA_API_KEY environment variable not set">
    Export your API key before running commands:

    ```bash theme={"dark"}
    export MODA_API_KEY="moda_sk_your_key_here"
    ```
  </Accordion>

  <Accordion title="No data returned">
    * Verify your API key at [moda.dev/settings](https://moda.dev/settings)
    * Try `--days-back=30` for a wider time range
    * Ensure conversations are being ingested (see [Quickstart](/quickstart))
  </Accordion>

  <Accordion title="Connection errors">
    The CLI connects to `https://moda.dev` by default. Override with `MODA_BASE_URL` if needed.
  </Accordion>

  <Accordion title="Command not found">
    Install globally: `npm install -g @moda-ai/cli`. Or use npx:

    ```bash theme={"dark"}
    npx -p @moda-ai/cli moda overview
    ```
  </Accordion>
</AccordionGroup>