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.

praisonai rag index <sources> [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:

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

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 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 <source>: N chunks per source, then Indexing complete!	0
A source stored zero chunks	! Indexed nothing from <source> (no supported files, or every file failed)	contributes to 1
A source raised	✗ Failed to index <source>: <error>	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 for the underlying failure modes (wrong embedding model name, revoked API key, exhausted quota).

query

One-shot question answering with citations.

praisonai rag query "<question>" [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:

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

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:

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

praisonai rag eval <test_file> [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:

[
  {
    "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:

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

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:

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

{
  "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:

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

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:

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.

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