Complete documentation for QMD (Quick Markdown Search) features and commands.
- 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
QMD requires Bun runtime:
# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash# 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# 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"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)# Check system health
qmd doctor
# Initialize a project
qmd init
# Run your first search
qmd add .
qmd search "markdown"# 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 pathQMD uses a unified configuration system with clear precedence:
Priority: CLI flags > Environment variables > Config file > Defaults
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"
}
EOFCommit this file to share settings with your team.
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 colorsOverride 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# 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-modelQMD 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
QMD searches for indexes in this order:
.qmd/directory - Project-local (walks up tree)QMD_CACHE_DIR- Environment variable override~/.cache/qmd/- Global default
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)- Zero-config setup for project-local indexes
- Automatic
.gitignoregeneration - Optional configuration file
- Immediate indexing with
--with-index
- Check project configuration
- Validate dependencies (Bun, sqlite-vec)
- Test services (Ollama)
- Examine index health
- Auto-fix capability
- Auto-detects
.qmd/directory - Works from subdirectories
- Environment variable support
- Global fallback
- Re-index all collections
- Update specific collection by ID
- No need to cd into directories
- Detailed statistics
- GitHub Actions workflow
- Multi-platform testing
- Code coverage with Codecov
- Type checking and build verification
# 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# 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# 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- Read Getting Started for detailed setup
- See Commands for complete command reference
- Check Project Setup for best practices
- GitHub Issues: https://github.com/ddebowczyk/qmd/issues
- Architecture: See ARCHITECTURE.md
- Claude Guide: See CLAUDE.md