CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search
npm install voyageai-cli

    
The fastest path from documents to semantic search. Chunk files, generate Voyage AI embeddings, store in MongoDB Atlas, and query with two-stage retrieval โ from the terminal, your browser, or a desktop app.
> โ ๏ธ Disclaimer: This is an independent, community-built tool โ not an official product of MongoDB, Inc. or Voyage AI. See Disclaimer for details.
---
๐ฅ๏ธ CLIvai22 commands ยท 5 chunking strategies End-to-end RAG pipeline from your terminal npm install -g voyageai-cli | ๐ Web Playgroundvai playground7 interactive tabs for embedding, comparing, searching, and benchmarking Launches in your browser | ๐ป Desktop AppStandalone Electron app Secure keychain storage, dark/light themes, MongoDB LeafyGreen design system Download from GitHub Releases |
---
- Desktop App
- Web Playground
- CLI โ Quick Start
- Install
- 5-Minute RAG Pipeline
- Project Config
- Core Workflow
- Individual Commands
- Models & Benchmarks
- Benchmarking Your Data
- Learn
- Environment & Auth
- Shell Completions
- All Commands
- Screenshots
- Requirements
- Author
- Disclaimer
- License
---
A standalone desktop application built with Electron and the MongoDB LeafyGreen design system. Everything the CLI and playground can do โ in a native app experience.

