voyageai-cli 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Lynn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# voyageai-cli
+
+CLI for [Voyage AI](https://www.mongodb.com/docs/voyageai/) embeddings, reranking, and [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/atlas/atlas-vector-search/). Pure Node.js — no Python required.
+
+Generate embeddings, rerank search results, store vectors in Atlas, and run semantic search — all from the command line.
+
+## Install
+
+```bash
+npm install -g voyageai-cli
+```
+
+## Quick Start
+
+```bash
+# Set your API key (get one from MongoDB Atlas → AI Models)
+export VOYAGE_API_KEY="your-key"
+
+# Generate an embedding
+vai embed "What is MongoDB?"
+
+# List available models
+vai models
+```
+
+## Commands
+
+### `vai embed` — Generate embeddings
+
+```bash
+# Single text
+vai embed "Hello, world"
+
+# With options
+vai embed "search query" --model voyage-4-large --input-type query --dimensions 512
+
+# From a file
+vai embed --file document.txt --input-type document
+
+# Bulk from stdin (newline-delimited)
+cat texts.txt | vai embed
+
+# Raw array output
+vai embed "hello" --output-format array
+```
+
+### `vai rerank` — Rerank documents by relevance
+
+```bash
+# Inline documents
+vai rerank --query "database performance" \
+  --documents "MongoDB is fast" "Redis is cached" "SQL is relational"
+
+# From a file (JSON array or newline-delimited)
+vai rerank --query "best database" --documents-file candidates.json --top-k 3
+
+# Different model
+vai rerank --query "query" --documents "doc1" "doc2" --model rerank-2.5-lite
+```
+
+### `vai store` — Embed and insert into MongoDB Atlas
+
+Requires `MONGODB_URI` environment variable.
+
+```bash
+# Single document with metadata
+vai store --db myapp --collection docs --field embedding \
+  --text "MongoDB Atlas is a cloud database" \
+  --metadata '{"source": "docs", "category": "product"}'
+
+# From a file
+vai store --db myapp --collection docs --field embedding \
+  --file article.txt
+
+# Batch from JSONL (one {"text": "...", "metadata": {...}} per line)
+vai store --db myapp --collection docs --field embedding \
+  --file documents.jsonl
+```
+
+### `vai search` — Vector similarity search
+
+Requires `MONGODB_URI` environment variable.
+
+```bash
+# Basic search
+vai search --query "cloud database" \
+  --db myapp --collection docs \
+  --index vector_index --field embedding
+
+# With pre-filter and limit
+vai search --query "performance tuning" \
+  --db myapp --collection docs \
+  --index vector_index --field embedding \
+  --filter '{"category": "guides"}' --limit 5
+```
+
+### `vai index` — Manage Atlas Vector Search indexes
+
+Requires `MONGODB_URI` environment variable.
+
+```bash
+# Create an index
+vai index create --db myapp --collection docs --field embedding \
+  --dimensions 1024 --similarity cosine --index-name my_index
+
+# List indexes
+vai index list --db myapp --collection docs
+
+# Delete an index
+vai index delete --db myapp --collection docs --index-name my_index
+```
+
+### `vai models` — List available models
+
+```bash
+# All models
+vai models
+
+# Filter by type
+vai models --type embedding
+vai models --type reranking
+```
+
+## Full Pipeline Example
+
+```bash
+export VOYAGE_API_KEY="your-key"
+export MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/"
+
+# 1. Store documents with embeddings
+vai store --db myapp --collection articles --field embedding \
+  --text "MongoDB Atlas provides a fully managed cloud database" \
+  --metadata '{"title": "Atlas Overview"}'
+
+vai store --db myapp --collection articles --field embedding \
+  --text "Vector search enables semantic similarity matching" \
+  --metadata '{"title": "Vector Search Guide"}'
+
+# 2. Create a vector search index
+vai index create --db myapp --collection articles --field embedding \
+  --dimensions 1024 --similarity cosine --index-name article_search
+
+# 3. Search (wait ~60s for index to build on small collections)
+vai search --query "how does cloud database work" \
+  --db myapp --collection articles --index article_search --field embedding
+
+# 4. Rerank for precision
+vai rerank --query "how does cloud database work" \
+  --documents "MongoDB Atlas provides a fully managed cloud database" \
+    "Vector search enables semantic similarity matching"
+```
+
+## Environment Variables
+
+| Variable | Required For | Description |
+|----------|-------------|-------------|
+| `VOYAGE_API_KEY` | embed, rerank, store, search | [Model API key](https://www.mongodb.com/docs/voyageai/management/api-keys/) from MongoDB Atlas |
+| `MONGODB_URI` | store, search, index | MongoDB Atlas connection string |
+
+## Global Flags
+
+All commands support:
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Machine-readable JSON output |
+| `--quiet` | Suppress non-essential output |
+
+## Models
+
+| Model | Type | Dimensions | Price/1M tokens | Best For |
+|-------|------|-----------|----------------|----------|
+| voyage-4-large | embedding | 1024 (default), 256-2048 | $0.12 | Best quality |
+| voyage-4 | embedding | 1024 (default), 256-2048 | $0.06 | Balanced |
+| voyage-4-lite | embedding | 1024 (default), 256-2048 | $0.02 | Lowest cost |
+| voyage-code-3 | embedding | 1024 (default), 256-2048 | $0.18 | Code |
+| voyage-finance-2 | embedding | 1024 | $0.12 | Finance |
+| voyage-law-2 | embedding | 1024 | $0.12 | Legal |
+| voyage-multimodal-3.5 | embedding | 1024 (default), 256-2048 | $0.12 + pixels | Text + images |
+| rerank-2.5 | reranking | — | $0.05 | Best reranking |
+| rerank-2.5-lite | reranking | — | $0.02 | Fast reranking |
+
+Free tier: 200M tokens for most models. All Voyage 4 series models share the same embedding space.
+
+## Requirements
+
+- Node.js 18+
+- A [MongoDB Atlas](https://www.mongodb.com/atlas) account (free tier works)
+- A [Voyage AI model API key](https://www.mongodb.com/docs/voyageai/management/api-keys/) (created in Atlas)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "voyageai-cli",
+  "version": "1.1.0",
+  "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
+  "bin": {
+    "vai": "./src/cli.js"
+  },
+  "keywords": [
+    "voyage-ai",
+    "voyageai",
+    "embeddings",
+    "vector-search",
+    "reranking",
+    "mongodb",
+    "atlas",
+    "semantic-search",
+    "rag",
+    "cli"
+  ],
+  "author": "Michael Lynn",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mrlynn/voyageai-cli"
+  },
+  "homepage": "https://github.com/mrlynn/voyageai-cli#readme",
+  "bugs": {
+    "url": "https://github.com/mrlynn/voyageai-cli/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "mongodb": "^6.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+'use strict';
+
+const { program } = require('commander');
+const { registerEmbed } = require('./commands/embed');
+const { registerRerank } = require('./commands/rerank');
+const { registerStore } = require('./commands/store');
+const { registerSearch } = require('./commands/search');
+const { registerIndex } = require('./commands/index');
+const { registerModels } = require('./commands/models');
+
+program
+  .name('vai')
+  .description('Voyage AI embeddings, reranking, and Atlas Vector Search CLI')
+  .version('1.0.0');
+
+registerEmbed(program);
+registerRerank(program);
+registerStore(program);
+registerSearch(program);
+registerIndex(program);
+registerModels(program);
+
+program.parse();

package/src/commands/embed.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const { DEFAULT_EMBED_MODEL } = require('../lib/catalog');
+const { generateEmbeddings } = require('../lib/api');
+const { resolveTextInput } = require('../lib/input');
+
+/**
+ * Register the embed command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerEmbed(program) {
+  program
+    .command('embed [text]')
+    .description('Generate embeddings for text')
+    .option('-m, --model <model>', 'Embedding model', DEFAULT_EMBED_MODEL)
+    .option('-t, --input-type <type>', 'Input type: query or document')
+    .option('-d, --dimensions <n>', 'Output dimensions', (v) => parseInt(v, 10))
+    .option('-f, --file <path>', 'Read text from file')
+    .option('-o, --output-format <format>', 'Output format: json or array', 'json')
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action(async (text, opts) => {
+      try {
+        const texts = await resolveTextInput(text, opts.file);
+
+        const result = await generateEmbeddings(texts, {
+          model: opts.model,
+          inputType: opts.inputType,
+          dimensions: opts.dimensions,
+        });
+
+        if (opts.outputFormat === 'array') {
+          if (result.data.length === 1) {
+            console.log(JSON.stringify(result.data[0].embedding));
+          } else {
+            console.log(JSON.stringify(result.data.map(d => d.embedding)));
+          }
+          return;
+        }
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+
+        // Friendly output
+        if (!opts.quiet) {
+          console.log(`Model: ${result.model}`);
+          console.log(`Texts: ${result.data.length}`);
+          if (result.usage) {
+            console.log(`Tokens: ${result.usage.total_tokens}`);
+          }
+          console.log(`Dimensions: ${result.data[0]?.embedding?.length || 'N/A'}`);
+          console.log('');
+        }
+
+        for (const item of result.data) {
+          const preview = item.embedding.slice(0, 5).map(v => v.toFixed(6)).join(', ');
+          console.log(`[${item.index}] [${preview}, ...] (${item.embedding.length} dims)`);
+        }
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = { registerEmbed };

package/src/commands/index.js

@@ -0,0 +1,156 @@
+'use strict';
+
+const { DEFAULT_DIMENSIONS } = require('../lib/catalog');
+const { getMongoCollection } = require('../lib/mongo');
+
+/**
+ * Register the index command (with create, list, delete subcommands) on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerIndex(program) {
+  const indexCmd = program
+    .command('index')
+    .description('Manage Atlas Vector Search indexes');
+
+  // ── index create ──
+  indexCmd
+    .command('create')
+    .description('Create a vector search index')
+    .requiredOption('--db <database>', 'Database name')
+    .requiredOption('--collection <name>', 'Collection name')
+    .requiredOption('--field <name>', 'Embedding field name')
+    .option('-d, --dimensions <n>', 'Vector dimensions', (v) => parseInt(v, 10), DEFAULT_DIMENSIONS)
+    .option('-s, --similarity <type>', 'Similarity function: cosine, dotProduct, euclidean', 'cosine')
+    .option('-n, --index-name <name>', 'Index name', 'default')
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action(async (opts) => {
+      let client;
+      try {
+        const { client: c, collection } = await getMongoCollection(opts.db, opts.collection);
+        client = c;
+
+        const indexDef = {
+          name: opts.indexName,
+          type: 'vectorSearch',
+          definition: {
+            fields: [
+              {
+                type: 'vector',
+                path: opts.field,
+                numDimensions: parseInt(opts.dimensions, 10) || DEFAULT_DIMENSIONS,
+                similarity: opts.similarity,
+              },
+            ],
+          },
+        };
+
+        const result = await collection.createSearchIndex(indexDef);
+
+        if (opts.json) {
+          console.log(JSON.stringify({ indexName: result, definition: indexDef }, null, 2));
+        } else if (!opts.quiet) {
+          console.log(`✓ Vector search index created: "${result}"`);
+          console.log(`  Database:   ${opts.db}`);
+          console.log(`  Collection: ${opts.collection}`);
+          console.log(`  Field:      ${opts.field}`);
+          console.log(`  Dimensions: ${opts.dimensions}`);
+          console.log(`  Similarity: ${opts.similarity}`);
+          console.log('');
+          console.log('Note: Index may take a few minutes to become ready.');
+        }
+      } catch (err) {
+        if (err.message && err.message.includes('already exists')) {
+          console.error(`Error: Index "${opts.indexName}" already exists on ${opts.db}.${opts.collection}`);
+          console.error('Use a different --index-name or delete the existing index first.');
+        } else {
+          console.error(`Error: ${err.message}`);
+        }
+        process.exit(1);
+      } finally {
+        if (client) await client.close();
+      }
+    });
+
+  // ── index list ──
+  indexCmd
+    .command('list')
+    .description('List all search indexes on a collection')
+    .requiredOption('--db <database>', 'Database name')
+    .requiredOption('--collection <name>', 'Collection name')
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action(async (opts) => {
+      let client;
+      try {
+        const { client: c, collection } = await getMongoCollection(opts.db, opts.collection);
+        client = c;
+
+        const indexes = await collection.listSearchIndexes().toArray();
+
+        if (opts.json) {
+          console.log(JSON.stringify(indexes, null, 2));
+          return;
+        }
+
+        if (indexes.length === 0) {
+          console.log(`No search indexes found on ${opts.db}.${opts.collection}`);
+          return;
+        }
+
+        if (!opts.quiet) {
+          console.log(`Search indexes on ${opts.db}.${opts.collection}:`);
+          console.log('');
+        }
+
+        for (const idx of indexes) {
+          console.log(`  Name:   ${idx.name}`);
+          console.log(`  Type:   ${idx.type || 'N/A'}`);
+          console.log(`  Status: ${idx.status || 'N/A'}`);
+          if (idx.latestDefinition) {
+            console.log(`  Fields: ${JSON.stringify(idx.latestDefinition.fields || [])}`);
+          }
+          console.log('');
+        }
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      } finally {
+        if (client) await client.close();
+      }
+    });
+
+  // ── index delete ──
+  indexCmd
+    .command('delete')
+    .description('Drop a search index')
+    .requiredOption('--db <database>', 'Database name')
+    .requiredOption('--collection <name>', 'Collection name')
+    .requiredOption('-n, --index-name <name>', 'Index name to delete')
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action(async (opts) => {
+      let client;
+      try {
+        const { client: c, collection } = await getMongoCollection(opts.db, opts.collection);
+        client = c;
+
+        await collection.dropSearchIndex(opts.indexName);
+
+        if (opts.json) {
+          console.log(JSON.stringify({ dropped: opts.indexName }, null, 2));
+        } else if (!opts.quiet) {
+          console.log(`✓ Dropped search index: "${opts.indexName}"`);
+          console.log(`  Database:   ${opts.db}`);
+          console.log(`  Collection: ${opts.collection}`);
+        }
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      } finally {
+        if (client) await client.close();
+      }
+    });
+}
+
+module.exports = { registerIndex };

package/src/commands/models.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const { MODEL_CATALOG } = require('../lib/catalog');
+const { API_BASE } = require('../lib/api');
+const { formatTable } = require('../lib/format');
+
+/**
+ * Register the models command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerModels(program) {
+  program
+    .command('models')
+    .description('List available Voyage AI models')
+    .option('-t, --type <type>', 'Filter by type: embedding, reranking, or all', 'all')
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action((opts) => {
+      let models = MODEL_CATALOG;
+
+      if (opts.type !== 'all') {
+        models = models.filter(m => m.type === opts.type);
+      }
+
+      if (opts.json) {
+        console.log(JSON.stringify(models, null, 2));
+        return;
+      }
+
+      if (models.length === 0) {
+        console.log(`No models found for type: ${opts.type}`);
+        return;
+      }
+
+      if (!opts.quiet) {
+        console.log('Voyage AI Models');
+        console.log(`(via MongoDB AI API — ${API_BASE})`);
+        console.log('');
+      }
+
+      const headers = ['Model', 'Type', 'Context', 'Dimensions', 'Price', 'Best For'];
+      const rows = models.map(m => [m.name, m.type, m.context, m.dimensions, m.price, m.bestFor]);
+
+      console.log(formatTable(headers, rows));
+
+      if (!opts.quiet) {
+        console.log('');
+        console.log('Free tier: 200M tokens (most models), 50M (domain-specific)');
+        console.log('All 4-series models share the same embedding space.');
+      }
+    });
+}
+
+module.exports = { registerModels };

package/src/commands/rerank.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const fs = require('fs');
+const { DEFAULT_RERANK_MODEL } = require('../lib/catalog');
+const { apiRequest } = require('../lib/api');
+
+/**
+ * Register the rerank command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerRerank(program) {
+  program
+    .command('rerank')
+    .description('Rerank documents against a query')
+    .requiredOption('--query <text>', 'Search query')
+    .option('--documents <docs...>', 'Documents to rerank')
+    .option('--documents-file <path>', 'File with documents (JSON array or newline-delimited)')
+    .option('-m, --model <model>', 'Reranking model', DEFAULT_RERANK_MODEL)
+    .option('-k, --top-k <n>', 'Return top K results', (v) => parseInt(v, 10))
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action(async (opts) => {
+      try {
+        let documents = opts.documents;
+
+        if (opts.documentsFile) {
+          const content = fs.readFileSync(opts.documentsFile, 'utf-8').trim();
+          try {
+            const parsed = JSON.parse(content);
+            if (Array.isArray(parsed)) {
+              documents = parsed.map(item => {
+                if (typeof item === 'string') return item;
+                if (item.text) return item.text;
+                return JSON.stringify(item);
+              });
+            } else {
+              documents = [typeof parsed === 'string' ? parsed : JSON.stringify(parsed)];
+            }
+          } catch {
+            documents = content.split('\n').filter(line => line.trim());
+          }
+        }
+
+        // Also support stdin for documents
+        if (!documents && !process.stdin.isTTY) {
+          const chunks = [];
+          for await (const chunk of process.stdin) {
+            chunks.push(chunk);
+          }
+          const input = Buffer.concat(chunks).toString('utf-8').trim();
+          try {
+            const parsed = JSON.parse(input);
+            if (Array.isArray(parsed)) {
+              documents = parsed.map(item => {
+                if (typeof item === 'string') return item;
+                if (item.text) return item.text;
+                return JSON.stringify(item);
+              });
+            }
+          } catch {
+            documents = input.split('\n').filter(line => line.trim());
+          }
+        }
+
+        if (!documents || documents.length === 0) {
+          console.error('Error: No documents provided. Use --documents, --documents-file, or pipe via stdin.');
+          process.exit(1);
+        }
+
+        const body = {
+          query: opts.query,
+          documents,
+          model: opts.model,
+        };
+        if (opts.topK) {
+          body.top_k = opts.topK;
+        }
+
+        const result = await apiRequest('/rerank', body);
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+          return;
+        }
+
+        if (!opts.quiet) {
+          console.log(`Model: ${result.model}`);
+          console.log(`Query: "${opts.query}"`);
+          console.log(`Results: ${result.data?.length || 0}`);
+          if (result.usage) {
+            console.log(`Tokens: ${result.usage.total_tokens}`);
+          }
+          console.log('');
+        }
+
+        if (result.data) {
+          for (const item of result.data) {
+            const docPreview = documents[item.index].substring(0, 80);
+            const ellipsis = documents[item.index].length > 80 ? '...' : '';
+            console.log(`[${item.index}] Score: ${item.relevance_score.toFixed(6)}  "${docPreview}${ellipsis}"`);
+          }
+        }
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = { registerRerank };

package/src/commands/search.js

@@ -0,0 +1,111 @@
+'use strict';
+
+const { DEFAULT_EMBED_MODEL } = require('../lib/catalog');
+const { generateEmbeddings } = require('../lib/api');
+const { getMongoCollection } = require('../lib/mongo');
+
+/**
+ * Register the search command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerSearch(program) {
+  program
+    .command('search')
+    .description('Vector search against Atlas collection')
+    .requiredOption('--query <text>', 'Search query text')
+    .requiredOption('--db <database>', 'Database name')
+    .requiredOption('--collection <name>', 'Collection name')
+    .requiredOption('--index <name>', 'Vector search index name')
+    .requiredOption('--field <name>', 'Embedding field name')
+    .option('-m, --model <model>', 'Embedding model', DEFAULT_EMBED_MODEL)
+    .option('--input-type <type>', 'Input type for query embedding', 'query')
+    .option('-d, --dimensions <n>', 'Output dimensions', (v) => parseInt(v, 10))
+    .option('-l, --limit <n>', 'Maximum results', (v) => parseInt(v, 10), 10)
+    .option('--min-score <n>', 'Minimum similarity score', parseFloat)
+    .option('--num-candidates <n>', 'Number of candidates for ANN search', (v) => parseInt(v, 10))
+    .option('--filter <json>', 'Pre-filter JSON for $vectorSearch (e.g. \'{"category": "docs"}\')')
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action(async (opts) => {
+      let client;
+      try {
+        const embedResult = await generateEmbeddings([opts.query], {
+          model: opts.model,
+          inputType: opts.inputType,
+          dimensions: opts.dimensions,
+        });
+
+        const queryVector = embedResult.data[0].embedding;
+        const numCandidates = opts.numCandidates || Math.min(opts.limit * 15, 10000);
+
+        const { client: c, collection } = await getMongoCollection(opts.db, opts.collection);
+        client = c;
+
+        const vectorSearchStage = {
+          index: opts.index,
+          path: opts.field,
+          queryVector,
+          numCandidates,
+          limit: opts.limit,
+        };
+
+        // Add pre-filter if provided
+        if (opts.filter) {
+          try {
+            vectorSearchStage.filter = JSON.parse(opts.filter);
+          } catch (e) {
+            console.error('Error: Invalid filter JSON. Ensure it is valid JSON.');
+            process.exit(1);
+          }
+        }
+
+        const pipeline = [
+          { $vectorSearch: vectorSearchStage },
+          { $addFields: { score: { $meta: 'vectorSearchScore' } } },
+          ...(opts.minScore ? [{ $match: { score: { $gte: opts.minScore } } }] : []),
+        ];
+
+        const results = await collection.aggregate(pipeline).toArray();
+
+        const cleanResults = results.map(doc => {
+          const clean = { ...doc };
+          delete clean[opts.field];
+          return clean;
+        });
+
+        if (opts.json) {
+          console.log(JSON.stringify(cleanResults, null, 2));
+          return;
+        }
+
+        if (!opts.quiet) {
+          console.log(`Query: "${opts.query}"`);
+          console.log(`Results: ${cleanResults.length}`);
+          console.log('');
+        }
+
+        if (cleanResults.length === 0) {
+          console.log('No results found.');
+          return;
+        }
+
+        for (let i = 0; i < cleanResults.length; i++) {
+          const doc = cleanResults[i];
+          const score = doc.score?.toFixed(6) || 'N/A';
+          console.log(`── Result ${i + 1} (score: ${score}) ──`);
+          const textPreview = doc.text ? doc.text.substring(0, 200) : 'No text field';
+          const ellipsis = doc.text && doc.text.length > 200 ? '...' : '';
+          console.log(`  ${textPreview}${ellipsis}`);
+          console.log(`  _id: ${doc._id}`);
+          console.log('');
+        }
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      } finally {
+        if (client) await client.close();
+      }
+    });
+}
+
+module.exports = { registerSearch };

package/src/commands/store.js

@@ -0,0 +1,186 @@
+'use strict';
+
+const fs = require('fs');
+const { DEFAULT_EMBED_MODEL } = require('../lib/catalog');
+const { generateEmbeddings } = require('../lib/api');
+const { resolveTextInput } = require('../lib/input');
+const { getMongoCollection } = require('../lib/mongo');
+
+/**
+ * Register the store command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerStore(program) {
+  program
+    .command('store')
+    .description('Embed text and store in MongoDB Atlas')
+    .requiredOption('--db <database>', 'Database name')
+    .requiredOption('--collection <name>', 'Collection name')
+    .requiredOption('--field <name>', 'Embedding field name')
+    .option('--text <text>', 'Text to embed and store')
+    .option('-f, --file <path>', 'File to embed and store (text file or .jsonl for batch mode)')
+    .option('-m, --model <model>', 'Embedding model', DEFAULT_EMBED_MODEL)
+    .option('--input-type <type>', 'Input type: query or document', 'document')
+    .option('-d, --dimensions <n>', 'Output dimensions', (v) => parseInt(v, 10))
+    .option('--metadata <json>', 'Additional metadata as JSON')
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action(async (opts) => {
+      let client;
+      try {
+        // Batch mode: .jsonl file
+        if (opts.file && opts.file.endsWith('.jsonl')) {
+          await handleBatchStore(opts);
+          return;
+        }
+
+        const texts = await resolveTextInput(opts.text, opts.file);
+        const textContent = texts[0];
+
+        const embedResult = await generateEmbeddings([textContent], {
+          model: opts.model,
+          inputType: opts.inputType,
+          dimensions: opts.dimensions,
+        });
+
+        const embedding = embedResult.data[0].embedding;
+
+        const doc = {
+          text: textContent,
+          [opts.field]: embedding,
+          model: opts.model || DEFAULT_EMBED_MODEL,
+          dimensions: embedding.length,
+          createdAt: new Date(),
+        };
+
+        if (opts.metadata) {
+          try {
+            const meta = JSON.parse(opts.metadata);
+            Object.assign(doc, meta);
+          } catch (e) {
+            console.error('Error: Invalid metadata JSON. Ensure it is valid JSON.');
+            process.exit(1);
+          }
+        }
+
+        const { client: c, collection } = await getMongoCollection(opts.db, opts.collection);
+        client = c;
+        const result = await collection.insertOne(doc);
+
+        if (opts.json) {
+          console.log(JSON.stringify({
+            insertedId: result.insertedId,
+            dimensions: embedding.length,
+            model: doc.model,
+            tokens: embedResult.usage?.total_tokens,
+          }, null, 2));
+        } else if (!opts.quiet) {
+          console.log(`✓ Stored document: ${result.insertedId}`);
+          console.log(`  Database:   ${opts.db}`);
+          console.log(`  Collection: ${opts.collection}`);
+          console.log(`  Field:      ${opts.field}`);
+          console.log(`  Dimensions: ${embedding.length}`);
+          console.log(`  Model:      ${doc.model}`);
+          if (embedResult.usage) {
+            console.log(`  Tokens:     ${embedResult.usage.total_tokens}`);
+          }
+        }
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      } finally {
+        if (client) await client.close();
+      }
+    });
+}
+
+/**
+ * Handle batch store from a .jsonl file.
+ * Each line: {"text": "...", "metadata": {...}}
+ * @param {object} opts - Command options
+ */
+async function handleBatchStore(opts) {
+  let client;
+  try {
+    const content = fs.readFileSync(opts.file, 'utf-8').trim();
+    const lines = content.split('\n').filter(line => line.trim());
+
+    if (lines.length === 0) {
+      console.error('Error: JSONL file is empty.');
+      process.exit(1);
+    }
+
+    const records = lines.map((line, i) => {
+      try {
+        return JSON.parse(line);
+      } catch (e) {
+        console.error(`Error: Invalid JSON on line ${i + 1}: ${e.message}`);
+        process.exit(1);
+      }
+    });
+
+    const texts = records.map(r => {
+      if (!r.text) {
+        console.error('Error: Each JSONL line must have a "text" field.');
+        process.exit(1);
+      }
+      return r.text;
+    });
+
+    if (!opts.quiet) {
+      console.log(`Embedding ${texts.length} documents...`);
+    }
+
+    const embedResult = await generateEmbeddings(texts, {
+      model: opts.model,
+      inputType: opts.inputType,
+      dimensions: opts.dimensions,
+    });
+
+    const docs = records.map((record, i) => {
+      const embedding = embedResult.data[i].embedding;
+      const doc = {
+        text: record.text,
+        [opts.field]: embedding,
+        model: opts.model || DEFAULT_EMBED_MODEL,
+        dimensions: embedding.length,
+        createdAt: new Date(),
+      };
+      if (record.metadata) {
+        Object.assign(doc, record.metadata);
+      }
+      return doc;
+    });
+
+    const { client: c, collection } = await getMongoCollection(opts.db, opts.collection);
+    client = c;
+    const result = await collection.insertMany(docs);
+
+    if (opts.json) {
+      console.log(JSON.stringify({
+        insertedCount: result.insertedCount,
+        insertedIds: result.insertedIds,
+        dimensions: docs[0]?.dimensions,
+        model: opts.model || DEFAULT_EMBED_MODEL,
+        tokens: embedResult.usage?.total_tokens,
+      }, null, 2));
+    } else if (!opts.quiet) {
+      console.log(`✓ Stored ${result.insertedCount} documents`);
+      console.log(`  Database:   ${opts.db}`);
+      console.log(`  Collection: ${opts.collection}`);
+      console.log(`  Field:      ${opts.field}`);
+      console.log(`  Dimensions: ${docs[0]?.dimensions}`);
+      console.log(`  Model:      ${opts.model || DEFAULT_EMBED_MODEL}`);
+      if (embedResult.usage) {
+        console.log(`  Tokens:     ${embedResult.usage.total_tokens}`);
+      }
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  } finally {
+    if (client) await client.close();
+  }
+}
+
+module.exports = { registerStore };

package/src/lib/api.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const API_BASE = 'https://ai.mongodb.com/v1';
+const MAX_RETRIES = 3;
+
+/**
+ * Get the Voyage API key or exit with a helpful error.
+ * @returns {string}
+ */
+function requireApiKey() {
+  const key = process.env.VOYAGE_API_KEY;
+  if (!key) {
+    console.error('Error: VOYAGE_API_KEY environment variable is not set.');
+    console.error('');
+    console.error('Get one from MongoDB Atlas → AI Models → Create model API key');
+    console.error('Then: export VOYAGE_API_KEY="your-key-here"');
+    process.exit(1);
+  }
+  return key;
+}
+
+/**
+ * Sleep for the given number of milliseconds.
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * Make an authenticated request to the Voyage AI API with retry on 429.
+ * @param {string} endpoint - API endpoint path (e.g., '/embeddings')
+ * @param {object} body - Request body
+ * @returns {Promise<object>}
+ */
+async function apiRequest(endpoint, body) {
+  const apiKey = requireApiKey();
+  const url = `${API_BASE}${endpoint}`;
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (response.status === 429 && attempt < MAX_RETRIES) {
+      const retryAfter = response.headers.get('Retry-After');
+      const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : Math.pow(2, attempt) * 1000;
+      console.error(`Rate limited (429). Retrying in ${waitMs / 1000}s... (attempt ${attempt + 1}/${MAX_RETRIES})`);
+      await sleep(waitMs);
+      continue;
+    }
+
+    if (!response.ok) {
+      let errorDetail = '';
+      try {
+        const errBody = await response.json();
+        errorDetail = errBody.detail || errBody.message || errBody.error?.message || JSON.stringify(errBody);
+      } catch {
+        errorDetail = await response.text();
+      }
+      console.error(`API Error (${response.status}): ${errorDetail}`);
+      process.exit(1);
+    }
+
+    return response.json();
+  }
+}
+
+/**
+ * Generate embeddings for an array of texts.
+ * @param {string[]} texts - Array of texts to embed
+ * @param {object} options - Embedding options
+ * @param {string} [options.model] - Model name
+ * @param {string} [options.inputType] - Input type (query|document)
+ * @param {number} [options.dimensions] - Output dimensions
+ * @returns {Promise<object>} API response with embeddings
+ */
+async function generateEmbeddings(texts, options = {}) {
+  const { DEFAULT_EMBED_MODEL } = require('./catalog');
+
+  const body = {
+    input: texts,
+    model: options.model || DEFAULT_EMBED_MODEL,
+  };
+
+  if (options.inputType) {
+    body.input_type = options.inputType;
+  }
+  if (options.dimensions) {
+    body.output_dimension = options.dimensions;
+  }
+
+  return apiRequest('/embeddings', body);
+}
+
+module.exports = {
+  API_BASE,
+  requireApiKey,
+  apiRequest,
+  generateEmbeddings,
+};

package/src/lib/catalog.js

@@ -0,0 +1,26 @@
+'use strict';
+
+const DEFAULT_EMBED_MODEL = 'voyage-4-large';
+const DEFAULT_RERANK_MODEL = 'rerank-2.5';
+const DEFAULT_DIMENSIONS = 1024;
+
+/** @type {Array<{name: string, type: string, context: string, dimensions: string, price: string, bestFor: string}>} */
+const MODEL_CATALOG = [
+  { name: 'voyage-4-large', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.12/1M tokens', bestFor: 'Best quality, multilingual' },
+  { name: 'voyage-4', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.06/1M tokens', bestFor: 'Balanced quality/perf' },
+  { name: 'voyage-4-lite', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.02/1M tokens', bestFor: 'Lowest cost' },
+  { name: 'voyage-code-3', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.18/1M tokens', bestFor: 'Code retrieval' },
+  { name: 'voyage-finance-2', type: 'embedding', context: '32K', dimensions: '1024', price: '$0.12/1M tokens', bestFor: 'Finance' },
+  { name: 'voyage-law-2', type: 'embedding', context: '16K', dimensions: '1024', price: '$0.12/1M tokens', bestFor: 'Legal' },
+  { name: 'voyage-context-3', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.18/1M tokens', bestFor: 'Contextualized chunks' },
+  { name: 'voyage-multimodal-3.5', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.12/M + $0.60/B px', bestFor: 'Text + images + video' },
+  { name: 'rerank-2.5', type: 'reranking', context: '32K', dimensions: '—', price: '$0.05/1M tokens', bestFor: 'Best quality reranking' },
+  { name: 'rerank-2.5-lite', type: 'reranking', context: '32K', dimensions: '—', price: '$0.02/1M tokens', bestFor: 'Fast reranking' },
+];
+
+module.exports = {
+  DEFAULT_EMBED_MODEL,
+  DEFAULT_RERANK_MODEL,
+  DEFAULT_DIMENSIONS,
+  MODEL_CATALOG,
+};

package/src/lib/format.js

@@ -0,0 +1,24 @@
+'use strict';
+
+/**
+ * Format a simple table for terminal output.
+ * @param {string[]} headers - Column headers
+ * @param {string[][]} rows - Table rows
+ * @returns {string}
+ */
+function formatTable(headers, rows) {
+  const colWidths = headers.map((h, i) => {
+    const maxRow = rows.reduce((max, row) => Math.max(max, (row[i] || '').length), 0);
+    return Math.max(h.length, maxRow);
+  });
+
+  const sep = colWidths.map(w => '─'.repeat(w + 2)).join('┼');
+  const headerLine = headers.map((h, i) => ` ${h.padEnd(colWidths[i])} `).join('│');
+  const dataLines = rows.map(row =>
+    row.map((cell, i) => ` ${(cell || '').padEnd(colWidths[i])} `).join('│')
+  );
+
+  return [headerLine, sep, ...dataLines].join('\n');
+}
+
+module.exports = { formatTable };

package/src/lib/input.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * Read text input from argument, --file flag, or stdin.
+ * @param {string|undefined} textArg - Text argument from CLI
+ * @param {string|undefined} filePath - File path from --file flag
+ * @returns {Promise<string[]>} Array of text strings
+ */
+async function resolveTextInput(textArg, filePath) {
+  if (filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8').trim();
+    return [content];
+  }
+
+  if (textArg) {
+    return [textArg];
+  }
+
+  // Try reading from stdin (piped input)
+  if (!process.stdin.isTTY) {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
+    }
+    const input = Buffer.concat(chunks).toString('utf-8').trim();
+    if (!input) {
+      console.error('Error: No input provided. Pass text as an argument, use --file, or pipe via stdin.');
+      process.exit(1);
+    }
+    // Split by newlines for bulk embedding
+    return input.split('\n').filter(line => line.trim());
+  }
+
+  console.error('Error: No input provided. Pass text as an argument, use --file, or pipe via stdin.');
+  process.exit(1);
+}
+
+module.exports = { resolveTextInput };

package/src/lib/mongo.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * Get MongoDB URI or exit with a helpful error.
+ * @returns {string}
+ */
+function requireMongoUri() {
+  const uri = process.env.MONGODB_URI;
+  if (!uri) {
+    console.error('Error: MONGODB_URI environment variable is not set.');
+    console.error('');
+    console.error('Set your Atlas connection string:');
+    console.error('  export MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/"');
+    process.exit(1);
+  }
+  return uri;
+}
+
+/**
+ * Get a connected MongoDB client and target collection.
+ * Lazy-requires the mongodb driver.
+ * @param {string} db - Database name
+ * @param {string} collectionName - Collection name
+ * @returns {Promise<{client: import('mongodb').MongoClient, collection: import('mongodb').Collection}>}
+ */
+async function getMongoCollection(db, collectionName) {
+  const { MongoClient } = require('mongodb');
+  const uri = requireMongoUri();
+  const client = new MongoClient(uri);
+  await client.connect();
+  const collection = client.db(db).collection(collectionName);
+  return { client, collection };
+}
+
+/**
+ * Connect to MongoDB, run a function with the collection, then close.
+ * @param {string} db - Database name
+ * @param {string} collectionName - Collection name
+ * @param {(collection: import('mongodb').Collection) => Promise<*>} fn - Function to run
+ * @returns {Promise<*>}
+ */
+async function connectAndClose(db, collectionName, fn) {
+  const { client, collection } = await getMongoCollection(db, collectionName);
+  try {
+    return await fn(collection);
+  } finally {
+    await client.close();
+  }
+}
+
+module.exports = {
+  requireMongoUri,
+  getMongoCollection,
+  connectAndClose,
+};