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

# Chat

> Query your Unbound usage data with natural language from the terminal

`unbound chat` lets you ask questions about your AI usage data in natural language. It renders charts and tables directly in the terminal.

Requires **Admin or Manager** role. Run `unbound whoami` to check.

## Interactive session

Start a multi-turn REPL:

```bash theme={null}
unbound chat
```

Session commands:

| Command          | Action                               |
| ---------------- | ------------------------------------ |
| `/help`          | Show available commands              |
| `/json`          | Print the last result as JSON        |
| `/export <path>` | Write the last result to a file      |
| `/clear`         | Reset conversation history in memory |
| `/exit`          | Quit (Ctrl+C also works)             |

Add `--no-suggestions` to skip the follow-up question picker after each turn.

## One-shot mode

Ask a single question and exit:

```bash theme={null}
unbound chat -m "show cost by provider for the last 30 days"
unbound chat -m "which users spent the most this month"
unbound chat -m "MCP tool calls by server last week"
```

Each `-m` call sends no history — keep prompts self-contained.

## Output flags

| Flag        | Behavior                                                       |
| ----------- | -------------------------------------------------------------- |
| `--json`    | Write raw JSON response to stdout                              |
| `-o <path>` | Write raw JSON to a file (refuses to overwrite existing files) |

```bash theme={null}
# Pipe to jq:
unbound chat -m "cost by provider last 30 days" --json | jq '.intent'
unbound chat -m "cost by provider last 30 days" --json | jq '.result.chart_option'

# Save to file:
unbound chat -m "cost by provider last 30 days" -o report.json

# Pipe and archive simultaneously:
unbound chat -m "cost by provider last 30 days" --json -o report.json | jq '.intent'
```

## JSON response shape

```json theme={null}
{
  "message": "...",
  "intent": "sql_visualise | conversational | invalid",
  "result": { ... },
  "suggestions": [{ "label": "...", "query": "...", "description": "..." }],
  "turn": { "role": "assistant", "content": "...", "timestamp": "..." }
}
```

| Intent           | Meaning                                                                       |
| ---------------- | ----------------------------------------------------------------------------- |
| `sql_visualise`  | A chart was generated; `result` is populated                                  |
| `conversational` | The model wants clarification; use a `suggestions[i].query` as your follow-up |
| `invalid`        | The prompt could not be answered; exit code is `1`                            |

## Exit codes

| Code | Meaning                                                         |
| ---- | --------------------------------------------------------------- |
| `0`  | Success                                                         |
| `1`  | `intent == "invalid"`, auth failure, role error, or write error |