QMD Documentation

Complete documentation for QMD (Quick Markdown Search) features and commands.

Table of Contents

• Installation - How to install QMD
• Configuration - Unified config system (CLI > Env > File > Defaults)
• Getting Started - Quick start guide
• Commands - Complete command reference
• Project Setup - Setting up project-local indexes
• Index Management - Managing collections and indexes
• Architecture - Index location priority and design

Installation

Prerequisites

QMD requires Bun runtime:

# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

Install QMD

Option 1: Install Globally from Source

# Clone the repository
git clone https://github.com/ddebowczyk/qmd.git
cd qmd

# Install dependencies
bun install

# Link globally (creates 'qmd' command)
bun link

# Verify installation
qmd doctor

Option 2: Run from Source

# Clone and install dependencies
git clone https://github.com/ddebowczyk/qmd.git
cd qmd
bun install

# Run directly
bun qmd.ts init
bun qmd.ts add .
bun qmd.ts search "query"

Optional: Ollama for Embeddings

For vector search (qmd embed, qmd vsearch, qmd query), install Ollama:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull required models
ollama pull nomic-embed-text    # For embeddings
ollama pull qwen3-reranker      # For reranking (hybrid search)

Verify Installation

# Check system health
qmd doctor

# Initialize a project
qmd init

# Run your first search
qmd add .
qmd search "markdown"

Quick Reference

Essential Commands

# Initialize project
qmd init                    # Create .qmd/ directory
qmd init --with-index       # Init + index files
qmd doctor                  # Check system health

# Indexing
qmd add .                   # Index current directory
qmd update                  # Re-index all collections
qmd update <id>             # Re-index specific collection
qmd embed                   # Generate embeddings

# Searching
qmd search "query"          # Full-text search (BM25)
qmd vsearch "query"         # Vector similarity search
qmd query "query"           # Hybrid search (best quality)

# Information
qmd status                  # Show collections and stats
qmd get <path>              # Get document by path

Configuration

QMD uses a unified configuration system with clear precedence:

Priority: CLI flags > Environment variables > Config file > Defaults

Config File (.qmd/config.json)

Create a config file for project-specific settings:

# Create with defaults
qmd init --config

# Or create manually
cat > .qmd/config.json <<'EOF'
{
  "embedModel": "nomic-embed-text",
  "rerankModel": "qwen3-reranker:0.6b-q8_0",
  "defaultGlob": "**/*.md",
  "excludeDirs": ["node_modules", ".git", "dist", "build", ".cache"],
  "ollamaUrl": "http://localhost:11434"
}
EOF

Commit this file to share settings with your team.

Environment Variables

Quick overrides for machine-specific settings:

# Model configuration
export QMD_EMBED_MODEL=custom-model
export QMD_RERANK_MODEL=custom-reranker
export OLLAMA_URL=http://remote:11434

# Infrastructure
export QMD_CACHE_DIR=/custom/cache  # Cache location override

# Standard
export NO_COLOR=1  # Disable terminal colors

CLI Flags

Override any setting at runtime:

qmd embed --embed-model custom-model
qmd vsearch "query" --embed-model nomic-embed-text
qmd query "query" --rerank-model qwen3-reranker

Example: Team Configuration

# 1. Create project config (commit to git)
qmd init --config

# 2. Team members clone repo (config is shared)
git clone your-repo
cd your-repo

# 3. Override locally if needed
export QMD_EMBED_MODEL=faster-model  # Personal preference
export OLLAMA_URL=http://localhost:11434  # Local Ollama

# 4. Or override per-command
qmd embed --embed-model production-model

Core Concepts

Project-Local Indexes

QMD uses a .qmd/ directory (like .git/) for project-local indexes:

myproject/
├── .qmd/
│   ├── default.sqlite      # Index database
│   ├── .gitignore          # Ignores *.sqlite files
│   └── config.json         # Optional config
├── docs/
│   └── readme.md
└── src/
    └── index.ts

Index Location Priority

QMD searches for indexes in this order:

1. .qmd/ directory - Project-local (walks up tree)
2. QMD_CACHE_DIR - Environment variable override
3. ~/.cache/qmd/ - Global default

Collections

A collection is a set of indexed files from one directory with one glob pattern:

qmd add .                   # Creates collection: (pwd, **/*.md)
qmd add "docs/**/*.md"      # Creates collection: (pwd, docs/**/*.md)

Features

✅ Project Initialization (qmd init)

• Zero-config setup for project-local indexes
• Automatic .gitignore generation
• Optional configuration file
• Immediate indexing with --with-index

✅ Health Diagnostics (qmd doctor)

• Check project configuration
• Validate dependencies (Bun, sqlite-vec)
• Test services (Ollama)
• Examine index health
• Auto-fix capability

✅ Smart Index Location

• Auto-detects .qmd/ directory
• Works from subdirectories
• Environment variable support
• Global fallback

✅ Collection Updates (qmd update)

• Re-index all collections
• Update specific collection by ID
• No need to cd into directories
• Detailed statistics

✅ CI/CD Integration

• GitHub Actions workflow
• Multi-platform testing
• Code coverage with Codecov
• Type checking and build verification

Examples

Single Project Workflow

# Setup
cd myproject
qmd init --with-index

# Work in subdirectories
cd docs
qmd search "architecture"   # Finds .qmd/ in parent

# Update after changes
git pull
qmd update                  # Refresh index

Multi-Project Workflow

# Index multiple projects
cd ~/work/project1 && qmd add .
cd ~/work/project2 && qmd add .
cd ~/work/project3 && qmd add .

# View all
qmd status

# Update all at once
qmd update

Environment Variable Override

# Custom cache location
export QMD_CACHE_DIR=/mnt/ssd/qmd-indexes
qmd add .                   # Uses custom location

# Or with direnv (.envrc)
echo 'export QMD_CACHE_DIR=.qmd' >> .envrc
direnv allow

Next Steps

• Read Getting Started for detailed setup
• See Commands for complete command reference
• Check Project Setup for best practices

Support

• GitHub Issues: https://github.com/ddebowczyk/qmd/issues
• Architecture: See ARCHITECTURE.md
• Claude Guide: See CLAUDE.md