> ## Documentation Index > Fetch the complete documentation index at: https://praison.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # RAG CLI > Command-line interface for RAG operations # RAG CLI The `praisonai rag` command group provides full RAG functionality from the command line. ## Commands ### index Build or update an index from source documents. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai rag index [options] ``` **Arguments:** * `sources` - Files, directories, or URLs to index **Options:** * `--collection, -c` - Collection name (default: "default") * `--chunking` - Chunking strategy: token, sentence, recursive, semantic * `--chunk-size` - Chunk size in tokens (default: 512) * `--config, -f` - Config file path * `--verbose, -v` - Verbose output * `--profile` - Enable performance profiling * `--profile-out` - Save profile to JSON file * `--profile-top` - Top N items in profile (default: 20) This command uses the Knowledge substrate for indexing. Equivalent to `praisonai knowledge index`. **Examples:** ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Index a directory praisonai rag index ./documents # Index specific files praisonai rag index paper.pdf report.docx # Index with custom collection praisonai rag index ./data --collection research # Index with semantic chunking praisonai rag index ./docs --chunking semantic --chunk-size 256 ``` `--chunking` and `--chunk-size` reach the `Knowledge` chunker directly. `--chunking` accepts `token`, `sentence`, `recursive` (default), or `semantic`; `--chunk-size` defaults to `512` tokens. #### Chunker precedence with `--config` CLI chunker flags and a config file's `chunker` block merge **field by field** — a file overrides only the fields it sets, leaving the other CLI value intact. ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} graph TB A[--chunking / --chunk-size] --> M{Config file
sets chunker?} C[--config file] --> M M -->|No chunker block| R1[CLI values survive] M -->|Sets type only| R2[File type + CLI chunk_size] M -->|Sets both fields| R3[File wins on both] classDef input fill:#6366F1,stroke:#7C90A0,color:#fff classDef merge fill:#F59E0B,stroke:#7C90A0,color:#fff classDef result fill:#10B981,stroke:#7C90A0,color:#fff class A,C input class M merge class R1,R2,R3 result ``` Given `praisonai rag index ./data --chunking semantic --chunk-size 256 --config cfg.yaml`: | Config file `knowledge.chunker` | Effective chunker | | -------------------------------- | ----------------------------------------------------------------------------------- | | absent | `{type: semantic, chunk_size: 256}` — CLI survives | | `type: token` only | `{type: token, chunk_size: 256}` — file overrides `type`, CLI `chunk_size` survives | | `{type: token, chunk_size: 128}` | `{type: token, chunk_size: 128}` — file wins on both | This field-level merge applies **only** to the `chunker` block. It is an exception to the general [Configuration Precedence](#configuration-precedence) rule below, where CLI flags fully override config-file values. #### Exit codes for `rag index` `rag index` exits `1` when any source stores zero chunks — a broken embedding backend, an empty glob, or an unreadable directory no longer looks like a successful import. | Outcome | Console line | Exit code | | ------------------------------------------ | ---------------------------------------------------------------------------- | ------------------ | | Every source stored ≥ 1 chunk | `✓ Indexed : N chunks` per source, then `Indexing complete!` | `0` | | A source stored zero chunks | `! Indexed nothing from (no supported files, or every file failed)` | contributes to `1` | | A source raised | `✗ Failed to index : ` | contributes to `1` | | Any failed source | `Indexing finished with N failed source(s)` summary | `1` | | Missing `praisonaiagents[knowledge]` extra | `Error: Missing dependency: ...` | `1` | The zero-chunk outcome is the CLI surface of the SDK's `result["errors"]` behaviour. See [Knowledge Indexing Errors](/docs/features/knowledge-indexing-errors) for the underlying failure modes (wrong embedding model name, revoked API key, exhausted quota). ### query One-shot question answering with citations. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai rag query "" [options] ``` **Options:** * `--collection, -c` - Collection to query (default: "default") * `--top-k, -k` - Number of results (default: 5) * `--hybrid` - Use hybrid retrieval (dense + BM25) * `--rerank` - Enable reranking of results * `--citations/--no-citations` - Include citations (default: true) * `--config, -f` - Config file path * `--verbose, -v` - Verbose output * `--profile` - Enable performance profiling * `--profile-out` - Save profile to JSON file * `--profile-top` - Top N items in profile (default: 20) **Examples:** ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Simple query praisonai rag query "What is the main finding?" # Query specific collection praisonai rag query "Summarize the methodology" --collection research # Query with hybrid retrieval (combines dense vectors + BM25 keyword search) praisonai rag query "What are the key findings?" --hybrid # Query with hybrid + reranking for best quality praisonai rag query "Summarize conclusions" --hybrid --rerank # Query with more results praisonai rag query "List all conclusions" --top-k 10 # Query without citations praisonai rag query "Quick summary" --no-citations # Query with profiling praisonai rag query "Summary?" --profile --profile-out ./profile.json ``` ### chat Interactive RAG chat session with streaming. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai rag chat [options] ``` **Options:** * `--collection, -c` - Collection to chat with (default: "default") * `--top-k, -k` - Results per query (default: 5) * `--hybrid` - Use hybrid retrieval (dense + BM25) * `--rerank` - Enable reranking of results * `--config, -f` - Config file path * `--stream/--no-stream` - Stream responses (default: true) **Examples:** ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Start chat session praisonai rag chat # Chat with specific collection praisonai rag chat --collection research # Chat with hybrid retrieval praisonai rag chat --hybrid --rerank # Chat without streaming praisonai rag chat --no-stream ``` **Chat Commands:** * Type questions to get answers * `exit`, `quit`, or `q` to end session * `Ctrl+C` to interrupt ### eval Evaluate RAG retrieval quality against golden queries. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai rag eval [options] ``` **Arguments:** * `test_file` - JSON file with test queries **Options:** * `--collection, -c` - Collection to evaluate (default: "default") * `--top-k, -k` - Results to retrieve (default: 5) * `--output, -o` - Output results to file * `--verbose, -v` - Verbose output * `--profile` - Enable performance profiling * `--profile-out` - Save profile to JSON file * `--profile-top` - Top N items in profile (default: 20) **Test File Format:** ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} [ { "query": "What is the main finding?", "expected_doc": "paper.pdf", "expected_answer_contains": "significant improvement" }, { "query": "What methodology was used?", "expected_doc": "methods.pdf", "expected_answer_contains": "randomized" } ] ``` **Examples:** ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Run evaluation praisonai rag eval golden_queries.json # Evaluate with output praisonai rag eval tests.json --output results.json # Verbose evaluation praisonai rag eval tests.json --verbose ``` ### serve Start RAG as a microservice API. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai serve rag [options] ``` **Options:** * `--collection, -c` - Collection to serve (default: "default") * `--host, -h` - Host to bind (default: 127.0.0.1) * `--port, -p` - Port to bind (default: 8080) * `--hybrid` - Use hybrid retrieval (dense + BM25) * `--rerank` - Enable reranking of results * `--openai-compat` - Enable OpenAI-compatible `/v1/chat/completions` endpoint * `--config, -f` - Config file path * `--verbose, -v` - Verbose output * `--profile` - Enable performance profiling * `--profile-out` - Save profile to JSON file * `--profile-top` - Top N items in profile (default: 20) **Examples:** ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Start server praisonai serve rag # Serve specific collection on custom port praisonai serve rag --collection research --port 9000 # Serve with hybrid retrieval + reranking praisonai serve rag --hybrid --rerank # Serve with OpenAI-compatible endpoint praisonai serve rag --openai-compat --port 8080 # Serve on all interfaces praisonai serve rag --host 0.0.0.0 ``` **API Endpoints:** | Endpoint | Method | Description | | ---------------------- | ------ | -------------------------------------------------------- | | `/health` | GET | Health check (returns collection, hybrid, rerank status) | | `/rag/query` | POST | Query with JSON body | | `/rag/chat` | POST | Streaming chat (SSE) | | `/v1/chat/completions` | POST | OpenAI-compatible endpoint (with `--openai-compat`) | | `/docs` | GET | OpenAPI documentation | **Query Request:** ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "question": "What is the main finding?", "top_k": 5, "include_citations": true, "hybrid": false, "rerank": false } ``` ## Configuration File Create a YAML config file for reusable settings: ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # rag_config.yaml knowledge: sources: - ./documents collection: my_docs chunker: type: semantic chunk_size: 512 chunk_overlap: 50 vector_store: provider: chroma config: persist_directory: ./.praison/knowledge/my_docs retrieval: hybrid: true rerank: true top_k: 5 min_score: 0.5 rag: include_citations: true max_context_tokens: 4000 ``` Use with any command: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} praisonai rag query "Question" --config rag_config.yaml ``` The `Knowledge` chunker reads three keys under `knowledge.chunker`: `type` (default `recursive`), `chunk_size` (default `512`), and `chunk_overlap` (default `50`). `type` accepts `token`, `sentence`, `recursive`, or `semantic`. ## Configuration Precedence Settings are applied in this order (highest priority first): 1. **CLI flags** - `--hybrid`, `--rerank`, `--top-k`, etc. 2. **Environment variables** - `PRAISONAI_HYBRID=true`, etc. 3. **Config file** - YAML configuration 4. **Defaults** - Built-in defaults This means CLI flags always override environment variables, which override config file settings. ## Environment Variables Override settings with environment variables: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} export PRAISONAI_COLLECTION=my_docs export PRAISONAI_TOP_K=10 export PRAISONAI_HYBRID=true export PRAISONAI_RERANK=true export PRAISONAI_MODEL=gpt-4o-mini ``` ## Exit Codes | Code | Meaning | | ---- | ---------------------------------------- | | 0 | Success | | 1 | Error (missing deps, config error, etc.) | For `rag index`, `0` means every source stored at least one chunk and `1` means at least one source stored zero chunks or raised — see [Exit codes for `rag index`](#exit-codes-for-rag-index). ## Knowledge vs RAG **Knowledge** is the indexing and retrieval substrate: * Indexes documents into vector stores * Performs similarity search * Returns raw chunks/documents * Use `praisonai knowledge` for indexing and search without LLM generation **RAG** orchestrates on top of Knowledge: * Retrieves context using Knowledge * Generates answers with an LLM * Provides citations * Use `praisonai rag` for question answering with generated responses Both share the same underlying index. You can index with `knowledge index` and query with `rag query`. ## Tips 1. **Start simple**: Use defaults, then customize 2. **Use hybrid retrieval**: `--hybrid` combines dense + keyword search for better recall 3. **Enable reranking**: `--rerank` improves precision for complex queries 4. **Name collections**: Organize by project or topic 5. **Use config files**: For reproducible setups 6. **Check verbose output**: Debug retrieval issues 7. **Profile performance**: Use `--profile` to identify bottlenecks 8. **Evaluate regularly**: Track quality over time