CLI Development Guide

This document provides comprehensive reference for developing with the QDrant Loader command-line interface (CLI) and MCP server. All commands, options, and examples are verified against the actual implementation.

📋 Table of Contents

Main CLI Commands
MCP Server CLI
Configuration
Exit Codes
Development Patterns
Database Migrations
Testing

🚀 Main CLI Commands

The QDrant Loader provides a focused set of commands for data ingestion and project management.

Command Overview

qdrant-loader [GLOBAL_OPTIONS] [COMMAND] [COMMAND_OPTIONS]

Commands:
  init         Initialize QDrant collection
  ingest       Ingest data from configured sources
  config       Display current configuration (includes project information)

Global Options:
  --log-level LEVEL    Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
  --help               Show help message
  --version            Show version information

Global Configuration Options

All commands support these configuration options:

# Workspace mode (recommended)
--workspace PATH    # Workspace directory containing config.yaml and .env

# Traditional mode (alternative)
--config PATH       # Path to configuration file
--env PATH          # Path to environment file

Note: --workspace cannot be used with --config or --env options.

`init` - Initialize Collection

Initialize QDrant collection with configured settings.

qdrant-loader [GLOBAL_OPTIONS] init [OPTIONS]
Options: --force Force reinitialization of existing collection --help Show help for this command

Examples:

# Workspace mode (recommended)
qdrant-loader init --workspace .
# Force re-initialization
qdrant-loader init --workspace . --force
# Traditional mode
qdrant-loader --config config.yaml --env .env init
# With debug logging
qdrant-loader --log-level DEBUG --workspace . init

`ingest` - Data Ingestion

Process and load data from configured sources into QDrant.

qdrant-loader [GLOBAL_OPTIONS] ingest [OPTIONS]
Options: --project ID Process specific project only --source-type TYPE Process specific source type (git, confluence, jira, localfile, publicdocs) --source NAME Process specific source name --profile Enable performance profiling (saves to profile.out) --help Show help for this command

Examples:

# Ingest all configured sources
qdrant-loader ingest --workspace .
# Ingest specific project
qdrant-loader ingest --workspace . --project my-project
# Ingest specific source type from all projects
qdrant-loader ingest --workspace . --source-type git
# Ingest specific source type from specific project
qdrant-loader ingest --workspace . --project my-project --source-type confluence
# Ingest specific source from specific project
qdrant-loader ingest --workspace . --project my-project --source-type git --source my-repo
# Enable performance profiling
qdrant-loader ingest --workspace . --profile
# With debug logging
qdrant-loader --log-level DEBUG --workspace . ingest

`config` - Configuration Display

Display current configuration in JSON format.

qdrant-loader [GLOBAL_OPTIONS] config
Options: --help Show help for this command

Examples:

# Show current configuration
qdrant-loader config --workspace .
# Traditional mode
qdrant-loader --config config.yaml --env .env config
# With debug logging to see configuration loading process
qdrant-loader --log-level DEBUG --workspace . config

`config` - Configuration and Project Information

Display current configuration including all project information and validation.

qdrant-loader [GLOBAL_OPTIONS] config
Options: --help Show help for this command

Note: Dedicated project management commands (project list, project status, project validate) are not currently available. All project information is accessible through the config command.

Examples:

# Display all configuration and project information
qdrant-loader config --workspace .
# Display configuration with debug logging
qdrant-loader --log-level DEBUG config --workspace .
# Traditional mode
qdrant-loader --config config.yaml --env .env config

Information Displayed:

Project configurations and validation status
Source configurations for each project
Environment variable validation
QDrant collection settings
LLM provider configuration

🤖 MCP Server CLI

The MCP server provides a single command for starting the Model Context Protocol server.

MCP Command Overview

mcp-qdrant-loader [OPTIONS]
Options: --log-level LEVEL Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) --config PATH Configuration file path (currently not implemented) --help Show help message --version Show version information

Basic Usage