- ๐ Secure API Key Storage โ Stores your Voyage AI API key and MongoDB URI in the OS keychain (macOS Keychain, Windows Credential Vault, Linux Secret Service). No plaintext config files.
- ๐จ Dark & Light Themes โ Full theme support with automatic system detection, built on MongoDB's LeafyGreen design tokens.
- ๐ MongoDB LeafyGreen UI โ Native MongoDB look & feel with LeafyGreen components and iconography throughout.
- ๐ฑ Sidebar Navigation โ Clean, collapsible sidebar for quick access to all features: Embed, Compare, Search, Benchmark, Explore, Settings, and more.
- โก All Playground Features โ Every tab from the web playground, plus desktop-native conveniences like system tray integration.
Download the latest release for your platform from GitHub Releases:
| Platform | Download |
|----------|----------|
| macOS (Apple Silicon) | .dmg |
| macOS (Intel) | .dmg |
| Windows | .exe installer |
| Linux | .AppImage / .deb |
---
An interactive, browser-based interface for exploring Voyage AI embeddings without writing code. Ships with the CLI โ just run:
``bash`
vai playground
Your default browser opens with a full-featured UI organized into 7 tabs:
| Tab | What It Does |
|-----|-------------|
| Embed | Generate embeddings for any text, inspect vectors, adjust dimensions and models |
| Compare | Side-by-side similarity comparison of two or more texts with cosine similarity scores |
| Search | Connect to MongoDB Atlas and run vector similarity searches with filters and reranking |
| Benchmark | Compare model latency, cost, and quality across the Voyage 4 family on your own data |
| Explore | Visualize embedding spaces with dimensionality reduction (PCA/t-SNE) and clustering |
| About | Project info, links, and version details |
| Settings | Configure API keys, MongoDB URI, default model, and preferences |
The playground connects to the same backend as the CLI. Any API keys or MongoDB URIs you've configured via vai config are available automatically.
---
22 commands ยท 312 tests ยท 5 chunking strategies ยท End-to-end RAG pipeline
`bash`
npm install -g voyageai-cli
Go from a folder of documents to a searchable vector database:
`bashSet credentials
export VOYAGE_API_KEY="your-key"
export MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/"
That's it. Documents chunked, embedded with
voyage-4-large, stored in Atlas with metadata, vector index created, and searchable with reranking.$3
Stop typing
--db myapp --collection docs on every command:`bash
vai init
`Creates
.vai.json with your defaults โ model, database, collection, chunking strategy. Every command reads it automatically. CLI flags override when needed.`json
{
"model": "voyage-4-large",
"db": "myapp",
"collection": "knowledge",
"field": "embedding",
"dimensions": 1024,
"chunk": {
"strategy": "recursive",
"size": 512,
"overlap": 50
}
}
`$3
####
vai pipeline โ Chunk โ embed โ storeThe end-to-end command. Takes files or directories, chunks them, embeds in batches, stores in MongoDB Atlas.
`bash
Directory of docs
vai pipeline ./docs/ --db myapp --collection knowledge --create-indexSingle file
vai pipeline whitepaper.pdf --db myapp --collection papersPreview without API calls
vai pipeline ./docs/ --dry-runCustom chunking
vai pipeline ./docs/ --strategy markdown --chunk-size 1024 --overlap 100
`Supports:
.txt, .md, .html, .json, .jsonl, .pdf (optional pdf-parse dependency). Auto-detects markdown files for heading-aware chunking.####
vai query โ Search + rerankTwo-stage retrieval in one command: embed query โ vector search โ rerank โ results.
`bash
Search with reranking (default)
vai query "How does authentication work?" --db myapp --collection knowledgeVector search only (skip rerank)
vai query "auth setup" --no-rerankWith pre-filter
vai query "performance tuning" --filter '{"category": "guides"}' --top-k 10
`####
vai chunk โ Document chunkingStandalone chunking for when you need control over the pipeline.
`bash
Chunk a directory, output JSONL
vai chunk ./docs/ --output chunks.jsonl --statsSpecific strategy
vai chunk paper.md --strategy markdown --chunk-size 1024Preview
vai chunk ./docs/ --dry-run
`Five strategies:
fixed, sentence, paragraph, recursive (default), markdown.####
vai estimate โ Cost estimatorCompare symmetric vs. asymmetric embedding strategies before committing.
`bash
vai estimate --docs 10M --queries 100M --months 12
`Shows cost breakdown for every Voyage 4 model combination, including asymmetric retrieval (embed docs with
voyage-4-large, query with voyage-4-lite โ same quality, fraction of the cost).$3
For when you need fine-grained control:
`bash
Embed text
vai embed "What is MongoDB?" --model voyage-4-large --dimensions 512Rerank documents
vai rerank --query "database performance" \
--documents "MongoDB is fast" "PostgreSQL is relational" "Redis is cached"Compare similarity
vai similarity "MongoDB is a database" "Atlas is a cloud database"Store a single document
vai store --db myapp --collection docs --field embedding \
--text "MongoDB Atlas provides managed cloud databases"Bulk import from file
vai ingest --file corpus.jsonl --db myapp --collection docs --field embeddingVector search (raw)
vai search --query "cloud database" --db myapp --collection docsManage indexes
vai index create --db myapp --collection docs --field embedding
vai index list --db myapp --collection docs
`$3
`bash
List models with architecture and shared space info
vai models --wideShow RTEB benchmark scores
vai models --benchmarks
`#### Voyage 4 Family
| Model | Architecture | Price/1M tokens | RTEB Score | Best For |
|-------|-------------|----------------|------------|----------|
| voyage-4-large | MoE | $0.12 | 71.41 | Best quality โ first production MoE embedding model |
| voyage-4 | Dense | $0.06 | 70.07 | Balanced quality/cost |
| voyage-4-lite | Dense | $0.02 | 68.10 | High-volume, budget |
| voyage-4-nano | Dense | Free (open-weight) | โ | Local dev, edge, HuggingFace |
Shared embedding space: All Voyage 4 models produce compatible embeddings. Embed docs with
voyage-4-large, query with voyage-4-lite โ no re-vectorization needed.#### Competitive Landscape (RTEB NDCG@10)
| Model | Score |
|-------|-------|
| voyage-4-large | 71.41 |
| voyage-4 | 70.07 |
| Gemini Embedding 001 | 68.66 |
| voyage-4-lite | 68.10 |
| Cohere Embed v4 | 65.75 |
| OpenAI v3 Large | 62.57 |
Also available:
voyage-code-3 (code), voyage-finance-2 (finance), voyage-law-2 (legal), rerank-2.5 / rerank-2.5-lite.$3
Published benchmarks measure average quality across standardized datasets.
vai benchmark measures what matters for your use case:`bash
Compare model latency and cost
vai benchmark embed --models voyage-4-large,voyage-4,voyage-4-lite --rounds 5Test asymmetric retrieval on your data
vai benchmark asymmetric --file your-corpus.txt --query "your actual query"Validate shared embedding space
vai benchmark spaceCompare quantization tradeoffs
vai benchmark quantization --model voyage-4-large --dtypes float,int8,ubinaryProject costs at scale
vai benchmark cost --tokens 500 --volumes 100,1000,10000,100000
`$3
Interactive explanations of key concepts:
`bash
vai explain embeddings # What are vector embeddings?
vai explain moe # Mixture-of-experts architecture
vai explain shared-space # Shared embedding space & asymmetric retrieval
vai explain rteb # RTEB benchmark scores
vai explain quantization # Matryoshka dimensions & quantization
vai explain two-stage # The embed โ search โ rerank pattern
vai explain nano # voyage-4-nano open-weight model
vai explain models # How to choose the right model
`17 topics covering embeddings, reranking, vector search, RAG, and more.
$3
| Variable | Required For | Description |
|----------|-------------|-------------|
|
VOYAGE_API_KEY | All embedding/reranking | Model API key from MongoDB Atlas |
| MONGODB_URI | store, search, query, pipeline, index | MongoDB Atlas connection string |Credentials resolve in order: environment variables โ
.env file โ ~/.vai/config.json.`bash
Or use the built-in config store
echo "your-key" | vai config set api-key --stdin
vai config set mongodb-uri "mongodb+srv://..."
`$3
`bash
Bash
vai completions bash >> ~/.bashrcZsh
mkdir -p ~/.zsh/completions
vai completions zsh > ~/.zsh/completions/_vai
`Covers all 22 commands, subcommands, flags, model names, and explain topics.
$3
| Command | Description |
|---------|-------------|
|
vai init | Initialize project with .vai.json |
| vai pipeline | Chunk โ embed โ store (end-to-end) |
| vai query | Search + rerank (two-stage retrieval) |
| vai chunk | Chunk documents (5 strategies) |
| vai estimate | Cost estimator (symmetric vs asymmetric) |
| vai embed | Generate embeddings |
| vai rerank | Rerank documents by relevance |
| vai similarity | Compare text similarity |
| vai store | Embed and store single documents |
| vai ingest | Bulk import with progress |
| vai search | Vector similarity search |
| vai index | Manage Atlas Vector Search indexes |
| vai models | List models, benchmarks, architecture |
| vai benchmark | 8 subcommands for model comparison |
| vai explain | 17 interactive concept explainers |
| vai config | Manage persistent configuration |
| vai ping | Test API and MongoDB connectivity |
| vai playground | Interactive web playground |
| vai demo | Guided walkthrough |
| vai completions | Shell completion scripts |
| vai about | About this tool |
| vai version` | Print version |---
---
- Node.js 18+
- MongoDB Atlas account (free tier works)
- Voyage AI model API key (created in Atlas)
Built by Michael Lynn, Principal Staff Developer Advocate at MongoDB.
This is a community tool and is not affiliated with, endorsed by, or supported by MongoDB, Inc. or Voyage AI. All trademarks belong to their respective owners.
For official documentation and support:
- MongoDB: mongodb.com | Atlas | Support
- Voyage AI: MongoDB Voyage AI Docs
MIT ยฉ Michael Lynn