voyageai-cli 1.12.1 → 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.1",
+  "version": "1.13.0",
   "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
   "bin": {
     "vai": "./src/cli.js"

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');
-  });
-});

package/test/commands/benchmark.test.js

@@ -1,319 +0,0 @@
-'use strict';
-
-const { describe, it } = require('node:test');
-const assert = require('node:assert/strict');
-const { Command } = require('commander');
-const { registerBenchmark } = require('../../src/commands/benchmark');
-
-describe('benchmark command', () => {
-  it('registers as benchmark with bench alias', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    assert.ok(benchCmd, 'benchmark command should be registered');
-    assert.ok(benchCmd.aliases().includes('bench'), 'should have "bench" alias');
-  });
-
-  it('has embed subcommand', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const embedSub = benchCmd.commands.find(c => c.name() === 'embed');
-    assert.ok(embedSub, 'embed subcommand should be registered');
-  });
-
-  it('embed has --models option', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const embedSub = benchCmd.commands.find(c => c.name() === 'embed');
-    const optionNames = embedSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--models'), 'should have --models option');
-  });
-
-  it('embed has --rounds option', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const embedSub = benchCmd.commands.find(c => c.name() === 'embed');
-    const optionNames = embedSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--rounds'), 'should have --rounds option');
-  });
-
-  it('embed has --input option for custom text', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const embedSub = benchCmd.commands.find(c => c.name() === 'embed');
-    const optionNames = embedSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--input'), 'should have --input option');
-  });
-
-  it('embed has --file option', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const embedSub = benchCmd.commands.find(c => c.name() === 'embed');
-    const optionNames = embedSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--file'), 'should have --file option');
-  });
-
-  it('embed has --json and --quiet options', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const embedSub = benchCmd.commands.find(c => c.name() === 'embed');
-    const optionNames = embedSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--json'), 'should have --json option');
-    assert.ok(optionNames.includes('--quiet'), 'should have --quiet option');
-  });
-
-  it('embed has --dimensions option', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const embedSub = benchCmd.commands.find(c => c.name() === 'embed');
-    const optionNames = embedSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--dimensions'), 'should have --dimensions option');
-  });
-
-  it('has rerank subcommand', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const rerankSub = benchCmd.commands.find(c => c.name() === 'rerank');
-    assert.ok(rerankSub, 'rerank subcommand should be registered');
-  });
-
-  it('rerank has --models and --rounds options', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const rerankSub = benchCmd.commands.find(c => c.name() === 'rerank');
-    const optionNames = rerankSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--models'), 'should have --models option');
-    assert.ok(optionNames.includes('--rounds'), 'should have --rounds option');
-  });
-
-  it('rerank has --query option', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const rerankSub = benchCmd.commands.find(c => c.name() === 'rerank');
-    const optionNames = rerankSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--query'), 'should have --query option');
-  });
-
-  it('rerank has --documents-file and --top-k options', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const rerankSub = benchCmd.commands.find(c => c.name() === 'rerank');
-    const optionNames = rerankSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--documents-file'), 'should have --documents-file option');
-    assert.ok(optionNames.includes('--top-k'), 'should have --top-k option');
-  });
-
-  it('has similarity subcommand', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const simSub = benchCmd.commands.find(c => c.name() === 'similarity');
-    assert.ok(simSub, 'similarity subcommand should be registered');
-  });
-
-  it('similarity has --models, --query, --file, --top-k options', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const simSub = benchCmd.commands.find(c => c.name() === 'similarity');
-    const optionNames = simSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--models'), 'should have --models');
-    assert.ok(optionNames.includes('--query'), 'should have --query');
-    assert.ok(optionNames.includes('--file'), 'should have --file');
-    assert.ok(optionNames.includes('--top-k'), 'should have --top-k');
-  });
-
-  it('has cost subcommand', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const costSub = benchCmd.commands.find(c => c.name() === 'cost');
-    assert.ok(costSub, 'cost subcommand should be registered');
-  });
-
-  it('cost has --models, --tokens, --volumes options', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const costSub = benchCmd.commands.find(c => c.name() === 'cost');
-    const optionNames = costSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--models'), 'should have --models');
-    assert.ok(optionNames.includes('--tokens'), 'should have --tokens');
-    assert.ok(optionNames.includes('--volumes'), 'should have --volumes');
-  });
-
-  it('has batch subcommand', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const batchSub = benchCmd.commands.find(c => c.name() === 'batch');
-    assert.ok(batchSub, 'batch subcommand should be registered');
-  });
-
-  it('batch has --model, --batch-sizes, --rounds options', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const batchSub = benchCmd.commands.find(c => c.name() === 'batch');
-    const optionNames = batchSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--model'), 'should have --model');
-    assert.ok(optionNames.includes('--batch-sizes'), 'should have --batch-sizes');
-    assert.ok(optionNames.includes('--rounds'), 'should have --rounds');
-  });
-
-  it('all subcommands have --json output option', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-
-    for (const sub of benchCmd.commands) {
-      if (sub.name() === 'help') continue;
-      const optionNames = sub.options.map(o => o.long);
-      assert.ok(optionNames.includes('--json'), `${sub.name()} should have --json option`);
-    }
-  });
-
-  it('all subcommands have --quiet option', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-
-    for (const sub of benchCmd.commands) {
-      if (sub.name() === 'help') continue;
-      const optionNames = sub.options.map(o => o.long);
-      assert.ok(optionNames.includes('--quiet'), `${sub.name()} should have --quiet option`);
-    }
-  });
-
-  it('embed defaults models to voyage-4-large,voyage-4,voyage-4-lite', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const embedSub = benchCmd.commands.find(c => c.name() === 'embed');
-    const modelsOpt = embedSub.options.find(o => o.long === '--models');
-    assert.equal(modelsOpt.defaultValue, 'voyage-4-large,voyage-4,voyage-4-lite');
-  });
-
-  it('rerank defaults models to rerank-2.5,rerank-2.5-lite', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const rerankSub = benchCmd.commands.find(c => c.name() === 'rerank');
-    const modelsOpt = rerankSub.options.find(o => o.long === '--models');
-    assert.equal(modelsOpt.defaultValue, 'rerank-2.5,rerank-2.5-lite');
-  });
-
-  it('cost defaults volumes to 100,1000,10000,100000', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const costSub = benchCmd.commands.find(c => c.name() === 'cost');
-    const volOpt = costSub.options.find(o => o.long === '--volumes');
-    assert.equal(volOpt.defaultValue, '100,1000,10000,100000');
-  });
-
-  it('embed has --save option', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const embedSub = benchCmd.commands.find(c => c.name() === 'embed');
-    const optionNames = embedSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--save'), 'should have --save option');
-  });
-
-  it('rerank has --save option', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const rerankSub = benchCmd.commands.find(c => c.name() === 'rerank');
-    const optionNames = rerankSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--save'), 'should have --save option');
-  });
-
-  it('has asymmetric subcommand', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const asymSub = benchCmd.commands.find(c => c.name() === 'asymmetric');
-    assert.ok(asymSub, 'asymmetric subcommand should be registered');
-  });
-
-  it('asymmetric has --doc-model and --query-models options', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const asymSub = benchCmd.commands.find(c => c.name() === 'asymmetric');
-    const optionNames = asymSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--doc-model'), 'should have --doc-model');
-    assert.ok(optionNames.includes('--query-models'), 'should have --query-models');
-  });
-
-  it('asymmetric defaults doc-model to voyage-4-large', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const asymSub = benchCmd.commands.find(c => c.name() === 'asymmetric');
-    const opt = asymSub.options.find(o => o.long === '--doc-model');
-    assert.equal(opt.defaultValue, 'voyage-4-large');
-  });
-
-  it('has quantization subcommand with quant alias', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const quantSub = benchCmd.commands.find(c => c.name() === 'quantization');
-    assert.ok(quantSub, 'quantization subcommand should be registered');
-    assert.ok(quantSub.aliases().includes('quant'), 'should have "quant" alias');
-  });
-
-  it('quantization has --model, --dtypes, --query options', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const quantSub = benchCmd.commands.find(c => c.name() === 'quantization');
-    const optionNames = quantSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--model'), 'should have --model');
-    assert.ok(optionNames.includes('--dtypes'), 'should have --dtypes');
-    assert.ok(optionNames.includes('--query'), 'should have --query');
-  });
-
-  it('quantization defaults dtypes to float,int8,ubinary', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const quantSub = benchCmd.commands.find(c => c.name() === 'quantization');
-    const dtypesOpt = quantSub.options.find(o => o.long === '--dtypes');
-    assert.equal(dtypesOpt.defaultValue, 'float,int8,ubinary');
-  });
-
-  it('quantization has --dimensions, --save, --file options', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const quantSub = benchCmd.commands.find(c => c.name() === 'quantization');
-    const optionNames = quantSub.options.map(o => o.long);
-    assert.ok(optionNames.includes('--dimensions'), 'should have --dimensions');
-    assert.ok(optionNames.includes('--save'), 'should have --save');
-    assert.ok(optionNames.includes('--file'), 'should have --file');
-  });
-
-  it('batch defaults batch-sizes to 1,5,10,25,50', () => {
-    const program = new Command();
-    registerBenchmark(program);
-    const benchCmd = program.commands.find(c => c.name() === 'benchmark');
-    const batchSub = benchCmd.commands.find(c => c.name() === 'batch');
-    const sizesOpt = batchSub.options.find(o => o.long === '--batch-sizes');
-    assert.equal(sizesOpt.defaultValue, '1,5,10,25,50');
-  });
-});