# Start MCP server with default settings
mcp-qdrant-loader
# Start with debug logging
mcp-qdrant-loader --log-level DEBUG
# Show version
mcp-qdrant-loader --version
# Show help
mcp-qdrant-loader --help

MCP Server Configuration

The MCP server uses environment variables for configuration (not config files):

# Required
QDRANT_URL=http://localhost:6333
OPENAI_API_KEY=your-openai-api-key
# Optional
QDRANT_API_KEY=your-qdrant-cloud-api-key
QDRANT_COLLECTION_NAME=documents
MCP_LOG_LEVEL=INFO
MCP_LOG_FILE=/path/to/mcp.log
MCP_DISABLE_CONSOLE_LOGGING=true # Recommended for Cursor

Integration with AI Tools

Cursor IDE Integration

{
  "mcpServers": {
    "qdrant-loader": {
      "command": "mcp-qdrant-loader",
      "args": ["--log-level", "INFO"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OPENAI_API_KEY": "your_openai_key",
        "MCP_DISABLE_CONSOLE_LOGGING": "true"
      }
    }
  }
}

Claude Desktop Integration

{
  "mcpServers": {
    "qdrant-loader": {
      "command": "mcp-qdrant-loader",
      "args": [],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OPENAI_API_KEY": "your_openai_key",
        "QDRANT_COLLECTION_NAME": "documents"
      }
    }
  }
}

🔧 Configuration

Workspace Mode (Recommended)

The CLI uses workspace mode for better organization:

# Workspace structure
my-workspace/
├── config.yaml        # Main configuration
├── .env               # Environment variables
├── logs/              # Log files
│   └── qdrant-loader.log
├── data/              # State database
│   └── qdrant-loader.db
└── metrics/           # Performance metrics

Configuration Files

The CLI looks for configuration in this order:

Workspace mode: --workspace directory containing config.yaml and .env
Traditional mode: --config and --env files
Default: config.yaml in current directory

Environment Variables

# QDrant Connection
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your-api-key
QDRANT_COLLECTION_NAME=documents
# OpenAI API
OPENAI_API_KEY=your-openai-api-key
# State Management
STATE_DB_PATH=./state/state.db
# Source-specific credentials
GITHUB_TOKEN=your-github-token
CONFLUENCE_TOKEN=your-confluence-token
CONFLUENCE_EMAIL=your-email@company.com
JIRA_TOKEN=your-jira-token
JIRA_EMAIL=your-email@company.com

Exit Codes

Code	Meaning	Description
0	Success	Command completed successfully
1	General Error	Unspecified error occurred
2	Configuration Error	Invalid configuration or missing required settings
3	Connection Error	Failed to connect to QDrant or data sources
4	Authentication Error	Invalid credentials for data sources
5	Processing Error	Error during data processing or ingestion

🔧 Development Patterns

Automation and Scripting

Basic Automation Script

#!/bin/bash
# automation-example.sh - Basic automation pattern
set -euo pipefail
WORKSPACE_DIR="${WORKSPACE_DIR:-$(pwd)}"
LOG_LEVEL="${LOG_LEVEL:-INFO}"
# Function to log messages
log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1"; }
# Validate configuration
log "Validating configuration..."
if ! qdrant-loader config --workspace "$WORKSPACE_DIR" >/dev/null 2>&1; then
  log "ERROR: Configuration validation failed"; exit 2
fi
# Validate projects
log "Validating projects..."
if ! qdrant-loader config --workspace "$WORKSPACE_DIR"; then
  log "ERROR: Project validation failed"; exit 2
fi
# Initialize collection
log "Initializing QDrant collection..."
qdrant-loader --log-level "$LOG_LEVEL" --workspace "$WORKSPACE_DIR" init
# Run ingestion
log "Starting data ingestion..."
qdrant-loader --log-level "$LOG_LEVEL" --workspace "$WORKSPACE_DIR" ingest
# Check final status
log "Checking project status..."
qdrant-loader config --workspace "$WORKSPACE_DIR"
log "Automation completed successfully"

