Skip to main content

​
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

​
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 rag serve [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 rag serve

# Serve specific collection on custom port
praisonai rag serve --collection research --port 9000

# Serve with hybrid retrieval + reranking
praisonai rag serve --hybrid --rerank

# Serve with OpenAI-compatible endpoint
praisonai rag serve --openai-compat --port 8080

# Serve on all interfaces
praisonai rag serve --host 0.0.0.0
API Endpoints:
EndpointMethodDescription
/healthGETHealth check (returns collection, hybrid, rerank status)
/rag/queryPOSTQuery with JSON body
/rag/chatPOSTStreaming chat (SSE)
/v1/chat/completionsPOSTOpenAI-compatible endpoint (with --openai-compat)
/docsGETOpenAPI 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
  
  chunking:
    strategy: 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

​
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

CodeMeaning
0Success
1Error (missing deps, config error, etc.)

​
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