weave-cli

Weave CLI

A fast, AI-powered command-line tool for managing Weaviate vector databases. Built in Go for performance and ease of use.

Quick Start

Installation

git clone https://github.com/maximilien/weave-cli.git
cd weave-cli
./build.sh
# Binary available at bin/weave

Setup (Interactive - Recommended)

# Interactive configuration - fastest way to get started
weave config create --env

# Follow prompts to enter:
# - WEAVIATE_URL
# - WEAVIATE_API_KEY
# - OPENAI_API_KEY

# Verify setup
weave health check

Supabase Setup (EXPERIMENTAL)

⚠️ EXPERIMENTAL: Supabase support is currently experimental and under active development. Some features may not work as expected. Please report issues at https://github.com/maximilien/weave-cli/issues

To use Supabase as your vector database:

# Set Supabase configuration
export SUPABASE_DATABASE_URL="postgresql://postgres:[password]@db.[project-ref].supabase.co:5432/postgres"
export SUPABASE_DATABASE_KEY="your-supabase-anon-key"

# Configure weave to use Supabase
weave config create --database-type supabase

# Verify Supabase connection
weave health check

Important Notes:

1. IPv6 Requirement: Supabase database endpoints are IPv6-only. If your network doesn't support IPv6, use the connection pooler instead:

   # Get pooler URL from: Project Settings → Database → Connection Pooling
   export SUPABASE_DATABASE_URL="postgresql://postgres.[project].[string]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres"
   

2. pgvector Extension: Ensure your Supabase project has pgvector enabled:

   CREATE EXTENSION IF NOT EXISTS vector;
   

Basic Usage

# List collections
weave cols ls

# List collections from specific database types
weave cols ls --weaviate    # Weaviate only
weave cols ls --supabase    # Supabase only
weave cols ls --mock        # Mock database only
weave cols ls --all         # All configured databases

# Create a collection
weave cols create MyCollection --text

# Add documents
weave docs create MyCollection document.txt
weave docs create MyCollection document.pdf

# Search with natural language
weave cols q MyCollection "search query"

# AI-powered REPL mode
weave
> show me all my collections
> create TestDocs collection
> add README.md to TestDocs

# List available embeddings
weave embeddings list
weave emb ls --verbose

# Create collection with specific embedding (used as default for all documents)
weave cols create MyCollection --embedding text-embedding-3-small
weave cols create MyCollection -e text-embedding-ada-002

Key Features

• 🤖 AI-Powered - Natural language interface with GPT-4o multi-agent system
• ⚡ Fast & Easy - Written in Go with simple CLI and interactive REPL with real-time progress feedback
• 🌐 Flexible - Weaviate Cloud, local instances, or built-in mock database
• 🔌 Extensible - Vector database abstraction layer supporting multiple backends (Supabase PGVector implemented, Milvus planned)
• 📦 Batch Processing - Parallel processing of entire directories
• 📄 PDF Support - Intelligent text extraction and image processing
• 🔍 Semantic Search - Vector-based similarity search with natural language
• 📊 Embeddings - List and explore available embedding models
• ⏱️ Configurable Timeouts - Default 10s timeout, adjustable per command

Documentation

Core Documentation

• 📖 User Guide - Complete feature documentation
• 📋 Changelog - Version history and updates
• 🗂️ VDB Support Matrix - Database feature comparison

Guides

• 🤖 AI Agents - Natural language query system
• 📦 Batch Processing - Directory processing guide
• 📚 Vector DB Abstraction - Multi-database support architecture
• 🎬 Demos - Video demos and tutorials

Database-Specific

• Supabase Documentation - Supabase integration guide
• Weaviate Documentation - Weaviate integration status

Advanced Usage

Configuration Options

Auto-Configuration

Weave CLI automatically detects missing configuration:

# Try any command - you'll get prompted to configure interactively
weave cols ls

# Or install weave-mcp for REPL mode
weave config update --weave-mcp

Configuration Precedence (highest to lowest):

1. Command-line flags - weave query --model gpt-4
2. Environment variables - export OPENAI_MODEL=gpt-4
3. config.yaml (optional) - For advanced customization
4. Built-in defaults

Configuration Location (precedence order):

1. Local directory (.env, config.yaml) - Project-specific configuration
2. Global directory (~/.weave-cli/.env, ~/.weave-cli/config.yaml) - User-wide configuration

# Create configuration in global directory
weave config create --env --global

# Sync local configuration to global directory
weave config sync

