voyageai-cli 1.4.0 → 1.5.0

package/README.md

@@ -4,6 +4,9 @@
 
 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:
@@ -248,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:

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

@@ -17,6 +17,7 @@ const { registerDemo } = require('./commands/demo');
 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();
@@ -38,6 +39,7 @@ registerDemo(program);
 registerExplain(program);
 registerSimilarity(program);
 registerIngest(program);
+registerCompletions(program);
 
 // Append disclaimer to all help output
 program.addHelpText('after', `

package/src/commands/completions.js

@@ -0,0 +1,463 @@
+'use strict';
+
+const pc = require('picocolors');
+
+/**
+ * Generate bash completion script for vai CLI.
+ * @returns {string}
+ */
+function generateBashCompletions() {
+  return `#!/bin/bash
+# vai bash completion script
+# Install: vai completions bash >> ~/.bashrc && source ~/.bashrc
+# Or:      vai completions bash > /usr/local/etc/bash_completion.d/vai
+
+_vai_completions() {
+  local cur prev commands
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  # Top-level commands
+  commands="embed rerank store search index models ping config demo explain similarity ingest completions help"
+
+  # Subcommands
+  local index_subs="create list delete"
+  local config_subs="set get delete path reset"
+
+  # Global flags
+  local global_flags="--json --quiet --help --version"
+
+  case "\${COMP_WORDS[1]}" in
+    embed)
+      COMPREPLY=( \$(compgen -W "--model --input-type --dimensions --file --output-format --json --quiet --help" -- "\$cur") )
+      return 0
+      ;;
+    rerank)
+      COMPREPLY=( \$(compgen -W "--query --documents --documents-file --model --top-k --json --quiet --help" -- "\$cur") )
+      return 0
+      ;;
+    store)
+      COMPREPLY=( \$(compgen -W "--db --collection --field --text --file --model --input-type --dimensions --metadata --json --quiet --help" -- "\$cur") )
+      return 0
+      ;;
+    search)
+      COMPREPLY=( \$(compgen -W "--query --db --collection --index --field --model --input-type --dimensions --limit --min-score --num-candidates --filter --json --quiet --help" -- "\$cur") )
+      return 0
+      ;;
+    index)
+      if [[ \$COMP_CWORD -eq 2 ]]; then
+        COMPREPLY=( \$(compgen -W "\$index_subs" -- "\$cur") )
+      else
+        case "\${COMP_WORDS[2]}" in
+          create)
+            COMPREPLY=( \$(compgen -W "--db --collection --field --dimensions --similarity --index-name --json --quiet --help" -- "\$cur") )
+            ;;
+          list)
+            COMPREPLY=( \$(compgen -W "--db --collection --json --quiet --help" -- "\$cur") )
+            ;;
+          delete)
+            COMPREPLY=( \$(compgen -W "--db --collection --index-name --json --quiet --help" -- "\$cur") )
+            ;;
+        esac
+      fi
+      return 0
+      ;;
+    models)
+      COMPREPLY=( \$(compgen -W "--type --json --quiet --help" -- "\$cur") )
+      return 0
+      ;;
+    ping)
+      COMPREPLY=( \$(compgen -W "--json --quiet --help" -- "\$cur") )
+      return 0
+      ;;
+    config)
+      if [[ \$COMP_CWORD -eq 2 ]]; then
+        COMPREPLY=( \$(compgen -W "\$config_subs" -- "\$cur") )
+      else
+        case "\${COMP_WORDS[2]}" in
+          set)
+            COMPREPLY=( \$(compgen -W "api-key mongodb-uri base-url default-model --stdin --help" -- "\$cur") )
+            ;;
+          get|delete)
+            COMPREPLY=( \$(compgen -W "api-key mongodb-uri base-url default-model --help" -- "\$cur") )
+            ;;
+        esac
+      fi
+      return 0
+      ;;
+    demo)
+      COMPREPLY=( \$(compgen -W "--no-pause --skip-pipeline --keep --json --quiet --help" -- "\$cur") )
+      return 0
+      ;;
+    explain)
+      COMPREPLY=( \$(compgen -W "embeddings reranking vector-search rag cosine-similarity two-stage-retrieval input-type models api-keys api-access batch-processing --help" -- "\$cur") )
+      return 0
+      ;;
+    similarity)
+      COMPREPLY=( \$(compgen -W "--against --file1 --file2 --model --dimensions --json --quiet --help" -- "\$cur") )
+      return 0
+      ;;
+    ingest)
+      COMPREPLY=( \$(compgen -W "--file --db --collection --field --model --input-type --dimensions --batch-size --text-field --text-column --strict --dry-run --json --quiet --help" -- "\$cur") )
+      return 0
+      ;;
+    completions)
+      COMPREPLY=( \$(compgen -W "bash zsh --help" -- "\$cur") )
+      return 0
+      ;;
+  esac
+
+  # Complete top-level commands and global flags
+  if [[ \$COMP_CWORD -eq 1 ]]; then
+    COMPREPLY=( \$(compgen -W "\$commands \$global_flags" -- "\$cur") )
+    return 0
+  fi
+
+  # Model name completions
+  case "\$prev" in
+    --model|-m)
+      COMPREPLY=( \$(compgen -W "voyage-4-large voyage-4 voyage-4-lite voyage-code-3 voyage-finance-2 voyage-law-2 voyage-multimodal-3.5 rerank-2.5 rerank-2.5-lite" -- "\$cur") )
+      return 0
+      ;;
+    --input-type)
+      COMPREPLY=( \$(compgen -W "query document" -- "\$cur") )
+      return 0
+      ;;
+    --type|-t)
+      COMPREPLY=( \$(compgen -W "embedding reranking all" -- "\$cur") )
+      return 0
+      ;;
+    --similarity|-s)
+      COMPREPLY=( \$(compgen -W "cosine dotProduct euclidean" -- "\$cur") )
+      return 0
+      ;;
+    --output-format|-o)
+      COMPREPLY=( \$(compgen -W "json array" -- "\$cur") )
+      return 0
+      ;;
+    --file|-f|--documents-file|--file1|--file2)
+      COMPREPLY=( \$(compgen -f -- "\$cur") )
+      return 0
+      ;;
+  esac
+}
+
+complete -F _vai_completions vai
+`;
+}
+
+/**
+ * Generate zsh completion script for vai CLI.
+ * @returns {string}
+ */
+function generateZshCompletions() {
+  return `#compdef vai
+# vai zsh completion script
+# Install: vai completions zsh > ~/.zsh/completions/_vai && source ~/.zshrc
+# Or:      vai completions zsh > /usr/local/share/zsh/site-functions/_vai
+
+_vai() {
+  local -a commands
+  commands=(
+    'embed:Generate embeddings for text'
+    'rerank:Rerank documents against a query'
+    'store:Embed text and store in MongoDB Atlas'
+    'search:Vector search against Atlas collection'
+    'index:Manage Atlas Vector Search indexes'
+    'models:List available Voyage AI models'
+    'ping:Test connectivity to Voyage AI API'
+    'config:Manage persistent configuration'
+    'demo:Interactive guided walkthrough'
+    'explain:Learn about AI and vector search concepts'
+    'similarity:Compute cosine similarity between texts'
+    'ingest:Bulk import documents with progress'
+    'completions:Generate shell completion scripts'
+    'help:Display help for command'
+  )
+
+  local -a models
+  models=(voyage-4-large voyage-4 voyage-4-lite voyage-code-3 voyage-finance-2 voyage-law-2 voyage-multimodal-3.5 rerank-2.5 rerank-2.5-lite)
+
+  local -a explain_topics
+  explain_topics=(embeddings reranking vector-search rag cosine-similarity two-stage-retrieval input-type models api-keys api-access batch-processing)
+
+  _arguments -C \\
+    '(-V --version)'{-V,--version}'[output the version number]' \\
+    '(-h --help)'{-h,--help}'[display help]' \\
+    '1:command:->command' \\
+    '*::arg:->args'
+
+  case \$state in
+    command)
+      _describe 'vai command' commands
+      ;;
+    args)
+      case \$words[1] in
+        embed)
+          _arguments \\
+            '(-m --model)'{-m,--model}'[Embedding model]:model:(\$models)' \\
+            '(-t --input-type)'{-t,--input-type}'[Input type]:type:(query document)' \\
+            '(-d --dimensions)'{-d,--dimensions}'[Output dimensions]:dimensions:' \\
+            '(-f --file)'{-f,--file}'[Read text from file]:file:_files' \\
+            '(-o --output-format)'{-o,--output-format}'[Output format]:format:(json array)' \\
+            '--json[Machine-readable JSON output]' \\
+            '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]' \\
+            '1:text:'
+          ;;
+        rerank)
+          _arguments \\
+            '--query[Search query]:query:' \\
+            '--documents[Documents to rerank]:document:' \\
+            '--documents-file[File with documents]:file:_files' \\
+            '(-m --model)'{-m,--model}'[Reranking model]:model:(\$models)' \\
+            '(-k --top-k)'{-k,--top-k}'[Return top K results]:k:' \\
+            '--json[Machine-readable JSON output]' \\
+            '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
+          ;;
+        store)
+          _arguments \\
+            '--db[Database name]:database:' \\
+            '--collection[Collection name]:collection:' \\
+            '--field[Embedding field name]:field:' \\
+            '--text[Text to embed and store]:text:' \\
+            '(-f --file)'{-f,--file}'[File to embed and store]:file:_files' \\
+            '(-m --model)'{-m,--model}'[Embedding model]:model:(\$models)' \\
+            '--input-type[Input type]:type:(query document)' \\
+            '(-d --dimensions)'{-d,--dimensions}'[Output dimensions]:dimensions:' \\
+            '--metadata[Additional metadata as JSON]:json:' \\
+            '--json[Machine-readable JSON output]' \\
+            '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
+          ;;
+        search)
+          _arguments \\
+            '--query[Search query text]:query:' \\
+            '--db[Database name]:database:' \\
+            '--collection[Collection name]:collection:' \\
+            '--index[Vector search index name]:index:' \\
+            '--field[Embedding field name]:field:' \\
+            '(-m --model)'{-m,--model}'[Embedding model]:model:(\$models)' \\
+            '--input-type[Input type]:type:(query document)' \\
+            '(-d --dimensions)'{-d,--dimensions}'[Output dimensions]:dimensions:' \\
+            '(-l --limit)'{-l,--limit}'[Maximum results]:limit:' \\
+            '--min-score[Minimum similarity score]:score:' \\
+            '--num-candidates[Number of ANN candidates]:n:' \\
+            '--filter[Pre-filter JSON]:json:' \\
+            '--json[Machine-readable JSON output]' \\
+            '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
+          ;;
+        index)
+          local -a index_commands
+          index_commands=(
+            'create:Create a vector search index'
+            'list:List vector search indexes'
+            'delete:Delete a vector search index'
+          )
+          _arguments -C \\
+            '1:index command:->index_command' \\
+            '*::arg:->index_args'
+          case \$state in
+            index_command)
+              _describe 'index command' index_commands
+              ;;
+            index_args)
+              case \$words[1] in
+                create)
+                  _arguments \\
+                    '--db[Database name]:database:' \\
+                    '--collection[Collection name]:collection:' \\
+                    '--field[Embedding field name]:field:' \\
+                    '(-d --dimensions)'{-d,--dimensions}'[Vector dimensions]:dimensions:' \\
+                    '(-s --similarity)'{-s,--similarity}'[Similarity function]:similarity:(cosine dotProduct euclidean)' \\
+                    '(-n --index-name)'{-n,--index-name}'[Index name]:name:' \\
+                    '--json[Machine-readable JSON output]' \\
+                    '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
+                  ;;
+                list)
+                  _arguments \\
+                    '--db[Database name]:database:' \\
+                    '--collection[Collection name]:collection:' \\
+                    '--json[Machine-readable JSON output]' \\
+                    '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
+                  ;;
+                delete)
+                  _arguments \\
+                    '--db[Database name]:database:' \\
+                    '--collection[Collection name]:collection:' \\
+                    '--index-name[Index name]:name:' \\
+                    '--json[Machine-readable JSON output]' \\
+                    '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
+                  ;;
+              esac
+              ;;
+          esac
+          ;;
+        models)
+          _arguments \\
+            '(-t --type)'{-t,--type}'[Filter by type]:type:(embedding reranking all)' \\
+            '--json[Machine-readable JSON output]' \\
+            '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
+          ;;
+        ping)
+          _arguments \\
+            '--json[Machine-readable JSON output]' \\
+            '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
+          ;;
+        config)
+          local -a config_commands
+          config_commands=(
+            'set:Set a config value'
+            'get:Show current configuration'
+            'delete:Remove a config value'
+            'path:Show config file path'
+            'reset:Reset all configuration'
+          )
+          _arguments -C \\
+            '1:config command:->config_command' \\
+            '*::arg:->config_args'
+          case \$state in
+            config_command)
+              _describe 'config command' config_commands
+              ;;
+            config_args)
+              case \$words[1] in
+                set)
+                  _arguments \\
+                    '1:key:(api-key mongodb-uri base-url default-model)' \\
+                    '2:value:' \\
+                    '--stdin[Read value from stdin]'
+                  ;;
+                delete)
+                  _arguments \\
+                    '1:key:(api-key mongodb-uri base-url default-model)'
+                  ;;
+              esac
+              ;;
+          esac
+          ;;
+        demo)
+          _arguments \\
+            '--no-pause[Skip pauses between steps]' \\
+            '--skip-pipeline[Skip MongoDB pipeline steps]' \\
+            '--keep[Keep demo data after completion]' \\
+            '--json[Machine-readable JSON output]' \\
+            '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
+          ;;
+        explain)
+          _arguments \\
+            '1:topic:(\$explain_topics)'
+          ;;
+        similarity)
+          _arguments \\
+            '--against[Compare against multiple texts]:text:' \\
+            '--file1[Read text A from file]:file:_files' \\
+            '--file2[Read text B from file]:file:_files' \\
+            '(-m --model)'{-m,--model}'[Embedding model]:model:(\$models)' \\
+            '--dimensions[Output dimensions]:dimensions:' \\
+            '--json[Machine-readable JSON output]' \\
+            '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]' \\
+            '*:text:'
+          ;;
+        ingest)
+          _arguments \\
+            '--file[Input file]:file:_files' \\
+            '--db[Database name]:database:' \\
+            '--collection[Collection name]:collection:' \\
+            '--field[Embedding field name]:field:' \\
+            '(-m --model)'{-m,--model}'[Embedding model]:model:(\$models)' \\
+            '--input-type[Input type]:type:(query document)' \\
+            '(-d --dimensions)'{-d,--dimensions}'[Output dimensions]:dimensions:' \\
+            '--batch-size[Documents per batch]:size:' \\
+            '--text-field[JSON field containing text]:field:' \\
+            '--text-column[CSV column to embed]:column:' \\
+            '--strict[Abort on first batch error]' \\
+            '--dry-run[Validate only, no API calls]' \\
+            '--json[Machine-readable JSON output]' \\
+            '(-q --quiet)'{-q,--quiet}'[Suppress non-essential output]'
+          ;;
+        completions)
+          _arguments \\
+            '1:shell:(bash zsh)'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_vai "\$@"
+`;
+}
+
+/**
+ * Show installation instructions for shell completions.
+ * @param {string} shell - 'bash' or 'zsh'
+ */
+function showInstallInstructions(shell) {
+  console.log('');
+  if (shell === 'bash') {
+    console.log(`  ${pc.bold('Install bash completions:')}`);
+    console.log('');
+    console.log(`  ${pc.cyan('# Add to your ~/.bashrc (or ~/.bash_profile on macOS)')}`);
+    console.log(`  ${pc.white('vai completions bash >> ~/.bashrc')}`);
+    console.log(`  ${pc.white('source ~/.bashrc')}`);
+    console.log('');
+    console.log(`  ${pc.cyan('# Or install system-wide (Linux)')}`);
+    console.log(`  ${pc.white('vai completions bash > /etc/bash_completion.d/vai')}`);
+    console.log('');
+    console.log(`  ${pc.cyan('# Or with Homebrew (macOS)')}`);
+    console.log(`  ${pc.white('vai completions bash > $(brew --prefix)/etc/bash_completion.d/vai')}`);
+  } else {
+    console.log(`  ${pc.bold('Install zsh completions:')}`);
+    console.log('');
+    console.log(`  ${pc.cyan('# Create completions directory if needed')}`);
+    console.log(`  ${pc.white('mkdir -p ~/.zsh/completions')}`);
+    console.log('');
+    console.log(`  ${pc.cyan('# Add to fpath in your ~/.zshrc (if not already there)')}`);
+    console.log(`  ${pc.white('echo \'fpath=(~/.zsh/completions $fpath)\' >> ~/.zshrc')}`);
+    console.log(`  ${pc.white('echo \'autoload -Uz compinit && compinit\' >> ~/.zshrc')}`);
+    console.log('');
+    console.log(`  ${pc.cyan('# Generate the completion file')}`);
+    console.log(`  ${pc.white('vai completions zsh > ~/.zsh/completions/_vai')}`);
+    console.log(`  ${pc.white('source ~/.zshrc')}`);
+    console.log('');
+    console.log(`  ${pc.cyan('# Or install system-wide')}`);
+    console.log(`  ${pc.white('vai completions zsh > /usr/local/share/zsh/site-functions/_vai')}`);
+  }
+  console.log('');
+}
+
+/**
+ * Register the completions command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerCompletions(program) {
+  program
+    .command('completions [shell]')
+    .description('Generate shell completion scripts (bash or zsh)')
+    .action((shell) => {
+      if (!shell) {
+        console.log('');
+        console.log(`  ${pc.bold('Usage:')} vai completions ${pc.cyan('<bash|zsh>')}`);
+        console.log('');
+        console.log('  Outputs a completion script for the specified shell.');
+        console.log('  Redirect the output to the appropriate file for your shell.');
+        console.log('');
+        showInstallInstructions('bash');
+        showInstallInstructions('zsh');
+        return;
+      }
+
+      const normalized = shell.toLowerCase().trim();
+
+      if (normalized === 'bash') {
+        process.stdout.write(generateBashCompletions());
+      } else if (normalized === 'zsh') {
+        process.stdout.write(generateZshCompletions());
+      } else {
+        console.error(`  ${pc.red('✗')} Unknown shell: ${shell}. Supported: bash, zsh`);
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = { registerCompletions, generateBashCompletions, generateZshCompletions };

package/src/commands/models.js

@@ -1,10 +1,36 @@
 'use strict';
 
 const { MODEL_CATALOG } = require('../lib/catalog');
-const { API_BASE } = require('../lib/api');
+const { getApiBase } = require('../lib/api');
 const { formatTable } = require('../lib/format');
 const ui = require('../lib/ui');
 
+/**
+ * Shorten dimensions string for compact display.
+ * "1024 (default), 256, 512, 2048" → "1024*"
+ * "1024" → "1024"
+ * "—" → "—"
+ * @param {string} dims
+ * @returns {string}
+ */
+function compactDimensions(dims) {
+  if (dims === '—') return dims;
+  const match = dims.match(/^(\d+)\s*\(default\)/);
+  if (match) return match[1] + '*';
+  return dims;
+}
+
+/**
+ * Shorten price string for compact display.
+ * "$0.12/1M tokens" → "$0.12/1M"
+ * "$0.12/M + $0.60/B px" → "$0.12/M+$0.60/Bpx"
+ * @param {string} price
+ * @returns {string}
+ */
+function compactPrice(price) {
+  return price.replace('/1M tokens', '/1M').replace(' + ', '+').replace('/B px', '/Bpx');
+}
+
 /**
  * Register the models command on a Commander program.
  * @param {import('commander').Command} program
@@ -14,6 +40,7 @@ function registerModels(program) {
     .command('models')
     .description('List available Voyage AI models')
     .option('-t, --type <type>', 'Filter by type: embedding, reranking, or all', 'all')
+    .option('-w, --wide', 'Wide output (show all columns untruncated)')
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
     .action((opts) => {
@@ -33,28 +60,49 @@ function registerModels(program) {
         return;
       }
 
+      const apiBase = getApiBase();
+
       if (!opts.quiet) {
         console.log(ui.bold('Voyage AI Models'));
-        console.log(ui.dim(`(via MongoDB AI API — ${API_BASE})`));
+        console.log(ui.dim(`(via ${apiBase})`));
         console.log('');
       }
 
-      const headers = ['Model', 'Type', 'Context', 'Dimensions', 'Price', 'Best For'];
-      const rows = models.map(m => {
-        const name = ui.cyan(m.name);
-        const type = m.type === '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];
-      });
-
-      // Use bold headers
-      const boldHeaders = headers.map(h => ui.bold(h));
-      console.log(formatTable(boldHeaders, rows));
+      if (opts.wide) {
+        // Full table with all details
+        const headers = ['Model', 'Type', 'Context', 'Dimensions', 'Price', 'Best For'];
+        const rows = models.map(m => {
+          const name = ui.cyan(m.name);
+          const type = m.type === '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 boldHeaders = headers.map(h => ui.bold(h));
+        console.log(formatTable(boldHeaders, rows));
+      } else {
+        // Compact table — fits in 80 cols
+        const headers = ['Model', 'Type', 'Dims', 'Price', 'Use Case'];
+        const rows = models.map(m => {
+          const name = ui.cyan(m.name);
+          const type = m.type === 'embedding' ? ui.green('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];
+        });
+        const boldHeaders = headers.map(h => ui.bold(h));
+        console.log(formatTable(boldHeaders, rows));
+      }
 
       if (!opts.quiet) {
         console.log('');
+        if (!opts.wide) {
+          console.log(ui.dim('* = also supports 256, 512, 2048 dimensions'));
+        }
         console.log(ui.dim('Free tier: 200M tokens (most models), 50M (domain-specific)'));
         console.log(ui.dim('All 4-series models share the same embedding space.'));
+        if (!opts.wide) {
+          console.log(ui.dim('Use --wide for full details.'));
+        }
       }
     });
 }

package/src/commands/ping.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { API_BASE, requireApiKey } = require('../lib/api');
+const { getApiBase, requireApiKey } = require('../lib/api');
 const ui = require('../lib/ui');
 
 /**
@@ -28,6 +28,7 @@ function registerPing(program) {
       const useColor = !opts.json;
       const useSpinner = useColor && !opts.quiet;
 
+      const apiBase = getApiBase();
       const model = 'voyage-4-lite';
       const startTime = Date.now();
 
@@ -38,7 +39,7 @@ function registerPing(program) {
       }
 
       try {
-        const response = await fetch(`${API_BASE}/embeddings`, {
+        const response = await fetch(`${apiBase}/embeddings`, {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json',
@@ -83,7 +84,7 @@ function registerPing(program) {
         const dims = data.data && data.data[0] ? data.data[0].embedding.length : 'unknown';
         const tokens = data.usage ? data.usage.total_tokens : 'unknown';
 
-        results.voyage = { ok: true, elapsed, model, dimensions: dims, tokens, endpoint: API_BASE };
+        results.voyage = { ok: true, elapsed, model, dimensions: dims, tokens, endpoint: apiBase };
 
         if (spin) spin.stop();
 
@@ -93,7 +94,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', API_BASE));
+          console.log(ui.label('Endpoint', apiBase));
           console.log(ui.label('Model', model));
           console.log(ui.label('Dimensions', String(dims)));
           console.log(ui.label('Tokens', String(tokens)));

package/src/lib/api.js

@@ -1,8 +1,32 @@
 'use strict';
 
-const API_BASE = 'https://ai.mongodb.com/v1';
+const ATLAS_API_BASE = 'https://ai.mongodb.com/v1';
+const VOYAGE_API_BASE = 'https://api.voyageai.com/v1';
 const MAX_RETRIES = 3;
 
+/**
+ * Resolve the API base URL.
+ * Priority: VOYAGE_API_BASE env → config baseUrl → auto-detect from key prefix.
+ * Keys starting with 'pa-' that work on Voyage platform use VOYAGE_API_BASE.
+ * @returns {string}
+ */
+function getApiBase() {
+  const { getConfigValue } = require('./config');
+
+  // Explicit override wins
+  const envBase = process.env.VOYAGE_API_BASE;
+  if (envBase) return envBase.replace(/\/+$/, '');
+
+  const configBase = getConfigValue('baseUrl');
+  if (configBase) return configBase.replace(/\/+$/, '');
+
+  // Default to Atlas endpoint
+  return ATLAS_API_BASE;
+}
+
+// Legacy export for backward compat
+const API_BASE = ATLAS_API_BASE;
+
 /**
  * Get the Voyage API key or exit with a helpful error.
  * Checks: env var → config file.
@@ -18,6 +42,7 @@ function requireApiKey() {
     console.error('Option 2: vai config set api-key <your-key>');
     console.error('');
     console.error('Get one from MongoDB Atlas → AI Models → Create model API key');
+    console.error('       or Voyage AI platform → Dashboard → API Keys');
     process.exit(1);
   }
   return key;
@@ -40,7 +65,8 @@ function sleep(ms) {
  */
 async function apiRequest(endpoint, body) {
   const apiKey = requireApiKey();
-  const url = `${API_BASE}${endpoint}`;
+  const base = getApiBase();
+  const url = `${base}${endpoint}`;
 
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
     const response = await fetch(url, {
@@ -69,6 +95,23 @@ async function apiRequest(endpoint, body) {
         errorDetail = await response.text();
       }
       console.error(`API Error (${response.status}): ${errorDetail}`);
+
+      // Help users diagnose endpoint mismatch
+      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.');
+      } 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/');
+      }
       process.exit(1);
     }
 
@@ -105,6 +148,9 @@ async function generateEmbeddings(texts, options = {}) {
 
 module.exports = {
   API_BASE,
+  ATLAS_API_BASE,
+  VOYAGE_API_BASE,
+  getApiBase,
   requireApiKey,
   apiRequest,
   generateEmbeddings,

package/src/lib/catalog.js

@@ -24,16 +24,16 @@ function getDefaultDimensions() {
 
 /** @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' },
+  { name: 'voyage-4-large', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.12/1M tokens', bestFor: 'Best quality, multilingual', shortFor: 'Best quality' },
+  { name: 'voyage-4', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.06/1M tokens', bestFor: 'Balanced quality/perf', shortFor: 'Balanced' },
+  { name: 'voyage-4-lite', type: 'embedding', context: '32K', dimensions: '1024 (default), 256, 512, 2048', price: '$0.02/1M tokens', bestFor: 'Lowest cost', shortFor: 'Budget' },
+  { 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: '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' },
 ];
 
 module.exports = {

package/src/lib/config.js

@@ -13,6 +13,7 @@ const KEY_MAP = {
   'mongodb-uri': 'mongodbUri',
   'default-model': 'defaultModel',
   'default-dimensions': 'defaultDimensions',
+  'base-url': 'baseUrl',
 };
 
 // Keys whose values should be masked in output

package/test/commands/completions.test.js

@@ -0,0 +1,166 @@
+'use strict';
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const { Command } = require('commander');
+const { registerCompletions, generateBashCompletions, generateZshCompletions } = require('../../src/commands/completions');
+
+describe('completions command', () => {
+  let originalLog;
+  let originalWrite;
+  let originalError;
+  let originalExit;
+  let output;
+  let stdoutOutput;
+  let stderrOutput;
+
+  beforeEach(() => {
+    originalLog = console.log;
+    originalWrite = process.stdout.write;
+    originalError = console.error;
+    originalExit = process.exit;
+    output = [];
+    stdoutOutput = [];
+    stderrOutput = [];
+    console.log = (...args) => output.push(args.join(' '));
+    process.stdout.write = (data) => { stdoutOutput.push(data); return true; };
+    console.error = (...args) => stderrOutput.push(args.join(' '));
+    process.exit = (code) => { throw new Error(`EXIT_${code}`); };
+  });
+
+  afterEach(() => {
+    console.log = originalLog;
+    process.stdout.write = originalWrite;
+    console.error = originalError;
+    process.exit = originalExit;
+  });
+
+  it('registers correctly on a program', () => {
+    const program = new Command();
+    registerCompletions(program);
+    const cmd = program.commands.find(c => c.name() === 'completions');
+    assert.ok(cmd, 'completions command should be registered');
+    assert.ok(cmd.description().includes('completion'), 'should have a description about completions');
+  });
+
+  it('shows usage when called without shell argument', async () => {
+    const program = new Command();
+    program.exitOverride();
+    registerCompletions(program);
+
+    await program.parseAsync(['node', 'test', 'completions']);
+
+    const combined = output.join('\n');
+    assert.ok(combined.includes('bash'), 'should mention bash');
+    assert.ok(combined.includes('zsh'), 'should mention zsh');
+  });
+
+  it('outputs bash completion script', async () => {
+    const program = new Command();
+    program.exitOverride();
+    registerCompletions(program);
+
+    await program.parseAsync(['node', 'test', 'completions', 'bash']);
+
+    const combined = stdoutOutput.join('');
+    assert.ok(combined.includes('_vai_completions'), 'should contain bash completion function');
+    assert.ok(combined.includes('complete -F _vai_completions vai'), 'should register completion');
+  });
+
+  it('outputs zsh completion script', async () => {
+    const program = new Command();
+    program.exitOverride();
+    registerCompletions(program);
+
+    await program.parseAsync(['node', 'test', 'completions', 'zsh']);
+
+    const combined = stdoutOutput.join('');
+    assert.ok(combined.includes('#compdef vai'), 'should contain zsh compdef header');
+    assert.ok(combined.includes('_vai'), 'should contain zsh completion function');
+  });
+
+  it('rejects unknown shell', async () => {
+    const program = new Command();
+    program.exitOverride();
+    registerCompletions(program);
+
+    await assert.rejects(
+      () => program.parseAsync(['node', 'test', 'completions', 'fish']),
+      /EXIT_1/,
+      'should exit with code 1 for unsupported shell'
+    );
+    const combined = stderrOutput.join('\n');
+    assert.ok(combined.includes('fish'), 'should mention the unknown shell name');
+  });
+});
+
+describe('generateBashCompletions', () => {
+  it('includes all 14 commands (including completions)', () => {
+    const script = generateBashCompletions();
+    const commands = ['embed', 'rerank', 'store', 'search', 'index', 'models', 'ping', 'config', 'demo', 'explain', 'similarity', 'ingest', 'completions', 'help'];
+    for (const cmd of commands) {
+      assert.ok(script.includes(cmd), `should include command: ${cmd}`);
+    }
+  });
+
+  it('includes model completions', () => {
+    const script = generateBashCompletions();
+    assert.ok(script.includes('voyage-4-large'), 'should include voyage-4-large model');
+    assert.ok(script.includes('rerank-2.5'), 'should include rerank-2.5 model');
+  });
+
+  it('includes flag completions for embed', () => {
+    const script = generateBashCompletions();
+    assert.ok(script.includes('--model'), 'should include --model flag');
+    assert.ok(script.includes('--dimensions'), 'should include --dimensions flag');
+    assert.ok(script.includes('--input-type'), 'should include --input-type flag');
+  });
+
+  it('includes index subcommands', () => {
+    const script = generateBashCompletions();
+    assert.ok(script.includes('create list delete'), 'should include index subcommands');
+  });
+
+  it('includes config subcommands', () => {
+    const script = generateBashCompletions();
+    assert.ok(script.includes('set get delete path reset'), 'should include config subcommands');
+  });
+
+  it('includes input-type values', () => {
+    const script = generateBashCompletions();
+    assert.ok(script.includes('query document'), 'should include input-type values');
+  });
+});
+
+describe('generateZshCompletions', () => {
+  it('includes compdef header', () => {
+    const script = generateZshCompletions();
+    assert.ok(script.startsWith('#compdef vai'), 'should start with #compdef vai');
+  });
+
+  it('includes all commands with descriptions', () => {
+    const script = generateZshCompletions();
+    const commands = ['embed', 'rerank', 'store', 'search', 'index', 'models', 'ping', 'config', 'demo', 'explain', 'similarity', 'ingest', 'completions'];
+    for (const cmd of commands) {
+      assert.ok(script.includes(`'${cmd}:`), `should include command with description: ${cmd}`);
+    }
+  });
+
+  it('includes model names', () => {
+    const script = generateZshCompletions();
+    assert.ok(script.includes('voyage-4-large'), 'should include voyage-4-large model');
+    assert.ok(script.includes('voyage-code-3'), 'should include voyage-code-3 model');
+  });
+
+  it('includes explain topics', () => {
+    const script = generateZshCompletions();
+    assert.ok(script.includes('embeddings'), 'should include embeddings topic');
+    assert.ok(script.includes('cosine-similarity'), 'should include cosine-similarity topic');
+    assert.ok(script.includes('batch-processing'), 'should include batch-processing topic');
+  });
+
+  it('includes file completion for --file flags', () => {
+    const script = generateZshCompletions();
+    assert.ok(script.includes('_files'), 'should use _files completion');
+  });
+});

