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

# Retrieval CLI Commands

> Command-line interface for knowledge indexing and retrieval

## Overview

The retrieval CLI provides unified commands for indexing documents and querying knowledge bases. These commands are Agent-first and use the same retrieval pipeline as the Python SDK.

## Commands

### `praisonai index` - Index Documents

Index documents into a knowledge base for later retrieval.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Index a directory
praisonai index ./docs

# Index specific files
praisonai index paper.pdf report.txt

# Index with custom collection name
praisonai index ./data --collection research

# Index with verbose output
praisonai index ./docs --verbose
```

#### Options

| Option             | Description                    | Default   |
| ------------------ | ------------------------------ | --------- |
| `--collection, -c` | Collection/knowledge base name | `default` |
| `--config, -f`     | Config file path (YAML)        | None      |
| `--verbose, -v`    | Verbose output                 | False     |
| `--profile`        | Enable performance profiling   | False     |
| `--profile-out`    | Save profile to JSON file      | None      |
| `--profile-top`    | Top N items in profile         | 20        |

### `praisonai query` - Query with Answer and Citations

Query the knowledge base and get a structured answer with citations.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Basic query
praisonai query "What are the main findings?"

# Query specific collection
praisonai query "Summarize the document" --collection research

# Query with more results
praisonai query "Key points?" --top-k 10

# Query without citations
praisonai query "Summary?" --no-citations

# Query with hybrid retrieval and reranking
praisonai query "What is the conclusion?" --hybrid --rerank
```

#### Options

| Option                       | Description                            | Default   |
| ---------------------------- | -------------------------------------- | --------- |
| `--collection, -c`           | Collection to query                    | `default` |
| `--top-k, -k`                | Number of results to retrieve          | 5         |
| `--min-score`                | Minimum relevance score (0.0-1.0)      | 0.0       |
| `--hybrid`                   | Use hybrid retrieval (dense + keyword) | False     |
| `--rerank`                   | Enable reranking of results            | False     |
| `--citations/--no-citations` | Include citations                      | True      |
| `--citations-mode`           | Citations mode: append, inline, hidden | append    |
| `--max-context-tokens`       | Maximum context tokens                 | 4000      |
| `--config, -f`               | Config file path                       | None      |
| `--verbose, -v`              | Verbose output                         | False     |
| `--profile`                  | Enable performance profiling           | False     |

### `praisonai search` - Dual-Mode Search

`praisonai search` picks its mode from the flags you pass:

* **Plain query → web search** (OpenAI-style). No LLM synthesis; raw results.
* **Query + any KB flag (`--collection`/`-c`, `--top-k`/`-k`, `--hybrid`) → knowledge-base search.** Runs against the indexed collection with no LLM synthesis.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Web search — no KB flags, no LLM synthesis
praisonai search "capital of France"

# KB search — any of --collection / -c / --top-k / -k / --hybrid switches to retrieval
praisonai search "main findings" --collection research --top-k 10

# --collection=value syntax also works
praisonai search "main findings" --collection=research

# Hybrid KB search
praisonai search "key concepts" --hybrid
```

For LLM-synthesised answers with citations, use `praisonai query` (above). `praisonai search` never calls the LLM — it returns raw web hits or raw retrieval hits depending on the flags.

#### Options — KB-Retrieval Mode

Passing **any** of `--collection`, `-c`, `--top-k`, `-k`, or `--hybrid` switches `praisonai search` into KB-retrieval mode. The `--flag value` and `--flag=value` forms are both accepted.

| Option             | Description                   | Default   |
| ------------------ | ----------------------------- | --------- |
| `--collection, -c` | Collection to search          | `default` |
| `--top-k, -k`      | Number of results to retrieve | 5         |
| `--hybrid`         | Use hybrid retrieval          | False     |
| `--config, -f`     | Config file path              | None      |
| `--verbose, -v`    | Verbose output                | False     |

#### Options — Web-Search Mode

With no KB-retrieval flag, `praisonai search` falls back to a web search (the historical default). Only `--max-results` / `-n` is honoured; the KB flags are unavailable in this mode.

| Option              | Description            | Default |
| ------------------- | ---------------------- | ------- |
| `--max-results, -n` | Max web-search results | 5       |

## Examples

### Complete Workflow

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 1. Index your documents
praisonai index ./company_docs --collection company

# 2. Query with citations
praisonai query "What is our vacation policy?" --collection company

# 3. Search for specific terms
praisonai search "remote work" --collection company --top-k 10
```

### Using Config Files

Create a config file `retrieval.yaml`:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
knowledge:
  vector_store:
    provider: chroma
    config:
      collection_name: my_docs
      path: .praison/knowledge

retrieval:
  top_k: 10
  rerank: true
  max_context_tokens: 8000
```

Use with commands:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai index ./docs --config retrieval.yaml
praisonai query "Summary?" --config retrieval.yaml
```

### Performance Profiling

Profile indexing and query performance:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Profile indexing
praisonai index ./large_corpus --profile --profile-out index_profile.json

# Profile query
praisonai query "Complex question" --profile --profile-out query_profile.json

# View profile results
cat query_profile.json
```

### Verbose Mode

Get detailed output for debugging:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai query "What is the answer?" --verbose
```

Output includes:

* Collection being queried
* Retrieval strategy used
* Number of sources found
* Relevance scores
* Elapsed time

## Environment Variables

| Variable            | Description                                  |
| ------------------- | -------------------------------------------- |
| `OPENAI_API_KEY`    | OpenAI API key for embeddings and generation |
| `ANTHROPIC_API_KEY` | Anthropic API key (if using Claude)          |

## Comparison with Legacy Commands

The unified retrieval commands replace the separate `knowledge` and `rag` command families:

| Legacy                       | New Unified                                                                                                                                     |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `praisonai knowledge add`    | `praisonai index`                                                                                                                               |
| `praisonai rag query`        | `praisonai query`                                                                                                                               |
| `praisonai knowledge search` | `praisonai search "Q" --collection C` (a KB flag is required to reach the retrieval path — a bare `praisonai search "Q"` now runs a web search) |

The legacy commands are still available but marked as deprecated. Use the new unified commands for all new projects.

## Next Steps

* [Agent Retrieval (Python)](/docs/features/retrieval) - Use retrieval in Python code
* [Knowledge Concepts](/docs/concepts/knowledge) - Learn about knowledge bases
* [CLI Reference](/docs/cli) - Full CLI documentation