EdgeCraft RAG CLI

A command-line interface tool for managing EdgeCraft RAG system components including pipelines, models, knowledge bases, agents, and more.

Implementation Notes

The CLI package is organized as follows:

  • main.py: Click command groups and subcommands

  • client.py: EcragApiClient REST wrapper

  • config.py: environment-based connection config

  • quickstart.py: quick start and connectivity check helper

  • setup.py: package metadata and ecrag console entry point

Installation

Requires Python 3.8+.

Optional (non-editable install)

pip install .
ecrag --help

Usage

The CLI is organized into logical command groups for different system components.

Basic Syntax

ecrag [--host HOST] [--port PORT] [--mega-port MEGA_PORT] COMMAND [OPTIONS]

# Default top-level query uses ChatQnA (/v1/chatqna)
ecrag query "Your question"

Global Options

  • --host: Server host URL (default: http://localhost)

  • --port: Server port (default: 16010)

  • --mega-port: Mega service port (default: 16011)

Commands

Pipeline Management

# List all pipelines
ecrag pipeline list

# Create a pipeline
ecrag pipeline create --name my_pipeline --file pipeline.json

# Get pipeline details
ecrag pipeline get --name my_pipeline

# Get pipeline JSON
ecrag pipeline get-json --name my_pipeline

# Activate/Deactivate pipeline
ecrag pipeline activate --name my_pipeline
ecrag pipeline deactivate --name my_pipeline

# Delete pipeline
ecrag pipeline delete --name my_pipeline

# Get benchmark data
ecrag pipeline benchmark --name my_pipeline

# Import pipeline from file
ecrag pipeline import-pipeline --file pipeline.json

Model Management

# Load a model
ecrag model load --type LLM --id model-id --path /path/to/model --device cpu

# List all models
ecrag model list

# Get model info
ecrag model get --id model-id

# Update model
ecrag model update --id model-id --device gpu

# Delete model
ecrag model delete --id model-id

# Get available weights
ecrag model weights --id model-id

# List available models by type
ecrag model available --type LLM
ecrag model available --type embedding

Knowledge Base Management

# Create knowledge base
ecrag kb create --name my_kb --description "My knowledge base"

# List knowledge bases
ecrag kb list

# Get knowledge base details
ecrag kb get --name my_kb

# Get knowledge base JSON
ecrag kb get-json --name my_kb

# Get file map (pagination)
ecrag kb filemap --name my_kb --page 1 --size 20

# Update knowledge base
ecrag kb update --name my_kb --description "Updated" --active true

# Delete knowledge base
ecrag kb delete --name my_kb

# Add files to knowledge base
ecrag kb add-files --name my_kb --paths /path/to/file1 /path/to/file2

# Delete files from knowledge base
ecrag kb delete-files --name my_kb --paths /path/to/file1

Experience Management

# List all experiences
ecrag experience list

# Get experience
ecrag experience get --id exp-id

# Create/Update experience
ecrag experience create --id exp-id --question "What is X?" --content "Answer"

# Delete experience
ecrag experience delete --id exp-id

# Load experiences from file
ecrag experience load-file --file experiences.json

Agent Management

# List all agents
ecrag agent list

# Get agent details
ecrag agent get --name my_agent

# Get agent type configs
ecrag agent configs --type react_llm

# Create agent
ecrag agent create --name my_agent --type react_llm --pipeline pipeline-idx

# Update agent
ecrag agent update --name my_agent --active true

# Delete agent
ecrag agent delete --name my_agent

Prompt Management

# Get current prompt
ecrag prompt get

# Get tagged prompt
ecrag prompt get-tagged

# Get default prompt
ecrag prompt get-default

# Set prompt from text
ecrag prompt set --text "Your prompt text here"

# Set prompt from file
ecrag prompt set --file prompt.txt

# Reset to default prompt
ecrag prompt reset

Data Management

# Get all nodes
ecrag data nodes

# Get nodes by document
ecrag data nodes-by-doc --name document_name

# List all documents
ecrag data documents

# List all files
ecrag data files

# Get specific file
ecrag data get-file --name filename

# Upload file
ecrag data upload --name filename --path /path/to/file

Session Management

# List all sessions
ecrag session list

# Get session details
ecrag session get --id session-id

System Information

# Get system info (CPU, memory, disk, etc.)
ecrag system info

# Get available devices
ecrag system devices

Chat and Query

# Shortcut for ChatQnA
ecrag query "Your question"

# Retrieve relevant chunks
ecrag chat retrieve --query "Your question" --top-n 5

# Run RAG pipeline
ecrag chat rag --query "Your question" --top-n 5

# Run mega service (full pipeline)
ecrag chat mega --query "Your question" --top-n 5

# Check vLLM connection
ecrag chat check-vllm --server http://localhost:8086 --model "Qwen/Qwen3-8B"

Examples

Create a Knowledge Base and Add Files

# Create KB
ecrag kb create --name research_kb --description "Research papers"

# Add files
ecrag kb add-files --name research_kb --paths /data/paper1.pdf /data/paper2.pdf

Load a Model and Create Pipeline

# Load embedding model
ecrag model load --type embedding --id BAAI/bge-base-en --device cpu

# Create pipeline with the model
ecrag pipeline create --name my_pipeline --file pipeline_config.json

# Activate pipeline
ecrag pipeline activate --name my_pipeline

Query the System

# Run the default ChatQnA shortcut
ecrag query "What is RAG?"

# Equivalent explicit subcommand
ecrag chat mega --query "What is RAG?" --top-n 5

# RAG pipeline only
ecrag chat rag --query "What is RAG?" --top-n 5

# Retrieval only
ecrag chat retrieve --query "What is RAG?" --top-n 5

Configuration

The CLI reads the following environment variables (optional):

  • ECRAG_HOST: Server host (default: http://localhost)

  • ECRAG_PORT: Server port (default: 16010)

  • ECRAG_MEGA_PORT: Mega service port (default: 16011)

Error Handling

The CLI will display error messages from the API in JSON format. Network errors and other issues will be reported with descriptive error messages.

Tips

  • Use --help with any command to see detailed help:

    ecrag pipeline --help
ecrag pipeline create --help

  • Pipe JSON output to other tools:

    ecrag kb list | jq '.[]' | head -n 20

  • Use confirmation prompts for destructive operations:

    # Will ask before deleting
ecrag pipeline delete --name old_pipeline

API Reference

The CLI wraps the following API endpoints:

  • Pipelines: /v1/settings/pipelines

  • Models: /v1/settings/models

  • Knowledge Bases: /v1/knowledge

  • Experiences: /v1/experiences

  • Agents: /v1/agents

  • Prompts: /v1/chatqna/prompt

  • Data: /v1/data/*

  • Sessions: /v1/sessions

  • System: /v1/system/*

  • Chat/Query: /v1/retrieval, /v1/ragqna, /v1/chatqna

For more details, see the main API_Guide.md.

Endpoint Mapping Details

The CLI maps command groups to REST endpoints as follows:

  • pipeline: GET/POST /v1/settings/pipelines, GET/PATCH/DELETE /v1/settings/pipelines/{name}

  • model: GET/POST /v1/settings/models, GET/PATCH/DELETE /v1/settings/models/{id}

  • kb: GET/POST /v1/knowledge, GET/DELETE /v1/knowledge/{name}, PATCH /v1/knowledge/patch, POST/DELETE /v1/knowledge/{name}/files

  • experience: GET /v1/experiences, POST /v1/experience, PATCH/DELETE /v1/experiences

  • agent: GET/POST /v1/agents, GET/PATCH/DELETE /v1/agents/{name}

  • prompt: GET/POST /v1/chatqna/prompt, POST /v1/chatqna/prompt/reset

  • data: GET /v1/data/nodes, GET /v1/data/documents, GET /v1/data/files, POST /v1/data/file/{name}

  • chat: POST /v1/retrieval, POST /v1/ragqna, POST /v1/chatqna