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.

---

Three Ways to Use It

🖥️ CLI vai 22 commands · 5 chunking strategies End-to-end RAG pipeline from your terminal npm install -g voyageai-cli

🌐 Web Playground vai playground 7 interactive tabs for embedding, comparing, searching, and benchmarking Launches in your browser

💻 Desktop App Standalone Electron app Secure keychain storage, dark/light themes, MongoDB LeafyGreen design system Download from GitHub Releases

---

Table of Contents

- 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

---

Desktop App

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.


$3

- 🔐 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.

$3

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 |

---

Web Playground

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.

---

CLI — Quick Start

22 commands · 312 tests · 5 chunking strategies · End-to-end RAG pipeline

$3

`bash
npm install -g voyageai-cli
`

$3

Go from a folder of documents to a searchable vector database:

`bash


Set credentials

export VOYAGE_API_KEY="your-key"
export MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/"

Initialize project

vai init --yes

Chunk → embed → store (one command)

vai pipeline ./docs/ --db myapp --collection knowledge --create-index

Search with two-stage retrieval

vai query "How do I configure replica sets?" --db myapp --collection knowledge
`

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 → store

The 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-index

Single file

vai pipeline whitepaper.pdf --db myapp --collection papers

Preview without API calls

vai pipeline ./docs/ --dry-run

Custom 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 + rerank

Two-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 knowledge

Vector search only (skip rerank)

vai query "auth setup" --no-rerank

With pre-filter

vai query "performance tuning" --filter '{"category": "guides"}' --top-k 10
`

#### vai chunk — Document chunking

Standalone chunking for when you need control over the pipeline.

`bash


Chunk a directory, output JSONL

vai chunk ./docs/ --output chunks.jsonl --stats

Specific strategy

vai chunk paper.md --strategy markdown --chunk-size 1024

Preview

vai chunk ./docs/ --dry-run
`

Five strategies: fixed, sentence, paragraph, recursive (default), markdown.

#### vai estimate — Cost estimator

Compare 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 512

Rerank 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 embedding

Vector search (raw)

vai search --query "cloud database" --db myapp --collection docs

Manage 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 --wide

Show 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 5

Test asymmetric retrieval on your data

vai benchmark asymmetric --file your-corpus.txt --query "your actual query"

Validate shared embedding space

vai benchmark space

Compare quantization tradeoffs

vai benchmark quantization --model voyage-4-large --dtypes float,int8,ubinary

Project 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 >> ~/.bashrc

Zsh

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 |

---

Screenshots

$3

!Vai - Embed Tab (Dark)

$3

!Vai - Settings (Dark)

$3

!Vai - Embed Tab (Light)

$3

!Vai - Search Tab

$3

!Vai - Benchmark Tab

---

Requirements

- Node.js 18+
- MongoDB Atlas account (free tier works)
- Voyage AI model API key (created in Atlas)

Author

Built by Michael Lynn, Principal Staff Developer Advocate at MongoDB.

Disclaimer

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

License

MIT © Michael Lynn