ruvector/crates/ruvector-cli/docs

Ruvector CLI and MCP Server

High-performance command-line interface and Model Context Protocol (MCP) server for Ruvector vector database.

Table of Contents

• Installation
• CLI Usage
• MCP Server
• Configuration
• Examples
• Shell Completions

Installation

# Build from source
cargo build --release -p ruvector-cli

# Install binaries
cargo install --path crates/ruvector-cli

# The following binaries will be available:
# - ruvector (CLI tool)
# - ruvector-mcp (MCP server)

CLI Usage

Create a Database

# Create with specific dimensions
ruvector create --path ./my-vectors.db --dimensions 384

# Use default location (./ruvector.db)
ruvector create --dimensions 1536

Insert Vectors

# From JSON file
ruvector insert --db ./my-vectors.db --input vectors.json --format json

# From CSV file
ruvector insert --db ./my-vectors.db --input vectors.csv --format csv

# From NumPy file
ruvector insert --db ./my-vectors.db --input embeddings.npy --format npy

# Hide progress bar
ruvector insert --db ./my-vectors.db --input vectors.json --no-progress

Input Format Examples

JSON format:

[
  {
    "id": "doc1",
    "vector": [0.1, 0.2, 0.3, ...],
    "metadata": {
      "title": "Document 1",
      "category": "science"
    }
  },
  {
    "id": "doc2",
    "vector": [0.4, 0.5, 0.6, ...],
    "metadata": {
      "title": "Document 2",
      "category": "tech"
    }
  }
]

CSV format:

id,vector,metadata
doc1,"[0.1, 0.2, 0.3]","{\"title\": \"Document 1\"}"
doc2,"[0.4, 0.5, 0.6]","{\"title\": \"Document 2\"}"

Search Vectors

# Search with JSON array
ruvector search --db ./my-vectors.db --query "[0.1, 0.2, 0.3]" --top-k 10

# Search with comma-separated values
ruvector search --db ./my-vectors.db --query "0.1, 0.2, 0.3" -k 5

# Show full vectors in results
ruvector search --db ./my-vectors.db --query "[0.1, 0.2, 0.3]" --show-vectors

Database Info

# Show database statistics
ruvector info --db ./my-vectors.db

Output example:

Database Statistics
  Vectors: 10000
  Dimensions: 384
  Distance Metric: Cosine

HNSW Configuration:
  M: 32
  ef_construction: 200
  ef_search: 100

Benchmark Performance

# Run 1000 queries
ruvector benchmark --db ./my-vectors.db --queries 1000

# Custom number of queries
ruvector benchmark --db ./my-vectors.db -n 5000

Output example:

Running benchmark...
  Queries: 1000
  Dimensions: 384

Benchmark Results:
  Total time: 2.45s
  Queries per second: 408
  Average latency: 2.45ms

Export Database

# Export to JSON
ruvector export --db ./my-vectors.db --output backup.json --format json

# Export to CSV
ruvector export --db ./my-vectors.db --output backup.csv --format csv

Import from Other Databases

# Import from FAISS (coming soon)
ruvector import --db ./my-vectors.db --source faiss --source-path index.faiss

# Import from Pinecone (coming soon)
ruvector import --db ./my-vectors.db --source pinecone --source-path config.json

Global Options

# Use custom config file
ruvector --config ./custom-config.toml info --db ./my-vectors.db

# Enable debug mode
ruvector --debug search --db ./my-vectors.db --query "[0.1, 0.2, 0.3]"

# Disable colors
ruvector --no-color info --db ./my-vectors.db

MCP Server

The Ruvector MCP server provides programmatic access via the Model Context Protocol.

Start Server

# STDIO transport (for local communication)
ruvector-mcp --transport stdio

# SSE transport (for HTTP streaming)
ruvector-mcp --transport sse --host 127.0.0.1 --port 3000

# With custom config
ruvector-mcp --config ./mcp-config.toml --transport sse

# Debug mode
ruvector-mcp --debug --transport stdio

MCP Tools

The server exposes the following tools:

1. vector_db_create

Create a new vector database.

Parameters:

• path (string, required): Database file path
• dimensions (integer, required): Vector dimensions
• distance_metric (string, optional): Distance metric (euclidean, cosine, dotproduct, manhattan)

Example:

{
  "name": "vector_db_create",
  "arguments": {
    "path": "./my-db.db",
    "dimensions": 384,
    "distance_metric": "cosine"
  }
}

2. vector_db_insert

Insert vectors into database.

Parameters:

• db_path (string, required): Database path
• vectors (array, required): Array of vector objects

Example:

{
  "name": "vector_db_insert",
  "arguments": {
    "db_path": "./my-db.db",
    "vectors": [
      {
        "id": "vec1",
        "vector": [0.1, 0.2, 0.3],
        "metadata": {"label": "test"}
      }
    ]
  }
}

3. vector_db_search

Search for similar vectors.

Parameters:

• db_path (string, required): Database path
• query (array, required): Query vector
• k (integer, optional, default: 10): Number of results
• filter (object, optional): Metadata filters

