> ## 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.

# CLI Overview

> Understand the CLI workflows and pipeline stages.

The Ragrails CLI is the terminal interface for building, querying, and maintaining a knowledge base.

Use workflow commands when you want the shortest path: `ingest`, `query`, and `chat`. Use stage commands when you want JSON artifacts between steps that you can inspect, commit, diff, or hand off to another process.

## Setup Wizard

Run `ragrails` with no subcommand to launch the setup wizard before using the CLI regularly.

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

The wizard writes `.ragrails.toml` in the current directory. CLI commands then inherit vector database, embedding, LLM, reranker, chunking, storage, retrieval, and chat defaults from that file. A flag always overrides `.ragrails.toml` for one run.

| Wizard section    | Defaults it captures                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------ |
| Vector store      | Provider, collection, URL                                                                  |
| Embedding         | Provider and model                                                                         |
| LLM               | Provider, model, max tokens                                                                |
| Reranking         | Whether reranking is enabled, provider, model                                              |
| Advanced defaults | Chunking, batch sizes, retrieval limits, query rewrite, intent routing, history compaction |

If `.ragrails.toml` already exists, bare `ragrails` shows the current config and lets you `edit`, `reset`, or `exit`.

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

<Note>There is no `ragrails setup` subcommand. `ragrails setup-url` only installs the browser runtime used by website extraction.</Note>

## Workflows

| Workflow                      | Use it for                                      | Details                                          |
| ----------------------------- | ----------------------------------------------- | ------------------------------------------------ |
| [`ingest`](/usage/cli/ingest) | Build a searchable knowledge base from sources. | Extracts, chunks, embeds, and stores content.    |
| [`query`](/usage/cli/query)   | Search the indexed knowledge base.              | Embeds the query and retrieves matching chunks.  |
| [`chat`](/usage/cli/chat)     | Ask grounded questions over the knowledge base. | Retrieves context and asks an LLM for an answer. |

```bash theme={null}
ragrails ingest --docs files/refund-policy.pdf \
  --vector-db qdrant --collection support --url http://localhost:6333

ragrails query "How long do refunds take?" \
  --vector-db qdrant --collection support --url http://localhost:6333

ragrails chat "How long do refunds take?" \
  --vector-db qdrant --collection support --url http://localhost:6333
```

## Pipeline

Start with the [pipeline overview](/usage/cli/pipeline-overview), or jump directly to a stage:

| Stage                                                | Commands                    | Details                                              |
| ---------------------------------------------------- | --------------------------- | ---------------------------------------------------- |
| [Extraction](/usage/cli/extraction)                  | `scrape`, `parse`, `fetch`  | Turn websites, files, and APIs into extraction JSON. |
| [Chunking](/usage/cli/chunking)                      | `chunk`                     | Split extraction JSON into retrievable chunks.       |
| [Embedding](/usage/cli/embedding)                    | `embed`                     | Generate vectors for chunk JSON.                     |
| [Storing](/usage/cli/storing)                        | `store`, `edit`, `delete`   | Upsert, replace, and remove stored chunks.           |
| [Retrieval](/usage/cli/retrieval)                    | `retrieve`                  | Search and optionally rerank stored chunks.          |
| [Maintenance](/usage/cli/knowledge-base-maintenance) | `edit`, `delete`, re-ingest | Refresh or remove stale knowledge base content.      |

```bash theme={null}
ragrails parse --files files/refund-policy.pdf --output-dir files/output/docs/
ragrails chunk --input-dir files/output/docs/ --output-dir files/output/chunks/
ragrails embed --input-dir files/output/chunks/ --output-dir files/output/embedded/
ragrails store --input-dir files/output/embedded/ \
  --vector-db qdrant --collection support --url http://localhost:6333
ragrails retrieve "How long do refunds take?" \
  --vector-db qdrant --collection support --url http://localhost:6333
```

## Command Index

| Command     | Purpose                                                               |
| ----------- | --------------------------------------------------------------------- |
| `doctor`    | Diagnose config, packages, keys, and optional vector DB connectivity. |
| `setup-url` | Install the browser runtime for URL scraping.                         |
| `scrape`    | Extract website pages.                                                |
| `parse`     | Extract documents.                                                    |
| `fetch`     | Extract REST API responses.                                           |
| `chunk`     | Split extraction JSON into chunks.                                    |
| `embed`     | Generate vectors for chunk JSON.                                      |
| `store`     | Upsert embedded chunks.                                               |
| `edit`      | Re-embed and replace chunks by ID.                                    |
| `delete`    | Delete chunks by exact ID.                                            |
| `retrieve`  | Search stored chunks.                                                 |
| `ingest`    | Full ingest workflow.                                                 |
| `query`     | Query embedding plus retrieval workflow.                              |
| `chat`      | One-shot chat or interactive REPL.                                    |

<Note>Some SDK capabilities are not exposed as CLI flags: scrape DLQ retry, raw bytes document input, full API pagination/body config, and query rewriting in `retrieve`. Use [SDK](/usage/sdk/overview) or [REST API](/usage/server/overview) for those.</Note>