voyageai-cli 1.12.0 → 1.13.0

package/README.md

@@ -1,14 +1,14 @@
 # voyageai-cli
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/mrlynn/voyageai-cli/main/voyageai-cli.png" alt="voyageai-cli" width="600" />
+  <img src="https://raw.githubusercontent.com/mrlynn/voyageai-cli/main/demo-readme.gif" alt="voyageai-cli demo" width="800" />
 </p>
 
 [![CI](https://github.com/mrlynn/voyageai-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/mrlynn/voyageai-cli/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/voyageai-cli.svg)](https://www.npmjs.com/package/voyageai-cli) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/node/v/voyageai-cli.svg)](https://nodejs.org)
 
-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.
+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/). Embed text, benchmark models, compare quantization tradeoffs, and search — all from the terminal. Pure Node.js — no Python required.
 
-Generate embeddings, rerank search results, store vectors in Atlas, and run semantic search — all from the command line.
+**16 commands · 201 tests · Interactive playground · Quantization benchmarks**
 
 > **⚠️ Disclaimer:** This is an independent, community-built tool. It is **not** an official product of MongoDB, Inc. or Voyage AI. It is not supported, endorsed, or maintained by either company. For official documentation, support, and products, visit:
 > - **MongoDB:** [mongodb.com](https://www.mongodb.com) | [MongoDB Atlas](https://www.mongodb.com/atlas) | [Support](https://support.mongodb.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voyageai-cli",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
   "bin": {
     "vai": "./src/cli.js"
@@ -40,5 +40,8 @@
     "ora": "^9.1.0",
     "picocolors": "^1.1.1",
     "update-notifier": "^7.3.1"
+  },
+  "devDependencies": {
+    "playwright": "^1.58.1"
   }
 }

package/src/commands/models.js

@@ -53,7 +53,7 @@ function registerModels(program) {
       const legacyModels = models.filter(m => m.legacy);
 
       if (opts.type !== 'all') {
-        models = models.filter(m => m.type === opts.type);
+        models = models.filter(m => opts.type === 'embedding' ? m.type.startsWith('embedding') : m.type === opts.type);
       }
 
       if (!showLegacy) {
@@ -84,14 +84,14 @@ function registerModels(program) {
 
       const formatWideRow = (m) => {
         const name = ui.cyan(m.name);
-        const type = m.type === 'embedding' ? ui.green(m.type) : ui.yellow(m.type);
+        const type = m.type.startsWith('embedding') ? ui.green(m.type) : ui.yellow(m.type);
         const price = ui.dim(m.price);
         return [name, type, m.context, m.dimensions, price, m.bestFor];
       };
 
       const formatCompactRow = (m) => {
         const name = ui.cyan(m.name);
-        const type = m.type === 'embedding' ? ui.green('embed') : ui.yellow('rerank');
+        const type = m.type.startsWith('embedding') ? ui.green(m.multimodal ? 'multi' : 'embed') : ui.yellow('rerank');
         const dims = compactDimensions(m.dimensions);
         const price = ui.dim(compactPrice(m.price));
         return [name, type, dims, price, m.shortFor || m.bestFor];

package/src/commands/ping.js

@@ -13,7 +13,12 @@ function registerPing(program) {
     .description('Test connectivity to Voyage AI API (and optionally MongoDB)')
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
+    .option('--mask', 'Mask sensitive info (cluster hostnames, endpoints) in output. Also enabled by VAI_MASK=1 env var.')
     .action(async (opts) => {
+      // Support env var so all recordings are masked without remembering the flag
+      if (process.env.VAI_MASK === '1' || process.env.VAI_MASK === 'true') {
+        opts.mask = true;
+      }
       const results = {};
 
       // ── Voyage AI ping ──
@@ -28,6 +33,31 @@ function registerPing(program) {
       const useColor = !opts.json;
       const useSpinner = useColor && !opts.quiet;
 
+      // Masking helper: "performance.zbcul.mongodb.net" → "perfo*****.mongodb.net"
+      const PUBLIC_HOSTS = ['ai.mongodb.com', 'api.voyageai.com'];
+      const maskHost = (host) => {
+        if (!opts.mask || !host) return host;
+        if (PUBLIC_HOSTS.includes(host)) return host;
+        const parts = host.split('.');
+        if (parts.length >= 3) {
+          const name = parts[0];
+          const masked = name.slice(0, Math.min(5, name.length)) + '*****';
+          return [masked, ...parts.slice(1)].join('.');
+        }
+        return host.slice(0, 5) + '*****';
+      };
+
+      const maskUrl = (url) => {
+        if (!opts.mask || !url) return url;
+        try {
+          const u = new URL(url);
+          u.hostname = maskHost(u.hostname);
+          return u.toString().replace(/\/$/, '');
+        } catch {
+          return url;
+        }
+      };
+
       const apiBase = getApiBase();
       const model = 'voyage-4-lite';
       const startTime = Date.now();
@@ -94,7 +124,7 @@ function registerPing(program) {
           console.log(`ok ${elapsed}ms`);
         } else {
           console.log(ui.success(`Connected to Voyage AI API ${ui.dim('(' + elapsed + 'ms)')}`));
-          console.log(ui.label('Endpoint', apiBase));
+          console.log(ui.label('Endpoint', maskUrl(apiBase)));
           console.log(ui.label('Model', model));
           console.log(ui.label('Dimensions', String(dims)));
           console.log(ui.label('Tokens', String(tokens)));
@@ -145,7 +175,7 @@ function registerPing(program) {
           if (!opts.json && !opts.quiet) {
             console.log('');
             console.log(ui.success(`Connected to MongoDB Atlas ${ui.dim('(' + mongoElapsed + 'ms)')}`));
-            console.log(ui.label('Cluster', cluster));
+            console.log(ui.label('Cluster', maskHost(cluster)));
           }
 
           await client.close();

package/src/commands/playground.js

@@ -84,7 +84,7 @@ function createPlaygroundServer() {
 
       // API: Models
       if (req.method === 'GET' && req.url === '/api/models') {
-        const models = MODEL_CATALOG.filter(m => !m.legacy && !m.local);
+        const models = MODEL_CATALOG.filter(m => !m.legacy && !m.local && !m.unreleased);
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ models }));
         return;

package/src/commands/search.js

@@ -16,8 +16,8 @@ function registerSearch(program) {
     .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('--index <name>', 'Vector search index name', 'vector_index')
+    .option('--field <name>', 'Embedding field name', 'embedding')
     .option('-m, --model <model>', 'Embedding model', getDefaultModel())
     .option('--input-type <type>', 'Input type for query embedding', 'query')
     .option('-d, --dimensions <n>', 'Output dimensions', (v) => parseInt(v, 10))

package/src/commands/store.js

@@ -17,7 +17,7 @@ function registerStore(program) {
     .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('--field <name>', 'Embedding field name', 'embedding')
     .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', getDefaultModel())

package/src/lib/api.js

@@ -96,25 +96,29 @@ async function apiRequest(endpoint, body) {
       } catch {
         errorDetail = await response.text();
       }
-      console.error(`API Error (${response.status}): ${errorDetail}`);
+      const errMsg = `API Error (${response.status}): ${errorDetail}`;
 
       // Help users diagnose endpoint mismatch
+      let hint = '';
       if (response.status === 403 && base === ATLAS_API_BASE) {
-        console.error('');
-        console.error('Hint: 403 on ai.mongodb.com often means your key is for the Voyage AI');
-        console.error('platform, not MongoDB Atlas. Try switching the base URL:');
-        console.error('');
-        console.error('  vai config set base-url https://api.voyageai.com/v1/');
-        console.error('');
-        console.error('Or set VOYAGE_API_BASE=https://api.voyageai.com/v1/ in your environment.');
+        hint = '\n\nHint: 403 on ai.mongodb.com often means your key is for the Voyage AI' +
+          '\nplatform, not MongoDB Atlas. Try switching the base URL:' +
+          '\n\n  vai config set base-url https://api.voyageai.com/v1/' +
+          '\n\nOr set VOYAGE_API_BASE=https://api.voyageai.com/v1/ in your environment.';
       } else if (response.status === 401 && base === VOYAGE_API_BASE) {
-        console.error('');
-        console.error('Hint: 401 on api.voyageai.com may mean your key is an Atlas AI key.');
-        console.error('Try switching back:');
-        console.error('');
-        console.error('  vai config set base-url https://ai.mongodb.com/v1/');
+        hint = '\n\nHint: 401 on api.voyageai.com may mean your key is an Atlas AI key.' +
+          '\nTry switching back:' +
+          '\n\n  vai config set base-url https://ai.mongodb.com/v1/';
       }
-      process.exit(1);
+
+      // Log the error + hint to stderr for CLI users
+      console.error(errMsg);
+      if (hint) console.error(hint);
+
+      // Throw instead of process.exit so callers (like playground) can catch gracefully
+      const err = new Error(errMsg);
+      err.statusCode = response.status;
+      throw err;
     }
 
     return response.json();

package/src/lib/catalog.js

@@ -32,8 +32,8 @@ const MODEL_CATALOG = [
   { name: 'voyage-code-3', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.18/1M tokens', bestFor: 'Code retrieval', shortFor: 'Code' },
   { name: 'voyage-finance-2', type: 'embedding', context: '32K', dimensions: '1024', price: '$0.12/1M tokens', bestFor: 'Finance', shortFor: 'Finance' },
   { name: 'voyage-law-2', type: 'embedding', context: '16K', dimensions: '1024', price: '$0.12/1M tokens', bestFor: 'Legal', shortFor: 'Legal' },
-  { name: 'voyage-context-3', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.18/1M tokens', bestFor: 'Contextualized chunks', shortFor: 'Context 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', shortFor: 'Multimodal' },
+  { name: 'voyage-context-3', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.18/1M tokens', bestFor: 'Contextualized chunks', shortFor: 'Context chunks', unreleased: true },
+  { name: 'voyage-multimodal-3.5', type: 'embedding-multimodal', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.12/M + $0.60/B px', bestFor: 'Text + images + video', shortFor: 'Multimodal', multimodal: true },
   { name: 'rerank-2.5', type: 'reranking', context: '32K', dimensions: '—', price: '$0.05/1M tokens', bestFor: 'Best quality reranking', shortFor: 'Best reranker' },
   { name: 'rerank-2.5-lite', type: 'reranking', context: '32K', dimensions: '—', price: '$0.02/1M tokens', bestFor: 'Fast reranking', shortFor: 'Fast reranker' },
   { name: 'voyage-4-nano', type: 'embedding', context: '32K', dimensions: '512 (default), 128, 256', price: 'Open-weight', bestFor: 'Open-weight / edge', shortFor: 'Open / edge', local: true },
@@ -42,7 +42,7 @@ const MODEL_CATALOG = [
   { name: 'voyage-3.5', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.06/1M tokens', bestFor: 'Previous gen balanced', shortFor: 'Previous gen balanced', legacy: true },
   { name: 'voyage-3.5-lite', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.02/1M tokens', bestFor: 'Previous gen budget', shortFor: 'Previous gen budget', legacy: true },
   { name: 'voyage-code-2', type: 'embedding', context: '16K', dimensions: '1536', price: '$0.12/1M tokens', bestFor: 'Legacy code', shortFor: 'Legacy code', legacy: true },
-  { name: 'voyage-multimodal-3', type: 'embedding', context: '32K', dimensions: '1024', price: '$0.12/1M tokens', bestFor: 'Legacy multimodal', shortFor: 'Legacy multimodal', legacy: true },
+  { name: 'voyage-multimodal-3', type: 'embedding-multimodal', context: '32K', dimensions: '1024', price: '$0.12/1M tokens', bestFor: 'Legacy multimodal', shortFor: 'Legacy multimodal', legacy: true, multimodal: true },
   { name: 'rerank-2', type: 'reranking', context: '16K', dimensions: '—', price: '$0.05/1M tokens', bestFor: 'Legacy reranker', shortFor: 'Legacy reranker', legacy: true },
   { name: 'rerank-2-lite', type: 'reranking', context: '8K', dimensions: '—', price: '$0.02/1M tokens', bestFor: 'Legacy fast reranker', shortFor: 'Legacy fast reranker', legacy: true },
 ];

package/.github/workflows/ci.yml

@@ -1,22 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-  workflow_dispatch:
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [18, 20, 22]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-      - run: npm ci
-      - run: npm test

package/CONTRIBUTING.md

@@ -1,81 +0,0 @@
-# Contributing to voyageai-cli
-
-Thanks for your interest in contributing! Here's how to get started.
-
-## Development Setup
-
-```bash
-git clone https://github.com/mrlynn/voyageai-cli.git
-cd voyageai-cli
-npm install
-npm link  # makes `vai` available globally for testing
-```
-
-## Running Tests
-
-```bash
-npm test
-```
-
-Tests use Node.js built-in test runner (`node:test`). No external test framework needed.
-
-## Project Structure
-
-```
-src/
-├── cli.js              # Entry point
-├── commands/           # One file per command
-│   ├── embed.js
-│   ├── rerank.js
-│   ├── store.js
-│   ├── search.js
-│   ├── index.js
-│   ├── models.js
-│   ├── ping.js
-│   ├── config.js
-│   └── demo.js
-└── lib/                # Shared utilities
-    ├── api.js          # Voyage AI API client
-    ├── mongo.js        # MongoDB connection
-    ├── catalog.js      # Model catalog
-    ├── config.js       # Config file management
-    ├── format.js       # Table formatting
-    ├── input.js        # Text input resolution
-    ├── ui.js           # Colors, spinners, output helpers
-    └── banner.js       # ASCII banner
-test/
-├── commands/           # Command tests
-└── lib/                # Library tests
-```
-
-## Adding a New Command
-
-1. Create `src/commands/mycommand.js` exporting a `registerMyCommand(program)` function
-2. Register it in `src/cli.js`
-3. Add tests in `test/commands/mycommand.test.js`
-4. Update README.md with usage examples
-
-## Code Style
-
-- CommonJS (`require`/`module.exports`)
-- `'use strict';` at the top of every file
-- JSDoc comments on exported functions
-- `parseInt(x, 10)` — always include radix
-- Errors go to stderr (`console.error`)
-- Support `--json` and `--quiet` flags on all commands
-- No colors or spinners in `--json` mode
-
-## Pull Requests
-
-- Create a feature branch from `main`
-- Include tests for new functionality
-- Run `npm test` before submitting
-- Write clear commit messages
-
-## Reporting Issues
-
-Open an issue at https://github.com/mrlynn/voyageai-cli/issues with:
-- Node.js version (`node --version`)
-- OS and version
-- Steps to reproduce
-- Expected vs actual behavior

package/demo.tape

@@ -1,39 +0,0 @@
-# VHS demo tape for voyageai-cli
-# Run: vhs demo.tape
-# Requires: VOYAGE_API_KEY set in environment
-
-Output demo.gif
-
-Set FontSize 16
-Set Width 900
-Set Height 600
-Set Theme "Catppuccin Mocha"
-Set Padding 20
-
-# Show version
-Type "vai --version"
-Enter
-Sleep 1.5s
-
-# List embedding models
-Type "vai models --type embedding"
-Enter
-Sleep 3s
-
-# Generate an embedding
-Type 'vai embed "What is MongoDB Atlas?"'
-Enter
-Sleep 4s
-
-# Explain embeddings (first few lines)
-Type "vai explain embeddings"
-Enter
-Sleep 4s
-
-# Compare similarity
-Type 'vai similarity "MongoDB is great" "MongoDB Atlas is amazing"'
-Enter
-Sleep 4s
-
-# Pause at end to show results
-Sleep 2s

package/scripts/record-demo.sh

@@ -1,63 +0,0 @@
-#!/usr/bin/env bash
-# Record a demo GIF for voyageai-cli
-# Requires: VOYAGE_API_KEY environment variable
-#
-# Usage:
-#   ./scripts/record-demo.sh          # Uses vhs (preferred)
-#   ./scripts/record-demo.sh asciinema # Uses asciinema instead
-#
-# Output:
-#   demo.gif (vhs) or demo.cast (asciinema)
-
-set -euo pipefail
-cd "$(dirname "$0")/.."
-
-METHOD="${1:-vhs}"
-
-if [ "$METHOD" = "vhs" ]; then
-  if ! command -v vhs &>/dev/null; then
-    echo "❌ vhs not found. Install: brew install charmbracelet/tap/vhs"
-    echo "   Or run: ./scripts/record-demo.sh asciinema"
-    exit 1
-  fi
-
-  if [ -z "${VOYAGE_API_KEY:-}" ]; then
-    echo "⚠️  VOYAGE_API_KEY not set. Commands that call the API will fail."
-    echo "   Set it: export VOYAGE_API_KEY=your-key"
-    exit 1
-  fi
-
-  echo "🎬 Recording demo with vhs..."
-  vhs demo.tape
-  echo "✅ Demo GIF saved to demo.gif"
-
-elif [ "$METHOD" = "asciinema" ]; then
-  if ! command -v asciinema &>/dev/null; then
-    echo "❌ asciinema not found. Install: brew install asciinema"
-    exit 1
-  fi
-
-  CAST_FILE="demo.cast"
-  echo "🎬 Recording demo with asciinema..."
-  echo "   Run the following commands, then press Ctrl-D when done:"
-  echo ""
-  echo "   vai --version"
-  echo "   vai models --type embedding"
-  echo '   vai embed "What is MongoDB Atlas?"'
-  echo "   vai explain embeddings"
-  echo '   vai similarity "MongoDB is great" "MongoDB Atlas is amazing"'
-  echo ""
-
-  asciinema rec "$CAST_FILE"
-  echo "✅ Recording saved to $CAST_FILE"
-  echo ""
-  echo "Convert to GIF with agg or svg-term-cli:"
-  echo "  agg $CAST_FILE demo.gif"
-  echo "  # or"
-  echo "  npx svg-term-cli --in $CAST_FILE --out demo.svg --window"
-
-else
-  echo "Unknown method: $METHOD"
-  echo "Usage: $0 [vhs|asciinema]"
-  exit 1
-fi

package/test/commands/about.test.js

@@ -1,23 +0,0 @@
-'use strict';
-
-const { describe, it } = require('node:test');
-const assert = require('node:assert/strict');
-const { Command } = require('commander');
-const { registerAbout } = require('../../src/commands/about');
-
-describe('about command', () => {
-  it('registers correctly on a program', () => {
-    const program = new Command();
-    registerAbout(program);
-    const aboutCmd = program.commands.find(c => c.name() === 'about');
-    assert.ok(aboutCmd, 'about command should be registered');
-  });
-
-  it('has --json option', () => {
-    const program = new Command();
-    registerAbout(program);
-    const aboutCmd = program.commands.find(c => c.name() === 'about');
-    const optionNames = aboutCmd.options.map(o => o.long);
-    assert.ok(optionNames.includes('--json'), 'should have --json option');
-  });
-});