Example:

{
  "name": "vector_db_search",
  "arguments": {
    "db_path": "./my-db.db",
    "query": [0.1, 0.2, 0.3],
    "k": 5
  }
}

4. vector_db_stats

Get database statistics.

Parameters:

• db_path (string, required): Database path

Example:

{
  "name": "vector_db_stats",
  "arguments": {
    "db_path": "./my-db.db"
  }
}

5. vector_db_backup

Backup database to file.

Parameters:

• db_path (string, required): Database path
• backup_path (string, required): Backup file path

Example:

{
  "name": "vector_db_backup",
  "arguments": {
    "db_path": "./my-db.db",
    "backup_path": "./backup.db"
  }
}

MCP Resources

The server provides access to database resources via URIs:

• database://local/default: Default database resource

MCP Prompts

Available prompt templates:

• semantic-search: Generate semantic search queries

Configuration

Ruvector can be configured via TOML files, environment variables, or CLI arguments.

Configuration File

Create a ruvector.toml file:

[database]
storage_path = "./ruvector.db"
dimensions = 384
distance_metric = "Cosine"

[database.hnsw]
m = 32
ef_construction = 200
ef_search = 100
max_elements = 10000000

[cli]
progress = true
colors = true
batch_size = 1000

[mcp]
host = "127.0.0.1"
port = 3000
cors = true

Environment Variables

export RUVECTOR_STORAGE_PATH="./my-db.db"
export RUVECTOR_DIMENSIONS=384
export RUVECTOR_DISTANCE_METRIC="cosine"
export RUVECTOR_MCP_HOST="0.0.0.0"
export RUVECTOR_MCP_PORT=8080

Configuration Precedence

1. CLI arguments (highest priority)
2. Environment variables
3. Configuration file
4. Default values (lowest priority)

Default Config Locations

Ruvector looks for config files in these locations:

1. ./ruvector.toml
2. ./.ruvector.toml
3. ~/.config/ruvector/config.toml
4. /etc/ruvector/config.toml

Examples

Building a Semantic Search Engine

# 1. Create database
ruvector create --path ./search.db --dimensions 384

# 2. Generate embeddings (external script)
python generate_embeddings.py --input documents/ --output embeddings.json

# 3. Insert embeddings
ruvector insert --db ./search.db --input embeddings.json

# 4. Search
ruvector search --db ./search.db --query "[0.1, 0.2, ...]" -k 10

Batch Processing Pipeline

#!/bin/bash

DB="./vectors.db"
DIMS=768

# Create database
ruvector create --path $DB --dimensions $DIMS

# Process batches
for file in data/batch_*.json; do
  echo "Processing $file..."
  ruvector insert --db $DB --input $file --no-progress
done

# Verify
ruvector info --db $DB

# Benchmark
ruvector benchmark --db $DB --queries 1000

Using with Claude Code

# Start MCP server
ruvector-mcp --transport stdio

# Claude Code can now use vector database tools
# Example prompt: "Create a vector database and insert embeddings from my documents"

Shell Completions

Generate shell completions for better CLI experience:

# Bash
ruvector --generate-completions bash > ~/.local/share/bash-completion/completions/ruvector

# Zsh
ruvector --generate-completions zsh > ~/.zsh/completions/_ruvector

# Fish
ruvector --generate-completions fish > ~/.config/fish/completions/ruvector.fish

Error Handling

Ruvector provides helpful error messages:

# Missing required argument
$ ruvector create
Error: Missing required argument: --dimensions

# Invalid vector dimensions
$ ruvector insert --db test.db --input vectors.json
Error: Vector dimension mismatch. Expected: 384, Got: 768
Suggestion: Ensure all vectors have the correct dimensionality

# Database not found
$ ruvector info --db nonexistent.db
Error: Failed to open database: No such file or directory
Suggestion: Create the database first with: ruvector create --path nonexistent.db --dimensions <dims>

# Use --debug for full stack traces
$ ruvector --debug info --db nonexistent.db

Performance Tips

1. Batch Inserts: Insert vectors in batches for better performance
2. HNSW Tuning: Adjust ef_construction and ef_search based on your accuracy/speed requirements
3. Quantization: Enable quantization for memory-constrained environments
4. Dimensions: Use appropriate dimensions for your use case (384 for smaller models, 1536 for larger)
5. Distance Metric: Choose based on your embeddings:
   • Cosine: Normalized embeddings (most common)
   • Euclidean: Absolute distances
   • Dot Product: When magnitude matters

Troubleshooting

Build Issues

# Ensure Rust is up to date
rustup update

# Clean build
cargo clean && cargo build --release -p ruvector-cli

Runtime Issues

# Enable debug logging
RUST_LOG=debug ruvector info --db test.db

# Check database integrity
ruvector info --db test.db

# Backup before operations
cp test.db test.db.backup

Contributing

See the main Ruvector repository for contribution guidelines.

License

MIT License - see LICENSE file for details.