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

# Chat

> Run one-shot and interactive grounded chat from the terminal.

`ragrails chat` answers with retrieved context from your vector database. Pass a query for a one-shot turn, or run it with no query to start an interactive REPL.

## One-shot Chat

```bash theme={null}
ragrails chat "How long do I have to request a refund?" \
  --vector-db qdrant \
  --collection support \
  --url http://localhost:6333 \
  --embedder-provider voyage \
  --embedder-model voyage-3 \
  --llm-provider openai \
  --llm-model gpt-4o-mini
```

Output:

```text theme={null}
You can request a refund within 30 days of purchase.

Sources:
[1] Refund policy
```

## Multi-turn with History File

`--history-file` persists conversation history across one-shot turns.

```bash theme={null}
ragrails chat "How long do I have to request a refund?" \
  --history-file files/chat/history.json \
  --vector-db qdrant --collection support --url http://localhost:6333

ragrails chat "What about the payment method?" \
  --history-file files/chat/history.json \
  --rewrite-query
```

## Interactive Chat

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

The REPL keeps session history, can stream answers, and can call built-in tools.

| Command                      | What it does                                    |
| ---------------------------- | ----------------------------------------------- |
| `/model`                     | List models, or `/model gpt-4o-mini` to switch. |
| `/stream on` / `/stream off` | Toggle token-by-token streaming.                |
| `/tools`                     | List built-in tools.                            |
| `/debug`                     | Show the retrieval trace for the last answer.   |

## Agentic Tools

Interactive chat can call `web_fetch` and `api_call`. Side-effecting API calls are validated and confirmed before execution.

Use [Agentic Tools](/capabilities/agentic-tools) for the safety model and boundaries.

## Options

| Option                                               | Default                          | Description                                   |
| ---------------------------------------------------- | -------------------------------- | --------------------------------------------- |
| `QUERY`                                              | none                             | Question. Omit to start the interactive REPL. |
| `--llm-provider`                                     | `openai`                         | LLM provider.                                 |
| `--llm-model`                                        | `gpt-4o-mini`                    | LLM model.                                    |
| `--max-tokens`                                       | `1024`                           | Max output tokens.                            |
| `--embedder-provider` / `--embedder-model`           | `voyage` / `voyage-3`            | Query embedding provider/model.               |
| `--vector-db`                                        | `qdrant`                         | Vector DB provider.                           |
| `--collection`                                       | config or none                   | Collection, index, or class name.             |
| `--url`                                              | config or none                   | Vector DB URL.                                |
| `--persona`                                          | `""`                             | System persona/domain instruction.            |
| `--history-file`                                     | none                             | JSON history file to load and save.           |
| `--rewrite-query`                                    | off                              | Rewrite follow-up questions before retrieval. |
| `--rewrite-session-context`                          | `""`                             | Context hint for query rewrite.               |
| `--rerank`                                           | off                              | Rerank retrieved chunks.                      |
| `--reranker` / `--reranker-model` / `--rerank-top-k` | `voyage` / `rerank-2-lite` / `5` | Reranker config.                              |
| `--disable-intent-routing`                           | off                              | Always run retrieval.                         |
| `--disable-history-compaction`                       | off                              | Return full history without summarization.    |

<CardGroup cols={2}>
  <Card title="Query" icon="search-check" href="/usage/cli/query">Use chat in the query workflow.</Card>
  <Card title="Streaming" icon="radio" href="/capabilities/streaming">Understand interactive streaming boundaries.</Card>
</CardGroup>