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
• 🌐 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

• 📖 User Guide - Complete feature documentation
• 🤖 AI Agents - Natural language query system
• 📦 Batch Processing - Directory processing guide
• 📚 Vector DB Abstraction - Multi-database support architecture
• 🎬 Demos - Video demos and tutorials
• 📋 Changelog - Version history and updates

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

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

• GitHub Repository
• Full Demo (5 min)
• Quick Demo (2 min)
• REPL Demo

License

MIT License - see LICENSE file for details.