voyageai-cli 1.28.0 → 1.30.0

package/README.md

@@ -38,27 +38,34 @@ vai quickstart    # Interactive tutorial — zero to semantic search in 2 minute
 
 <table>
 <tr>
-<td align="center" width="33%">
+<td align="center" width="25%">
 <h3>🖥️ CLI</h3>
 <code>vai</code><br/><br/>
 22 commands · 5 chunking strategies<br/>
 End-to-end RAG pipeline from your terminal<br/><br/>
-<code>npm install -g voyageai-cli</code>
+<code>curl -fsSL https://vaicli.com/install.sh | sh</code>
 </td>
-<td align="center" width="33%">
+<td align="center" width="25%">
 <h3>🌐 Web Playground</h3>
 <code>vai playground</code><br/><br/>
-7 interactive tabs for embedding,<br/>
-comparing, searching, and benchmarking<br/><br/>
+7 interactive tabs + Workflow Store<br/>
+with 20+ installable workflow packages<br/><br/>
 <em>Launches in your browser</em>
 </td>
-<td align="center" width="33%">
+<td align="center" width="25%">
 <h3>💻 Desktop App</h3>
 Standalone Electron app<br/><br/>
 Secure keychain storage, dark/light themes,<br/>
 MongoDB LeafyGreen design system<br/><br/>
 <a href="https://github.com/mrlynn/voyageai-cli/releases">Download from GitHub Releases</a>
 </td>
+<td align="center" width="25%">
+<h3>🏪 Workflow Store</h3>
+<code>vai store</code> or Playground<br/><br/>
+Browse, install, and run pre-built<br/>
+RAG workflows from npm<br/><br/>
+<em>Official + community packages</em>
+</td>
 </tr>
 </table>
 