Project-Specific Processing

#!/bin/bash
# project-processing.sh - Process specific projects
WORKSPACE_DIR="${1:-$(pwd)}"
PROJECT_ID="${2:-}"
if [ -n "$PROJECT_ID" ]; then
  echo "Processing project: $PROJECT_ID"
  # Validate specific project
  qdrant-loader config --workspace "$WORKSPACE_DIR" --project-id "$PROJECT_ID"
  # Process specific project
  qdrant-loader ingest --workspace "$WORKSPACE_DIR" --project "$PROJECT_ID"
  # Check project status
  qdrant-loader config --workspace "$WORKSPACE_DIR" --project-id "$PROJECT_ID"
else
  echo "Processing all projects"
  # Get list of projects
  PROJECTS=$(qdrant-loader config --workspace "$WORKSPACE_DIR" --format json | jq -r '.[].project_id')
  for project in $PROJECTS; do
    echo "Processing project: $project"
    qdrant-loader ingest --workspace "$WORKSPACE_DIR" --project "$project"
  done
fi

Error Handling and Debugging

Configuration Validation

# Check configuration syntax
qdrant-loader config --workspace .
# Validate all projects
qdrant-loader config --workspace .
# Display configuration with debug output (includes project validation)
qdrant-loader --log-level DEBUG config --workspace .

Debug Commands

# Show current configuration with debug logging
qdrant-loader --log-level DEBUG --workspace . config
# List all projects with detailed output
qdrant-loader config --workspace . --format json
# Display configuration (includes all project information)
qdrant-loader config --workspace .
# Run ingestion with debug logging and profiling
qdrant-loader --log-level DEBUG --workspace . ingest --profile

🗄️ Database Migrations

QDrant Loader uses Alembic to manage SQLite schema migrations. Always run migrations through the provided wrapper script so the correct database path is resolved automatically from Settings (workspace/config/env aware).

Important: Do not run python -m alembic -c alembic.ini ... directly unless you manually export STATE_DB_PATH first. The direct command uses the fallback path in alembic.ini, which may not match your actual configured database.

Upgrade to Latest Schema

# Workspace mode (recommended)
python scripts/alembic_with_settings.py --workspace . -- upgrade head

# Non-workspace mode (uses config.yaml in current directory)
python scripts/alembic_with_settings.py -- upgrade head

# Non-workspace mode with explicit config and env files
python scripts/alembic_with_settings.py --config path/to/config.yaml --env path/to/.env -- upgrade head

Check Current Migration Revision

# Workspace mode
python scripts/alembic_with_settings.py --workspace . -- current

# Non-workspace mode
python scripts/alembic_with_settings.py -- current

How It Works

The wrapper (scripts/alembic_with_settings.py):

Loads Settings using the same mode/config/env as the app (initialize_config / initialize_config_with_workspace).
Reads the resolved database_path from settings.global_config.state_management.database_path.
Sets STATE_DB_PATH for the child Alembic process.
Runs Alembic with the correct database path.

Mode	Resolved DB Path
Workspace (`--workspace .`)	`<workspace>/data/qdrant-loader.db`
Non-workspace, config sets path directly	value from `global.state_management.database_path` in `config.yaml`
Non-workspace, config uses `${STATE_DB_PATH}`	value of `STATE_DB_PATH` env var
Non-workspace, no config/env	`./state.db` (default)

Migration Script Options

python scripts/alembic_with_settings.py [OPTIONS] -- [ALEMBIC_ARGS]

Options:
  --workspace PATH     Workspace directory containing config.yaml and optional .env
  --config PATH        Path to config.yaml (non-workspace mode)
  --env PATH           Path to .env file (non-workspace mode)
  --alembic-config     Path to alembic.ini (default: packages/qdrant-loader/alembic.ini)

🧪 Testing

CLI Testing Patterns

Configuration Testing

