voyageai-cli 1.4.0 → 1.6.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.6.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/embed.js

@@ -17,6 +17,8 @@ function registerEmbed(program) {
     .option('-t, --input-type <type>', 'Input type: query or document')
     .option('-d, --dimensions <n>', 'Output dimensions', (v) => parseInt(v, 10))
     .option('-f, --file <path>', 'Read text from file')
+    .option('--truncation', 'Enable truncation for long inputs')
+    .option('--no-truncation', 'Disable truncation')
     .option('-o, --output-format <format>', 'Output format: json or array', 'json')
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
@@ -26,17 +28,29 @@ function registerEmbed(program) {
 
         const useColor = !opts.json;
         const useSpinner = useColor && !opts.quiet;
+
+        // Show hint when --input-type is not provided and output is interactive
+        if (!opts.inputType && !opts.json && !opts.quiet && process.stdout.isTTY) {
+          console.error(ui.dim('ℹ Tip: Use --input-type query or --input-type document for better retrieval accuracy.'));
+        }
+
         let spin;
         if (useSpinner) {
           spin = ui.spinner('Generating embeddings...');
           spin.start();
         }
 
-        const result = await generateEmbeddings(texts, {
+        const embedOpts = {
           model: opts.model,
           inputType: opts.inputType,
           dimensions: opts.dimensions,
-        });
+        };
+        // Only pass truncation when explicitly set via --truncation or --no-truncation
+        if (opts.truncation !== undefined) {
+          embedOpts.truncation = opts.truncation;
+        }
+
+        const result = await generateEmbeddings(texts, embedOpts);
 
         if (spin) spin.stop();