@@ -81,6 +88,7 @@ MongoDB LeafyGreen design system<br/><br/>
   - [Environment & Auth](#environment--auth)
   - [Shell Completions](#shell-completions)
   - [All Commands](#all-commands)
+- [Workflow Store](#workflow-store)
 - [MCP Server](#mcp-server)
 - [Screenshots](#screenshots)
 - [Requirements](#requirements)
@@ -115,6 +123,8 @@ Download the latest release for your platform from [GitHub Releases](https://git
 | Windows | `.exe` installer |
 | Linux | `.AppImage` / `.deb` |
 
+> **Prefer the CLI?** Install with `curl -fsSL https://vaicli.com/install.sh | sh` or `brew install mrlynn/vai/vai`
+
 ---
 
 ## Web Playground
@@ -125,7 +135,7 @@ An interactive, browser-based interface for exploring Voyage AI embeddings witho
 vai playground
 ```
 
-Your default browser opens with a full-featured UI organized into **7 tabs**:
+Your default browser opens with a full-featured UI:
 
 | Tab | What It Does |
 |-----|-------------|
@@ -134,6 +144,7 @@ Your default browser opens with a full-featured UI organized into **7 tabs**:
 | **Search** | Connect to MongoDB Atlas and run vector similarity searches with filters and reranking |
 | **Benchmark** | Compare model latency, cost, and quality across the Voyage 4 family on your own data |
 | **Explore** | Visualize embedding spaces with dimensionality reduction (PCA/t-SNE) and clustering |
+| **Workflow Store** | Browse, install, and run 20+ official and community workflow packages |
 | **About** | Project info, links, and version details |
 | **Settings** | Configure API keys, MongoDB URI, default model, and preferences |
 
@@ -143,12 +154,19 @@ The playground connects to the same backend as the CLI. Any API keys or MongoDB
 
 ## CLI — Quick Start
 
-**22 commands · 312 tests · 5 chunking strategies · End-to-end RAG pipeline**
+**22 commands · 1,000+ tests · 5 chunking strategies · End-to-end RAG pipeline**
 
 ### Install
 
 ```bash
+# Fastest — one command, no dependencies
+curl -fsSL https://vaicli.com/install.sh | sh
+
+# Via npm
 npm install -g voyageai-cli
+
+# Via Homebrew
+brew install mrlynn/vai/vai
 ```
 
 ### 5-Minute RAG Pipeline
@@ -535,6 +553,11 @@ Covers all 22 commands, subcommands, flags, model names, and explain topics.
 | `vai eval` | Evaluate retrieval quality (MRR, nDCG, Recall) |
 | `vai eval compare` | Compare configurations side-by-side |
 | `vai benchmark` | 8 subcommands for model comparison |
+| **Workflow Store** | |
+| `vai store list` | Browse available workflows (official + community) |
+| `vai store install` | Install a workflow package from npm |
+| `vai store run` | Run an installed workflow |
+| `vai store uninstall` | Remove an installed workflow |
 | **MCP Server** | |
 | `vai mcp` | Start the MCP server (expose vai tools to AI agents) |
 | `vai mcp install` | Install vai into AI tool configs (Claude, Cursor, etc.) |
@@ -554,6 +577,57 @@ Covers all 22 commands, subcommands, flags, model names, and explain topics.
 
 ---
 
+## Workflow Store
+
+Browse, install, and run pre-built RAG workflows — from the Playground UI or the CLI. The Workflow Store features **20 official workflows** and a growing ecosystem of community packages published on npm.
+
+### Browse & Install
+
+```bash
+# Open the visual Workflow Store in the Playground
+vai playground    # Click the grid icon → Store
+
+# Or from the CLI
+vai store list                    # Browse available workflows
+vai store install model-shootout  # Install a workflow
+vai store run model-shootout      # Run it
+```
+
+### Official Workflows
+
+| Workflow | Category | What It Does |
+|----------|----------|-------------|
+| **model-shootout** | Utility | Compare voyage-4-large, voyage-4, and voyage-4-lite side-by-side on your data |
+| **asymmetric-search** | Retrieval | Embed with voyage-4-large, query with voyage-4-lite — ~83% cost reduction |
+| **cost-optimizer** | Utility | Quantify exact cost savings of asymmetric retrieval |
+| **question-decomposition** | Retrieval | Break complex questions into sub-queries, search in parallel, merge & rerank |
+| **knowledge-base-bootstrap** | Integration | End-to-end onboarding: ingest → verify → test query → status report |
+| **hybrid-precision-search** | Retrieval | Three retrieval strategies in parallel, merged and reranked |
+| **embedding-drift-detector** | Analysis | Monitor embedding quality over time |
+| **multilingual-search** | Retrieval | Translate queries into multiple languages, search each in parallel |
+
+Plus 12 more covering code migration, financial risk scanning, clinical protocol matching, meeting action items, and more.
+
+### Community Packages
+
+Anyone can publish a workflow to npm. Tag your package with `vai-workflow` and add a `vai-workflow` field to your `package.json`:
+
+```json
+{
+  "name": "vai-workflow-my-pipeline",
+  "keywords": ["vai-workflow"],
+  "vai-workflow": {
+    "category": "retrieval",
+    "tags": ["custom", "my-use-case"],
+    "tools": ["query", "rerank", "generate"]
+  }
+}
+```
+
+Community workflows appear automatically in the Store alongside official packages.
+
+---
+
 ## MCP Server
 
 Expose vai's RAG tools to any MCP-compatible AI agent — Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, and more. **11 tools** for embedding, retrieval, reranking, ingestion, and learning — all accessible without writing code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voyageai-cli",
-  "version": "1.28.0",
+  "version": "1.30.0",
   "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
   "bin": {
     "vai": "./src/cli.js"
@@ -42,6 +42,7 @@
   "dependencies": {
     "@clack/prompts": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "@vaicli/vai-workflow-model-shootout": "^1.0.0",
     "commander": "^12.0.0",
     "dotenv": "^17.2.3",
     "mongodb": "^6.0.0",

package/src/commands/app.js

@@ -138,6 +138,21 @@ function registerApp(program) {
       const electronPkg = path.join(electronDir, 'package.json');
 
       if (!fs.existsSync(electronPkg)) {
+        // Check for system-installed Vai.app on macOS
+        if (process.platform === 'darwin') {
+          const appPaths = [
+            '/Applications/Vai.app',
+            path.join(process.env.HOME || '', 'Applications', 'Vai.app'),
+          ];
+          const installed = appPaths.find((p) => fs.existsSync(p));
+          if (installed) {
+            console.log('🧭 Launching Vai desktop app...');
+            spawn('open', ['-a', installed], { stdio: 'ignore', detached: true }).unref();
+            setTimeout(() => process.exit(0), 500);
+            return;
+          }
+        }
+
         console.log('');
         console.log('🖥️  The Vai desktop app is not installed locally.');
         console.log('');

package/src/commands/benchmark.js

@@ -1112,6 +1112,20 @@ function formatBytes(bytes) {
  * Register the benchmark command tree on a Commander program.
  * @param {import('commander').Command} program
  */
+function withTelemetry(subcommand, fn) {
+  return async (...args) => {
+    const telemetry = require('../lib/telemetry');
+    const done = telemetry.timer('cli_benchmark', { subcommand });
+    try {
+      await fn(...args);
+      done();
+    } catch (err) {
+      telemetry.send('cli_error', { command: 'benchmark', errorType: err.constructor.name });
+      throw err;
+    }
+  };
+}
+
 function registerBenchmark(program) {
   const bench = program
     .command('benchmark')
@@ -1131,7 +1145,7 @@ function registerBenchmark(program) {
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
     .option('-s, --save [path]', 'Save results to JSON file')
-    .action(benchmarkEmbed);
+    .action(withTelemetry("embed", benchmarkEmbed));
 
   // ── benchmark rerank ──
   bench
@@ -1145,7 +1159,7 @@ function registerBenchmark(program) {
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
     .option('-s, --save [path]', 'Save results to JSON file')
-    .action(benchmarkRerank);
+    .action(withTelemetry("rerank", benchmarkRerank));
 
   // ── benchmark similarity ──
   bench
@@ -1158,7 +1172,7 @@ function registerBenchmark(program) {
     .option('-d, --dimensions <n>', 'Output dimensions')
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
-    .action(benchmarkSimilarity);
+    .action(withTelemetry("similarity", benchmarkSimilarity));
 
   // ── benchmark cost ──
   bench
@@ -1170,7 +1184,7 @@ function registerBenchmark(program) {
     .option('--volumes <list>', 'Comma-separated daily query volumes', '100,1000,10000,100000')
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
-    .action(benchmarkCost);
+    .action(withTelemetry("cost", benchmarkCost));
 
   // ── benchmark batch ──
   bench
@@ -1182,7 +1196,7 @@ function registerBenchmark(program) {
     .option('-f, --file <path>', 'Load texts from file')
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
-    .action(benchmarkBatch);
+    .action(withTelemetry("batch", benchmarkBatch));
 
   // ── benchmark quantization ──
   bench
@@ -1198,7 +1212,7 @@ function registerBenchmark(program) {
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
     .option('-s, --save [path]', 'Save results to JSON file')
-    .action(benchmarkQuantization);
+    .action(withTelemetry("quantization", benchmarkQuantization));
 
   // ── benchmark asymmetric ──
   bench
@@ -1211,7 +1225,7 @@ function registerBenchmark(program) {
     .option('-k, --top-k <n>', 'Show top K results', '5')
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
-    .action(benchmarkAsymmetric);
+    .action(withTelemetry("asymmetric", benchmarkAsymmetric));
 
   // ── benchmark space ──
   bench
@@ -1223,7 +1237,7 @@ function registerBenchmark(program) {
     .option('-d, --dimensions <n>', 'Output dimensions (must be supported by all models)')
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
-    .action(benchmarkSpace);
+    .action(withTelemetry("space", benchmarkSpace));
 }
 
 /**

package/src/commands/chat.js

@@ -223,6 +223,11 @@ async function runChat(opts) {
     }
   }
 
+  // Telemetry: track session
+  const telemetry = require('../lib/telemetry');
+  const chatStartTime = Date.now();
+  let turnCount = 0;
+
   // Track tool calls from last agent response (for /tools and /export-workflow)
   let lastToolCalls = [];
 
@@ -276,6 +281,7 @@ async function runChat(opts) {
     }
 
     // Execute chat turn
+    turnCount++;
     try {
       if (isAgent) {
         lastToolCalls = await handleAgentTurn(input, {
@@ -296,13 +302,25 @@ async function runChat(opts) {
     rl.prompt();
   });
 
+  function sendChatTelemetry() {
+    telemetry.send('cli_chat', {
+      provider: llmConfig.provider,
+      llmModel: llmConfig.model,
+      embeddingModel: proj.model || undefined,
+      turnCount,
+      durationMs: Date.now() - chatStartTime,
+    });
+  }
+
   rl.on('close', async () => {
+    sendChatTelemetry();
     await cleanup(historyMongo);
     process.exit(0);
   });
 
   // Handle Ctrl+C gracefully
   rl.on('SIGINT', async () => {
+    sendChatTelemetry();
     console.log('');
     await cleanup(historyMongo);
     process.exit(0);

package/src/commands/chunk.js

@@ -51,6 +51,7 @@ function registerChunk(program) {
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
     .action(async (input, opts) => {
+      const telemetry = require('../lib/telemetry');
       try {
         // Load project config, merge with CLI opts
         const { config: projectConfig } = loadProject();
@@ -62,6 +63,12 @@ function registerChunk(program) {
         const minSize = opts.minSize || chunkConfig.minSize || DEFAULTS.minSize;
         const textField = opts.textField || 'text';
 
+        const done = telemetry.timer('cli_chunk', {
+          strategy,
+          chunkSize,
+          overlap,
+        });
+
         if (!STRATEGIES.includes(strategy)) {
           console.error(ui.error(`Unknown strategy: "${strategy}". Available: ${STRATEGIES.join(', ')}`));
           process.exit(1);
@@ -227,7 +234,10 @@ function registerChunk(program) {
             console.log(ui.label('Est. cost', ui.dim(`~$${cost < 0.01 ? cost.toFixed(4) : cost.toFixed(2)} with voyage-4-large`)));
           }
         }
+
+        done({ chunkCount: allChunks.length });
       } catch (err) {
+        telemetry.send('cli_error', { command: 'chunk', errorType: err.constructor.name });
         console.error(ui.error(err.message));
         process.exit(1);
       }

package/src/commands/demo.js

@@ -105,6 +105,8 @@ function registerDemo(program) {
     .option('--skip-pipeline', 'Skip the full pipeline step (Step 5)')
     .option('--keep', 'Keep the demo collection after pipeline step')
     .action(async (opts) => {
+      const telemetry = require('../lib/telemetry');
+      const demoStart = Date.now();
       const noPause = !opts.pause;
 
       // ── Preflight: check API key ──
@@ -425,6 +427,8 @@ function registerDemo(program) {
       console.log('');
       console.log('  Happy searching! 🚀');
       console.log('');
+
+      telemetry.send('cli_demo', { durationMs: Date.now() - demoStart });
     });
 }
 

package/src/commands/embed.js

@@ -4,6 +4,7 @@ const { getDefaultModel } = require('../lib/catalog');
 const { generateEmbeddings } = require('../lib/api');
 const { resolveTextInput } = require('../lib/input');
 const ui = require('../lib/ui');
+const { showCostSummary } = require('../lib/cost-display');
 
 /**
  * Register the embed command on a Commander program.
@@ -26,6 +27,7 @@ function registerEmbed(program) {
     .option('-q, --quiet', 'Suppress non-essential output')
     .action(async (text, opts) => {
       try {
+        const telemetry = require('../lib/telemetry');
         const texts = await resolveTextInput(text, opts.file);
 
         // --estimate: show cost comparison, optionally switch model
@@ -45,6 +47,13 @@ function registerEmbed(program) {
           console.error(ui.dim('ℹ Tip: Use --input-type query or --input-type document for better retrieval accuracy.'));
         }
 
+        const done = telemetry.timer('cli_embed', {
+          model: opts.model,
+          inputType: opts.inputType || undefined,
+          textCount: texts.length,
+          outputDtype: opts.outputDtype,
+        });
+
         let spin;
         if (useSpinner) {
           spin = ui.spinner('Generating embeddings...');
@@ -91,6 +100,7 @@ function registerEmbed(program) {
             console.log(ui.label('Tokens', ui.dim(String(result.usage.total_tokens))));
           }
           console.log(ui.label('Dimensions', ui.bold(String(result.data[0]?.embedding?.length || 'N/A'))));
+          showCostSummary(result.model || model, result.usage?.total_tokens || 0, opts);
           console.log('');
         }
 
@@ -101,7 +111,10 @@ function registerEmbed(program) {
 
         console.log('');
         console.log(ui.success('Embeddings generated'));
+
+        done({ dimensions: result.data[0]?.embedding?.length });
       } catch (err) {
+        telemetry.send('cli_error', { command: 'embed', errorType: err.constructor.name });
         console.error(ui.error(err.message));
         process.exit(1);
       }

package/src/commands/estimate.js

@@ -67,6 +67,7 @@ function registerEstimate(program) {
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
     .action((opts) => {
+      const telemetry = require('../lib/telemetry');
       const numDocs = parseShorthand(opts.docs);
       const numQueries = parseShorthand(opts.queries);
       const docTokens = parseInt(opts.docTokens, 10) || DEFAULT_DOC_TOKENS;
@@ -92,6 +93,8 @@ function registerEstimate(program) {
         process.exit(1);
       }
 
+      telemetry.send('cli_estimate', { model: opts.docModel, tokenCount: numDocs * docTokens });
+
       const docTotalTokens = numDocs * docTokens;
       const queryTotalTokensPerMonth = numQueries * queryTokens;
 

package/src/commands/eval.js

@@ -192,9 +192,13 @@ function registerEval(program) {
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
     .action(async (opts) => {
+      const telemetry = require('../lib/telemetry');
+      const done = telemetry.timer('cli_eval');
+
       // Dispatch to rerank eval mode
       if (opts.mode === 'rerank') {
         await evalRerank(opts);
+        done();
         return;
       }
 
@@ -438,7 +442,9 @@ function registerEval(program) {
           console.log(ui.dim('  💡 Low recall? Try: increasing --limit, different chunking strategy, or review your test set'));
         }
         console.log(ui.dim('  💡 Evaluate reranking quality: vai eval --mode rerank --test-set rerank-test.jsonl'));
+        done();
       } catch (err) {
+        telemetry.send('cli_error', { command: 'eval', errorType: err.constructor.name });
         console.error(ui.error(err.message));
         process.exit(1);
       } finally {

package/src/commands/explain.js

@@ -127,6 +127,8 @@ function registerExplain(program) {
     .description('Learn about embeddings, reranking, vector search, and more')
     .option('--json', 'Output in JSON format')
     .action((concept, opts) => {
+      const telemetry = require('../lib/telemetry');
+      telemetry.send('cli_explain', { topic: concept || 'list' });
       if (!concept) {
         // Show topic list
         if (opts.json) {

package/src/commands/generate.js

@@ -123,7 +123,9 @@ function registerGenerate(program) {
     .option('-l, --list', 'List available components')
     .option('-q, --quiet', 'Suppress hints and metadata')
     .action(async (component, opts) => {
+      const telemetry = require('../lib/telemetry');
       try {
+        telemetry.send('cli_generate', { provider: opts.target, model: opts.model });
         // Determine target
         const target = opts.target || detectTarget();
         

package/src/commands/ingest.js

@@ -208,6 +208,8 @@ function registerIngest(program) {
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress progress, show only final summary')
     .action(async (opts) => {
+      const telemetry = require('../lib/telemetry');
+      const done = telemetry.timer('cli_ingest');
       const startTime = Date.now();
 
       // Validate file exists
@@ -394,7 +396,9 @@ function registerIngest(program) {
             }
           }
         }
+        done({ format, docCount: succeeded });
       } catch (err) {
+        telemetry.send('cli_error', { command: 'ingest', errorType: err.constructor.name });
         console.error(ui.error(err.message));
         process.exit(1);
       } finally {

package/src/commands/init.js

@@ -21,6 +21,8 @@ function registerInit(program) {
     .option('--json', 'Output created config as JSON (non-interactive)')
     .option('-q, --quiet', 'Suppress non-essential output')
     .action(async (opts) => {
+      const telemetry = require('../lib/telemetry');
+      telemetry.send('cli_init');
       // Check for existing config
       const existing = findProjectFile();
       if (existing && !opts.force) {

package/src/commands/mcp-server.js

@@ -17,6 +17,8 @@ function registerMcpServer(program) {
     .option('--no-sse', 'Disable SSE transport (SSE is enabled by default for HTTP)')
     .option('--verbose', 'Enable debug logging to stderr')
     .action(async (opts) => {
+      const telemetry = require('../lib/telemetry');
+      telemetry.send('cli_mcp_start', { transport: opts.transport });
       if (opts.verbose) {
         process.env.VAI_MCP_VERBOSE = '1';
       }

package/src/commands/models.js

@@ -46,6 +46,8 @@ function registerModels(program) {
     .option('--json', 'Machine-readable JSON output')
     .option('-q, --quiet', 'Suppress non-essential output')
     .action((opts) => {
+      const telemetry = require('../lib/telemetry');
+      telemetry.send('cli_models', { category: opts.type });
       let models = MODEL_CATALOG;
 
       // Separate current and legacy models

package/src/commands/ping.js

@@ -15,6 +15,7 @@ function registerPing(program) {
     .option('-q, --quiet', 'Suppress non-essential output')
     .option('--mask', 'Mask sensitive info (cluster hostnames, endpoints) in output. Also enabled by VAI_MASK=1 env var.')
     .action(async (opts) => {
+      const telemetry = require('../lib/telemetry');
       // Support env var so all recordings are masked without remembering the flag
       if (process.env.VAI_MASK === '1' || process.env.VAI_MASK === 'true') {
         opts.mask = true;
@@ -242,6 +243,12 @@ function registerPing(program) {
         }
       }
 
+      // Telemetry
+      telemetry.send('cli_ping', {
+        voyageOk: !!results.voyage?.ok,
+        mongoOk: !!results.mongodb?.ok,
+      });
+
       // Emit JSON at the end with all results
       if (opts.json) {
         console.log(JSON.stringify({ ok: true, ...results }, null, 2));

package/src/commands/pipeline.js

@@ -67,6 +67,7 @@ function registerPipeline(program) {
     .option('-q, --quiet', 'Suppress non-essential output')
     .action(async (input, opts) => {
       let client;
+      const telemetry = require('../lib/telemetry');
       try {
         // Merge project config
         const { config: proj } = loadProject();
@@ -89,6 +90,13 @@ function registerPipeline(program) {
           process.exit(1);
         }
 
+        const done = telemetry.timer('cli_pipeline', {
+          model,
+          chunkStrategy: strategy,
+          chunkSize,
+          createIndex: !!opts.createIndex,
+        });
+
         if (!STRATEGIES.includes(strategy)) {
           console.error(ui.error(`Unknown strategy: "${strategy}". Available: ${STRATEGIES.join(', ')}`));
           process.exit(1);
@@ -313,7 +321,14 @@ function registerPipeline(program) {
           console.log('');
           console.log(ui.dim('  Next: vai query "your search" --db ' + db + ' --collection ' + collection));
         }
+
+        done({
+          fileCount: files.length,
+          chunkCount: allChunks.length,
+          docCount: insertResult.insertedCount,
+        });
       } catch (err) {
+        telemetry.send('cli_error', { command: 'pipeline', errorType: err.constructor.name });
         console.error(ui.error(err.message));
         process.exit(1);
       } finally {