#!/bin/bash
# test-config.sh - Test configuration validity
test_config() {
  local workspace_dir="$1"
  echo "Testing configuration in: $workspace_dir"
  # Test configuration loading
  if qdrant-loader config --workspace "$workspace_dir" >/dev/null 2>&1; then
    echo "✅ Configuration is valid"
  else
    echo "❌ Configuration is invalid"; return 1
  fi
  # Test project validation
  if qdrant-loader config --workspace "$WORKSPACE_DIR"; then
    echo "✅ All projects are valid"
  else
    echo "❌ Project validation failed"; return 1
  fi
}
# Test multiple workspace configurations
test_config "./test-workspace-1"
test_config "./test-workspace-2"

Integration Testing

#!/bin/bash
# integration-test.sh - Full integration test
set -euo pipefail
WORKSPACE_DIR="./test-workspace"
TEST_PROJECT="test-project"
# Setup test workspace
mkdir -p "$WORKSPACE_DIR"
cp config.test.yaml "$WORKSPACE_DIR/config.yaml"
cp .env.test "$WORKSPACE_DIR/.env"
# Test initialization
echo "Testing initialization..."
qdrant-loader init --workspace "$WORKSPACE_DIR" --force
# Test ingestion
echo "Testing ingestion..."
qdrant-loader ingest --workspace "$WORKSPACE_DIR" --project "$TEST_PROJECT"
# Test project commands
echo "Testing project commands..."
qdrant-loader config --workspace "$WORKSPACE_DIR"
qdrant-loader config --workspace "$WORKSPACE_DIR" --project-id "$TEST_PROJECT"
# Cleanup
rm -rf "$WORKSPACE_DIR"
echo "✅ Integration test completed"

MCP Server Testing

#!/bin/bash
# test-mcp-server.sh - Test MCP server functionality
# Set required environment variables
export QDRANT_URL="http://localhost:6333"
export OPENAI_API_KEY="test-key"
export QDRANT_COLLECTION_NAME="test-collection"
# Test server startup
echo "Testing MCP server startup..."
timeout 5s mcp-qdrant-loader --log-level DEBUG || echo "Server started successfully"
# Test with JSON-RPC message
echo "Testing search functionality..."
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"test","limit":1}}}' | \ timeout 5s mcp-qdrant-loader 2>/dev/null || echo "Search test completed"

Core Documentation

Architecture Overview - System design and components
Configuration Reference - Configuration options
Extension Guide - How to extend functionality

User Guides

CLI Reference - Complete CLI reference
Getting Started - Quick start guide
Troubleshooting - Common issues and solutions

🆘 Getting Help

CLI Support

GitHub Issues - Report CLI bugs
GitHub Discussions - Ask CLI questions

Contributing to CLI

Contributing Guide - How to contribute
Testing Guide - Testing CLI functionality

Ready to develop with the CLI? Start with the basic commands above or check out the Architecture Overview for detailed system design information.

CLI Development Guide

📋 Table of Contents

🚀 Main CLI Commands

Command Overview

Global Configuration Options

init - Initialize Collection

ingest - Data Ingestion

config - Configuration Display

config - Configuration and Project Information

🤖 MCP Server CLI

MCP Command Overview

Basic Usage

MCP Server Configuration

Integration with AI Tools

Cursor IDE Integration

Claude Desktop Integration

🔧 Configuration

Workspace Mode (Recommended)

Configuration Files

Environment Variables

Exit Codes

🔧 Development Patterns

Automation and Scripting

Basic Automation Script

Project-Specific Processing

Error Handling and Debugging

Configuration Validation

Debug Commands

🗄️ Database Migrations

Upgrade to Latest Schema

Check Current Migration Revision

How It Works

Migration Script Options

🧪 Testing

CLI Testing Patterns

Configuration Testing

Integration Testing

MCP Server Testing

📚 Related Documentation

Core Documentation

User Guides

🆘 Getting Help

CLI Support

Contributing to CLI

`init` - Initialize Collection

`ingest` - Data Ingestion

`config` - Configuration Display

`config` - Configuration and Project Information