package/test/commands/ping.test.js

@@ -105,8 +105,17 @@ describe('ping command', () => {
     assert.ok(combined.includes('Authentication failed'), 'Should show auth error');
   });
 
-  it('exits when VOYAGE_API_KEY is not set', async () => {
+  it('exits when VOYAGE_API_KEY is not set and no config', async () => {
     delete process.env.VOYAGE_API_KEY;
+    // Mock config to return nothing so the key isn't found in ~/.vai/config.json
+    delete require.cache[require.resolve('../../src/lib/config')];
+    delete require.cache[require.resolve('../../src/lib/api')];
+    delete require.cache[require.resolve('../../src/commands/ping')];
+    const config = require('../../src/lib/config');
+    const origGetConfigValue = config.getConfigValue;
+    config.getConfigValue = () => undefined;
+
+    const { registerPing: registerPingFresh } = require('../../src/commands/ping');
 
     let exitCode = null;
     process.exit = (code) => {
@@ -116,16 +125,20 @@ describe('ping command', () => {
 
     const program = new Command();
     program.exitOverride();
-    registerPing(program);
-
-    await assert.rejects(
-      () => program.parseAsync(['node', 'test', 'ping']),
-      /process\.exit called/
-    );
-
-    assert.equal(exitCode, 1);
-    const combined = errorOutput.join('\n');
-    assert.ok(combined.includes('VOYAGE_API_KEY'), 'Should mention missing key');
+    registerPingFresh(program);
+
+    try {
+      await assert.rejects(
+        () => program.parseAsync(['node', 'test', 'ping']),
+        /process\.exit called/
+      );
+
+      assert.equal(exitCode, 1);
+      const combined = errorOutput.join('\n');
+      assert.ok(combined.includes('VOYAGE_API_KEY'), 'Should mention missing key');
+    } finally {
+      config.getConfigValue = origGetConfigValue;
+    }
   });
 
   it('outputs JSON when --json flag is used', async () => {

package/test/lib/api.test.js

@@ -25,8 +25,13 @@ describe('api', () => {
   describe('requireApiKey', () => {
     it('throws/exits when VOYAGE_API_KEY is not set', () => {
       delete process.env.VOYAGE_API_KEY;
-      // Re-require to get fresh module
+      // Re-require to get fresh modules (clear config cache too)
       delete require.cache[require.resolve('../../src/lib/api')];
+      delete require.cache[require.resolve('../../src/lib/config')];
+      const config = require('../../src/lib/config');
+      const originalGetConfigValue = config.getConfigValue;
+      config.getConfigValue = () => undefined;
+
       const { requireApiKey } = require('../../src/lib/api');
 
       let exitCode = null;
@@ -35,8 +40,12 @@ describe('api', () => {
         throw new Error('process.exit called');
       };
 
-      assert.throws(() => requireApiKey(), /process\.exit called/);
-      assert.equal(exitCode, 1);
+      try {
+        assert.throws(() => requireApiKey(), /process\.exit called/);
+        assert.equal(exitCode, 1);
+      } finally {
+        config.getConfigValue = originalGetConfigValue;
+      }
     });
 
     it('returns key when VOYAGE_API_KEY is set', () => {