# View which configuration location is being used
weave config show

See the User Guide for detailed configuration options.

Vector Database Selection

Control which vector database(s) to operate on with these flags:

Important: Database selection behavior depends on your configuration:

• Single Database: If only one DB is configured, it's used automatically (no flags needed!)
• Multiple Databases:
  • Read operations (ls, show, count) use all databases by default
  • Write/delete operations use smart selection:
    1. Default Database: Uses VECTOR_DB_TYPE from .env or config
    2. Weaviate Collection Search: For --weaviate, searches all Weaviate databases for the collection
    3. Manual Selection: Use --vector-db-type (or --vdb) to specify explicitly

# Single database setup - no flags needed!
weave docs create MyCollection doc.txt       # Uses your only configured DB

# Multiple databases with VECTOR_DB_TYPE set
export VECTOR_DB_TYPE=weaviate-cloud
weave docs create MyCollection doc.txt       # Uses weaviate-cloud (default)
weave docs delete MyCollection doc123        # Uses weaviate-cloud (default)

# Override default with --vdb (short) or --vector-db-type (long)
weave docs create MyCollection doc.txt --vdb weaviate-local
weave docs create MyCollection doc.txt --vector-db-type supabase

# --weaviate tries both weaviate-cloud and weaviate-local
weave docs ls MyCollection --weaviate        # Searches both for collection
weave cols delete MyCollection --weaviate    # Searches both for collection

# Read operations work with specific or all databases
weave cols ls --weaviate                     # All Weaviate databases
weave cols ls --supabase                     # Supabase only
weave cols ls --all                          # All configured databases (default)

# Query multiple databases at once
weave cols query MyCollection "search" --weaviate --supabase

Database Selection Priority for Single-DB Operations:

1. If only one database configured → use it
2. If VECTOR_DB_TYPE set → use as default
3. If --weaviate flag used → try all Weaviate databases for the collection
4. Otherwise → show error with available options

More Examples

# Batch process documents with parallel workers
weave docs batch --directory ./docs --collection MyCollection --parallel 3

# Convert CMYK PDFs to RGB
weave docs pdf-convert document.pdf --rgb

# Text-only PDF extraction (faster, no images)
weave docs create MyCollection document.pdf --skip-all-images

# Natural language queries with AI agents
weave q "find all empty collections"
weave query "create TestDocs and add README.md" --dry-run

# Configure timeout for slow connections
weave cols ls --timeout 30s
weave health check --timeout 60s

# Create collections and documents with specific embeddings
weave cols create MyCollection --embedding text-embedding-3-small
weave docs create MyCollection document.txt --embedding text-embedding-3-small
weave docs create MyCollection report.pdf --embedding text-embedding-ada-002

Database Support

Weave CLI features a pluggable vector database abstraction layer that allows seamless switching between different vector database backends:

Currently Supported

• Weaviate Cloud (weaviate-cloud) - Production-ready cloud instances ✅
• Weaviate Local (weaviate-local) - Self-hosted Weaviate instances ✅
• Supabase PGVector (supabase) - PostgreSQL with pgvector extension ⚠️ EXPERIMENTAL
• Mock Database (mock) - Built-in testing database (no external dependencies) ✅

Planned Support

• Milvus (milvus) - Milvus vector database

See Vector DB Abstraction Documentation for details on the architecture and how to add support for new vector databases.

Abstraction Benefits

• Unified Interface - Same commands work across all database types
• Easy Migration - Switch databases without changing workflows
• Extensible - Add new vector databases with minimal code changes
• Type Safety - Compile-time validation of database operations
• Error Handling - Structured error types with context and recovery

See 📚 Vector DB Abstraction Guide for implementation details and adding new database support.

Development

# Setup development environment (installs linters, PDF tools, etc.)
./setup.sh

# Build, test, and lint
./build.sh
./test.sh
./lint.sh

See User Guide for detailed development instructions.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run ./test.sh and ./lint.sh
5. Submit a pull request

Links

Video Demos

• Full Demo (5 min) - Complete feature walkthrough
• Quick Demo (2 min) - Quick overview
• REPL Demo - AI-powered natural language interface

Interactive Demos

Run these scripts locally for hands-on demonstrations:

• Configuration Demo - Interactive setup and configuration management
• Supabase Demo - Supabase (PostgreSQL + pgvector) integration

See demos/README.md for details.

Resources

• GitHub Repository
• Documentation
• User Guide

License

MIT License - see LICENSE file for details.