voyageai-cli 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,8 @@ Format based on [Keep a Changelog](https://keepachangelog.com/).
 ## [Unreleased]
 
 ### Added
+- `vai ingest` — Bulk import from JSONL/JSON/CSV/text with batching, progress bar, and dry-run
+- `vai similarity` — Compute cosine similarity between texts without MongoDB
 - `vai demo` — Interactive guided walkthrough of all features
 - ASCII banner when running `vai` with no arguments
 - CONTRIBUTING.md for open-source contributors

package/NOTICE

@@ -0,0 +1,23 @@
+voyageai-cli — Community CLI for Voyage AI and MongoDB Atlas Vector Search
+
+Copyright (c) 2026 Michael Lynn
+
+DISCLAIMER:
+This software is an independent, community-built tool. It is NOT an official
+product of MongoDB, Inc. or Voyage AI (a MongoDB company). It is not supported,
+endorsed, or maintained by either organization.
+
+This tool interacts with:
+- The MongoDB Atlas Embedding and Reranking API (https://ai.mongodb.com/v1/)
+- MongoDB Atlas Vector Search (https://www.mongodb.com/docs/atlas/atlas-vector-search/)
+
+For official documentation, support, and products:
+- MongoDB: https://www.mongodb.com
+- Voyage AI: https://www.mongodb.com/docs/voyageai/
+- MongoDB Support: https://support.mongodb.com
+
+"MongoDB", "MongoDB Atlas", and "Voyage AI" are trademarks of MongoDB, Inc.
+All trademarks belong to their respective owners.
+
+This software is provided "as is" without warranty of any kind. See LICENSE
+for the full MIT License terms.

package/README.md

@@ -4,8 +4,17 @@
 
 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.
 
+<!-- TODO: Add demo GIF -->
+<!-- ![vai demo](demo.gif) -->
+
 Generate embeddings, rerank search results, store vectors in Atlas, and run semantic search — all from the command line.
 
+> **⚠️ 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)
+> - **Voyage AI:** [MongoDB Voyage AI Docs](https://www.mongodb.com/docs/voyageai/)
+>
+> Use at your own risk. No warranty is provided. See [LICENSE](LICENSE) for details.
+
 ## Install
 
 ```bash
@@ -60,6 +69,19 @@ vai rerank --query "best database" --documents-file candidates.json --top-k 3
 vai rerank --query "query" --documents "doc1" "doc2" --model rerank-2.5-lite
 ```
 
+### `vai similarity` — Compare text similarity
+
+```bash
+# Compare two texts
+vai similarity "MongoDB is a document database" "MongoDB Atlas is a cloud database"
+
+# Compare one text against many
+vai similarity "database performance" --against "MongoDB is fast" "PostgreSQL is relational"
+
+# From files
+vai similarity --file1 doc1.txt --file2 doc2.txt
+```
+
 ### `vai store` — Embed and insert into MongoDB Atlas
 
 Requires `MONGODB_URI` environment variable.
@@ -79,6 +101,29 @@ vai store --db myapp --collection docs --field embedding \
   --file documents.jsonl
 ```
 
+### `vai ingest` — Bulk import with progress
+
+```bash
+# JSONL (one JSON object per line with a "text" field)
+vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding
+
+# JSON array
+vai ingest --file documents.json --db myapp --collection docs --field embedding
+
+# CSV (specify text column)
+vai ingest --file data.csv --db myapp --collection docs --field embedding --text-column content
+
+# Plain text (one document per line)
+vai ingest --file lines.txt --db myapp --collection docs --field embedding
+
+# Options
+vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding \
+  --model voyage-4 --batch-size 100 --input-type document
+
+# Preview without embedding
+vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding --dry-run
+```
+
 ### `vai search` — Vector similarity search
 
 Requires `MONGODB_URI` environment variable.
@@ -206,6 +251,41 @@ vai config get
 - Use `echo "key" | vai config set api-key --stdin` or `vai config set api-key --stdin < keyfile` to avoid shell history exposure
 - The config file stores credentials in plaintext (similar to `~/.aws/credentials` and `~/.npmrc`) — protect your home directory accordingly
 
+## Shell Completions
+
+`vai` supports tab completion for bash and zsh.
+
+### Bash
+
+```bash
+# Add to ~/.bashrc (or ~/.bash_profile on macOS)
+vai completions bash >> ~/.bashrc
+source ~/.bashrc
+
+# Or install system-wide (Linux)
+vai completions bash > /etc/bash_completion.d/vai
+
+# Or with Homebrew (macOS)
+vai completions bash > $(brew --prefix)/etc/bash_completion.d/vai
+```
+
+### Zsh
+
+```bash
+# Create completions directory
+mkdir -p ~/.zsh/completions
+
+# Add to fpath in ~/.zshrc (if not already there)
+echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
+echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
+
+# Generate the completion file
+vai completions zsh > ~/.zsh/completions/_vai
+source ~/.zshrc
+```
+
+Completions cover all 14 commands, subcommands, flags, model names, and explain topics.
+
 ## Global Flags
 
 All commands support:
@@ -237,6 +317,10 @@ Free tier: 200M tokens for most models. All Voyage 4 series models share the sam
 - 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)
 
+## 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 support, visit [mongodb.com](https://www.mongodb.com).
+
 ## License
 
 MIT

package/demo.tape

@@ -0,0 +1,39 @@
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voyageai-cli",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
   "bin": {
     "vai": "./src/cli.js"

package/scripts/record-demo.sh

@@ -0,0 +1,63 @@
+#!/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/src/cli.js

@@ -4,6 +4,7 @@
 require('dotenv').config({ quiet: true });
 
 const { program } = require('commander');
+const pc = require('picocolors');
 const { registerEmbed } = require('./commands/embed');
 const { registerRerank } = require('./commands/rerank');
 const { registerStore } = require('./commands/store');
@@ -13,12 +14,18 @@ const { registerModels } = require('./commands/models');
 const { registerPing } = require('./commands/ping');
 const { registerConfig } = require('./commands/config');
 const { registerDemo } = require('./commands/demo');
-const { showBanner, showQuickStart } = require('./lib/banner');
+const { registerExplain } = require('./commands/explain');
+const { registerSimilarity } = require('./commands/similarity');
+const { registerIngest } = require('./commands/ingest');
+const { registerCompletions } = require('./commands/completions');
+const { showBanner, showQuickStart, getVersion } = require('./lib/banner');
+
+const version = getVersion();
 
 program
   .name('vai')
   .description('Voyage AI embeddings, reranking, and Atlas Vector Search CLI')
-  .version('1.1.0');
+  .version(`vai/${version} (community tool — not an official MongoDB or Voyage AI product)`, '-V, --version', 'output the version number');
 
 registerEmbed(program);
 registerRerank(program);
@@ -29,6 +36,16 @@ registerModels(program);
 registerPing(program);
 registerConfig(program);
 registerDemo(program);
+registerExplain(program);
+registerSimilarity(program);
+registerIngest(program);
+registerCompletions(program);
+
+// Append disclaimer to all help output
+program.addHelpText('after', `
+${pc.dim('Community tool — not an official MongoDB or Voyage AI product.')}
+${pc.dim('Docs: https://www.mongodb.com/docs/voyageai/')}
+`);
 
 // If no args (just `vai`), show banner + quick start + help
 if (process.argv.length <= 2) {