voyageai-cli 1.1.0 → 1.3.0

package/src/commands/ping.js

@@ -0,0 +1,169 @@
+'use strict';
+
+const { API_BASE, requireApiKey } = require('../lib/api');
+const ui = require('../lib/ui');
+
+/**
+ * Register the ping command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerPing(program) {
+  program
+    .command('ping')
+    .description('Test connectivity to Voyage AI API (and optionally MongoDB)')
+    .option('--json', 'Machine-readable JSON output')
+    .option('-q, --quiet', 'Suppress non-essential output')
+    .action(async (opts) => {
+      const results = {};
+
+      // ── Voyage AI ping ──
+      let apiKey;
+      try {
+        apiKey = requireApiKey();
+      } catch {
+        // requireApiKey calls process.exit, but just in case
+        process.exit(1);
+      }
+
+      const useColor = !opts.json;
+      const useSpinner = useColor && !opts.quiet;
+
+      const model = 'voyage-4-lite';
+      const startTime = Date.now();
+
+      let spin;
+      if (useSpinner) {
+        spin = ui.spinner('Testing Voyage AI connection...');
+        spin.start();
+      }
+
+      try {
+        const response = await fetch(`${API_BASE}/embeddings`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify({
+            input: ['ping'],
+            model,
+          }),
+        });
+
+        const elapsed = Date.now() - startTime;
+
+        if (response.status === 401 || response.status === 403) {
+          if (spin) spin.stop();
+          results.voyage = { ok: false, error: 'auth', elapsed };
+          if (opts.json) {
+            console.log(JSON.stringify({ ok: false, error: 'Authentication failed', elapsed }));
+          } else {
+            console.error(ui.error(`Authentication failed (${response.status})`));
+            console.error('');
+            console.error('Your API key may be invalid or expired.');
+            console.error('Get a new key: MongoDB Atlas → AI Models → Create model API key');
+            console.error('Then: export VOYAGE_API_KEY="your-new-key"');
+          }
+          process.exit(1);
+        }
+
+        if (!response.ok) {
+          if (spin) spin.stop();
+          const body = await response.text();
+          results.voyage = { ok: false, error: `HTTP ${response.status}`, elapsed };
+          if (opts.json) {
+            console.log(JSON.stringify({ ok: false, error: `API error (${response.status})`, detail: body, elapsed }));
+          } else {
+            console.error(ui.error(`API error (${response.status}): ${body}`));
+          }
+          process.exit(1);
+        }
+
+        const data = await response.json();
+        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 };
+
+        if (spin) spin.stop();
+
+        if (opts.json) {
+          // JSON output is emitted at the end after MongoDB check
+        } else if (opts.quiet) {
+          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('Model', model));
+          console.log(ui.label('Dimensions', String(dims)));
+          console.log(ui.label('Tokens', String(tokens)));
+        }
+      } catch (err) {
+        if (spin) spin.stop();
+        const elapsed = Date.now() - startTime;
+        results.voyage = { ok: false, error: 'network', elapsed };
+        if (opts.json) {
+          console.log(JSON.stringify({ ok: false, error: 'Network error', detail: err.message, elapsed }));
+        } else {
+          console.error(ui.error(`Connection failed: ${err.message}`));
+          console.error('');
+          console.error('Check your internet connection and try again.');
+        }
+        process.exit(1);
+      }
+
+      // ── MongoDB ping (optional) ──
+      const { getConfigValue } = require('../lib/config');
+      const mongoUri = process.env.MONGODB_URI || getConfigValue('mongodbUri');
+      if (mongoUri) {
+        const mongoStart = Date.now();
+        let mongoSpin;
+        if (useSpinner) {
+          mongoSpin = ui.spinner('Testing MongoDB connection...');
+          mongoSpin.start();
+        }
+
+        try {
+          const { MongoClient } = require('mongodb');
+          const client = new MongoClient(mongoUri);
+          await client.connect();
+          await client.db('admin').command({ ping: 1 });
+          const mongoElapsed = Date.now() - mongoStart;
+
+          // Extract cluster hostname from URI
+          let cluster = 'unknown';
+          try {
+            const match = mongoUri.match(/@([^/?]+)/);
+            if (match) cluster = match[1];
+          } catch { /* ignore */ }
+
+          results.mongodb = { ok: true, elapsed: mongoElapsed, cluster };
+
+          if (mongoSpin) mongoSpin.stop();
+
+          if (!opts.json && !opts.quiet) {
+            console.log('');
+            console.log(ui.success(`Connected to MongoDB Atlas ${ui.dim('(' + mongoElapsed + 'ms)')}`));
+            console.log(ui.label('Cluster', cluster));
+          }
+
+          await client.close();
+        } catch (err) {
+          if (mongoSpin) mongoSpin.stop();
+          const mongoElapsed = Date.now() - mongoStart;
+          results.mongodb = { ok: false, elapsed: mongoElapsed, error: err.message };
+          if (!opts.json && !opts.quiet) {
+            console.log('');
+            console.log(ui.error(`MongoDB connection failed ${ui.dim('(' + mongoElapsed + 'ms)')}: ${err.message}`));
+          }
+        }
+      }
+
+      // Emit JSON at the end with all results
+      if (opts.json) {
+        console.log(JSON.stringify({ ok: true, ...results }, null, 2));
+      }
+    });
+}
+
+module.exports = { registerPing };

package/src/commands/rerank.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const { DEFAULT_RERANK_MODEL } = require('../lib/catalog');
 const { apiRequest } = require('../lib/api');
+const ui = require('../lib/ui');
 
 /**
  * Register the rerank command on a Commander program.
@@ -63,7 +64,7 @@ function registerRerank(program) {
         }
 
         if (!documents || documents.length === 0) {
-          console.error('Error: No documents provided. Use --documents, --documents-file, or pipe via stdin.');
+          console.error(ui.error('No documents provided. Use --documents, --documents-file, or pipe via stdin.'));
           process.exit(1);
         }
 
@@ -76,19 +77,29 @@ function registerRerank(program) {
           body.top_k = opts.topK;
         }
 
+        const useColor = !opts.json;
+        const useSpinner = useColor && !opts.quiet;
+        let spin;
+        if (useSpinner) {
+          spin = ui.spinner('Reranking documents...');
+          spin.start();
+        }
+
         const result = await apiRequest('/rerank', body);
 
+        if (spin) spin.stop();
+
         if (opts.json) {
           console.log(JSON.stringify(result, null, 2));
           return;
         }
 
         if (!opts.quiet) {
-          console.log(`Model: ${result.model}`);
-          console.log(`Query: "${opts.query}"`);
-          console.log(`Results: ${result.data?.length || 0}`);
+          console.log(ui.label('Model', ui.cyan(result.model)));
+          console.log(ui.label('Query', ui.cyan(`"${opts.query}"`)));
+          console.log(ui.label('Results', String(result.data?.length || 0)));
           if (result.usage) {
-            console.log(`Tokens: ${result.usage.total_tokens}`);
+            console.log(ui.label('Tokens', ui.dim(String(result.usage.total_tokens))));
           }
           console.log('');
         }
@@ -97,11 +108,14 @@ function registerRerank(program) {
           for (const item of result.data) {
             const docPreview = documents[item.index].substring(0, 80);
             const ellipsis = documents[item.index].length > 80 ? '...' : '';
-            console.log(`[${item.index}] Score: ${item.relevance_score.toFixed(6)}  "${docPreview}${ellipsis}"`);
+            console.log(`${ui.dim('[' + item.index + ']')} Score: ${ui.score(item.relevance_score)}  ${ui.dim('"' + docPreview + ellipsis + '"')}`);
           }
         }
+
+        console.log('');
+        console.log(ui.success('Reranking complete'));
       } catch (err) {
-        console.error(`Error: ${err.message}`);
+        console.error(ui.error(err.message));
         process.exit(1);
       }
     });

package/src/commands/search.js

@@ -1,8 +1,9 @@
 'use strict';
 
-const { DEFAULT_EMBED_MODEL } = require('../lib/catalog');
+const { getDefaultModel } = require('../lib/catalog');
 const { generateEmbeddings } = require('../lib/api');
 const { getMongoCollection } = require('../lib/mongo');
+const ui = require('../lib/ui');
 
 /**
  * Register the search command on a Commander program.
@@ -17,7 +18,7 @@ function registerSearch(program) {
     .requiredOption('--collection <name>', 'Collection name')
     .requiredOption('--index <name>', 'Vector search index name')
     .requiredOption('--field <name>', 'Embedding field name')
-    .option('-m, --model <model>', 'Embedding model', DEFAULT_EMBED_MODEL)
+    .option('-m, --model <model>', 'Embedding model', getDefaultModel())
     .option('--input-type <type>', 'Input type for query embedding', 'query')
     .option('-d, --dimensions <n>', 'Output dimensions', (v) => parseInt(v, 10))
     .option('-l, --limit <n>', 'Maximum results', (v) => parseInt(v, 10), 10)
@@ -29,6 +30,14 @@ function registerSearch(program) {
     .action(async (opts) => {
       let client;
       try {
+        const useColor = !opts.json;
+        const useSpinner = useColor && !opts.quiet;
+        let spin;
+        if (useSpinner) {
+          spin = ui.spinner('Searching...');
+          spin.start();
+        }
+
         const embedResult = await generateEmbeddings([opts.query], {
           model: opts.model,
           inputType: opts.inputType,
@@ -54,7 +63,8 @@ function registerSearch(program) {
           try {
             vectorSearchStage.filter = JSON.parse(opts.filter);
           } catch (e) {
-            console.error('Error: Invalid filter JSON. Ensure it is valid JSON.');
+            if (spin) spin.stop();
+            console.error(ui.error('Invalid filter JSON. Ensure it is valid JSON.'));
             process.exit(1);
           }
         }
@@ -67,6 +77,8 @@ function registerSearch(program) {
 
         const results = await collection.aggregate(pipeline).toArray();
 
+        if (spin) spin.stop();
+
         const cleanResults = results.map(doc => {
           const clean = { ...doc };
           delete clean[opts.field];
@@ -79,28 +91,29 @@ function registerSearch(program) {
         }
 
         if (!opts.quiet) {
-          console.log(`Query: "${opts.query}"`);
-          console.log(`Results: ${cleanResults.length}`);
+          console.log(ui.label('Query', ui.cyan(`"${opts.query}"`)));
+          console.log(ui.label('Results', String(cleanResults.length)));
           console.log('');
         }
 
         if (cleanResults.length === 0) {
-          console.log('No results found.');
+          console.log(ui.yellow('No results found.'));
           return;
         }
 
         for (let i = 0; i < cleanResults.length; i++) {
           const doc = cleanResults[i];
-          const score = doc.score?.toFixed(6) || 'N/A';
-          console.log(`── Result ${i + 1} (score: ${score}) ──`);
+          const scoreVal = doc.score;
+          const scoreStr = scoreVal != null ? ui.score(scoreVal) : 'N/A';
+          console.log(`── ${ui.bold('Result ' + (i + 1))} (score: ${scoreStr}) ──`);
           const textPreview = doc.text ? doc.text.substring(0, 200) : 'No text field';
           const ellipsis = doc.text && doc.text.length > 200 ? '...' : '';
           console.log(`  ${textPreview}${ellipsis}`);
-          console.log(`  _id: ${doc._id}`);
+          console.log(`  ${ui.dim('_id: ' + doc._id)}`);
           console.log('');
         }
       } catch (err) {
-        console.error(`Error: ${err.message}`);
+        console.error(ui.error(err.message));
         process.exit(1);
       } finally {
         if (client) await client.close();

package/src/commands/store.js

@@ -1,10 +1,11 @@
 'use strict';
 
 const fs = require('fs');
-const { DEFAULT_EMBED_MODEL } = require('../lib/catalog');
+const { getDefaultModel } = require('../lib/catalog');
 const { generateEmbeddings } = require('../lib/api');
 const { resolveTextInput } = require('../lib/input');
 const { getMongoCollection } = require('../lib/mongo');
+const ui = require('../lib/ui');
 
 /**
  * Register the store command on a Commander program.
@@ -19,7 +20,7 @@ function registerStore(program) {
     .requiredOption('--field <name>', 'Embedding field name')
     .option('--text <text>', 'Text to embed and store')
     .option('-f, --file <path>', 'File to embed and store (text file or .jsonl for batch mode)')
-    .option('-m, --model <model>', 'Embedding model', DEFAULT_EMBED_MODEL)
+    .option('-m, --model <model>', 'Embedding model', getDefaultModel())
     .option('--input-type <type>', 'Input type: query or document', 'document')
     .option('-d, --dimensions <n>', 'Output dimensions', (v) => parseInt(v, 10))
     .option('--metadata <json>', 'Additional metadata as JSON')
@@ -37,6 +38,14 @@ function registerStore(program) {
         const texts = await resolveTextInput(opts.text, opts.file);
         const textContent = texts[0];
 
+        const useColor = !opts.json;
+        const useSpinner = useColor && !opts.quiet;
+        let spin;
+        if (useSpinner) {
+          spin = ui.spinner('Embedding and storing...');
+          spin.start();
+        }
+
         const embedResult = await generateEmbeddings([textContent], {
           model: opts.model,
           inputType: opts.inputType,
@@ -48,7 +57,7 @@ function registerStore(program) {
         const doc = {
           text: textContent,
           [opts.field]: embedding,
-          model: opts.model || DEFAULT_EMBED_MODEL,
+          model: opts.model || getDefaultModel(),
           dimensions: embedding.length,
           createdAt: new Date(),
         };
@@ -58,7 +67,8 @@ function registerStore(program) {
             const meta = JSON.parse(opts.metadata);
             Object.assign(doc, meta);
           } catch (e) {
-            console.error('Error: Invalid metadata JSON. Ensure it is valid JSON.');
+            if (spin) spin.stop();
+            console.error(ui.error('Invalid metadata JSON. Ensure it is valid JSON.'));
             process.exit(1);
           }
         }
@@ -67,6 +77,8 @@ function registerStore(program) {
         client = c;
         const result = await collection.insertOne(doc);
 
+        if (spin) spin.stop();
+
         if (opts.json) {
           console.log(JSON.stringify({
             insertedId: result.insertedId,
@@ -75,18 +87,18 @@ function registerStore(program) {
             tokens: embedResult.usage?.total_tokens,
           }, null, 2));
         } else if (!opts.quiet) {
-          console.log(`✓ Stored document: ${result.insertedId}`);
-          console.log(`  Database:   ${opts.db}`);
-          console.log(`  Collection: ${opts.collection}`);
-          console.log(`  Field:      ${opts.field}`);
-          console.log(`  Dimensions: ${embedding.length}`);
-          console.log(`  Model:      ${doc.model}`);
+          console.log(ui.success('Stored document: ' + ui.cyan(String(result.insertedId))));
+          console.log(ui.label('Database', opts.db));
+          console.log(ui.label('Collection', opts.collection));
+          console.log(ui.label('Field', opts.field));
+          console.log(ui.label('Dimensions', String(embedding.length)));
+          console.log(ui.label('Model', doc.model));
           if (embedResult.usage) {
-            console.log(`  Tokens:     ${embedResult.usage.total_tokens}`);
+            console.log(ui.label('Tokens', String(embedResult.usage.total_tokens)));
           }
         }
       } catch (err) {
-        console.error(`Error: ${err.message}`);
+        console.error(ui.error(err.message));
         process.exit(1);
       } finally {
         if (client) await client.close();
@@ -106,7 +118,7 @@ async function handleBatchStore(opts) {
     const lines = content.split('\n').filter(line => line.trim());
 
     if (lines.length === 0) {
-      console.error('Error: JSONL file is empty.');
+      console.error(ui.error('JSONL file is empty.'));
       process.exit(1);
     }
 
@@ -114,21 +126,25 @@ async function handleBatchStore(opts) {
       try {
         return JSON.parse(line);
       } catch (e) {
-        console.error(`Error: Invalid JSON on line ${i + 1}: ${e.message}`);
+        console.error(ui.error(`Invalid JSON on line ${i + 1}: ${e.message}`));
         process.exit(1);
       }
     });
 
     const texts = records.map(r => {
       if (!r.text) {
-        console.error('Error: Each JSONL line must have a "text" field.');
+        console.error(ui.error('Each JSONL line must have a "text" field.'));
         process.exit(1);
       }
       return r.text;
     });
 
-    if (!opts.quiet) {
-      console.log(`Embedding ${texts.length} documents...`);
+    const useColor = !opts.json;
+    const useSpinner = useColor && !opts.quiet;
+    let spin;
+    if (useSpinner) {
+      spin = ui.spinner(`Embedding and storing ${texts.length} documents...`);
+      spin.start();
     }
 
     const embedResult = await generateEmbeddings(texts, {
@@ -142,7 +158,7 @@ async function handleBatchStore(opts) {
       const doc = {
         text: record.text,
         [opts.field]: embedding,
-        model: opts.model || DEFAULT_EMBED_MODEL,
+        model: opts.model || getDefaultModel(),
         dimensions: embedding.length,
         createdAt: new Date(),
       };
@@ -156,27 +172,29 @@ async function handleBatchStore(opts) {
     client = c;
     const result = await collection.insertMany(docs);
 
+    if (spin) spin.stop();
+
     if (opts.json) {
       console.log(JSON.stringify({
         insertedCount: result.insertedCount,
         insertedIds: result.insertedIds,
         dimensions: docs[0]?.dimensions,
-        model: opts.model || DEFAULT_EMBED_MODEL,
+        model: opts.model || getDefaultModel(),
         tokens: embedResult.usage?.total_tokens,
       }, null, 2));
     } else if (!opts.quiet) {
-      console.log(`✓ Stored ${result.insertedCount} documents`);
-      console.log(`  Database:   ${opts.db}`);
-      console.log(`  Collection: ${opts.collection}`);
-      console.log(`  Field:      ${opts.field}`);
-      console.log(`  Dimensions: ${docs[0]?.dimensions}`);
-      console.log(`  Model:      ${opts.model || DEFAULT_EMBED_MODEL}`);
+      console.log(ui.success(`Stored ${result.insertedCount} documents`));
+      console.log(ui.label('Database', opts.db));
+      console.log(ui.label('Collection', opts.collection));
+      console.log(ui.label('Field', opts.field));
+      console.log(ui.label('Dimensions', String(docs[0]?.dimensions)));
+      console.log(ui.label('Model', opts.model || getDefaultModel()));
       if (embedResult.usage) {
-        console.log(`  Tokens:     ${embedResult.usage.total_tokens}`);
+        console.log(ui.label('Tokens', String(embedResult.usage.total_tokens)));
       }
     }
   } catch (err) {
-    console.error(`Error: ${err.message}`);
+    console.error(ui.error(err.message));
     process.exit(1);
   } finally {
     if (client) await client.close();

package/src/lib/api.js

@@ -5,15 +5,19 @@ const MAX_RETRIES = 3;
 
 /**
  * Get the Voyage API key or exit with a helpful error.
+ * Checks: env var → config file.
  * @returns {string}
  */
 function requireApiKey() {
-  const key = process.env.VOYAGE_API_KEY;
+  const { getConfigValue } = require('./config');
+  const key = process.env.VOYAGE_API_KEY || getConfigValue('apiKey');
   if (!key) {
-    console.error('Error: VOYAGE_API_KEY environment variable is not set.');
+    console.error('Error: VOYAGE_API_KEY is not set.');
+    console.error('');
+    console.error('Option 1: export VOYAGE_API_KEY="your-key-here"');
+    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('Then: export VOYAGE_API_KEY="your-key-here"');
     process.exit(1);
   }
   return key;
@@ -82,11 +86,11 @@ async function apiRequest(endpoint, body) {
  * @returns {Promise<object>} API response with embeddings
  */
 async function generateEmbeddings(texts, options = {}) {
-  const { DEFAULT_EMBED_MODEL } = require('./catalog');
+  const { getDefaultModel } = require('./catalog');
 
   const body = {
     input: texts,
-    model: options.model || DEFAULT_EMBED_MODEL,
+    model: options.model || getDefaultModel(),
   };
 
   if (options.inputType) {

package/src/lib/banner.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const pc = require('picocolors');
+
+/**
+ * Read the package version from package.json.
+ * @returns {string}
+ */
+function getVersion() {
+  const pkg = require('../../package.json');
+  return pkg.version || '0.0.0';
+}
+
+/**
+ * Display a compact ASCII banner for the CLI.
+ */
+function showBanner() {
+  const version = getVersion();
+  const title = `  🧭 ${pc.bold(pc.cyan('vai'))} — ${pc.bold('Voyage AI CLI')}  ${pc.dim('v' + version)}`;
+  const tagline = `  ${pc.dim('Embeddings, reranking & search')}`;
+
+  // Calculate visible width (strip ANSI codes for alignment)
+  const stripAnsi = (str) => str.replace(/\x1b\[[0-9;]*m/g, '');
+  const titleLen = stripAnsi(title).length;
+  const taglineLen = stripAnsi(tagline).length;
+  const innerWidth = Math.max(titleLen, taglineLen) + 2;
+
+  const top = pc.dim('  ╭' + '─'.repeat(innerWidth) + '╮');
+  const bot = pc.dim('  ╰' + '─'.repeat(innerWidth) + '╯');
+  const titleLine = pc.dim('  │') + title + ' '.repeat(innerWidth - titleLen) + pc.dim('│');
+  const taglineLine = pc.dim('  │') + tagline + ' '.repeat(innerWidth - taglineLen) + pc.dim('│');
+
+  console.log('');
+  console.log(top);
+  console.log(titleLine);
+  console.log(taglineLine);
+  console.log(bot);
+  console.log('');
+}
+
+/**
+ * Display the quick start guide with colored commands.
+ */
+function showQuickStart() {
+  console.log(`  ${pc.bold('Quick start:')}`);
+  console.log(`    ${pc.cyan('$ vai ping')}                    Test your connection`);
+  console.log(`    ${pc.cyan('$ vai embed "hello world"')}     Generate embeddings`);
+  console.log(`    ${pc.cyan('$ vai models')}                  List available models`);
+  console.log(`    ${pc.cyan('$ vai demo')}                    Interactive walkthrough`);
+  console.log('');
+  console.log(`  Run ${pc.cyan('vai <command> --help')} for detailed usage.`);
+  console.log('');
+}
+
+module.exports = { showBanner, showQuickStart, getVersion };

package/src/lib/catalog.js

@@ -1,9 +1,27 @@
 'use strict';
 
+const { getConfigValue } = require('./config');
+
 const DEFAULT_EMBED_MODEL = 'voyage-4-large';
 const DEFAULT_RERANK_MODEL = 'rerank-2.5';
 const DEFAULT_DIMENSIONS = 1024;
 
+/**
+ * Get the default embedding model (config override or built-in default).
+ * @returns {string}
+ */
+function getDefaultModel() {
+  return getConfigValue('defaultModel') || DEFAULT_EMBED_MODEL;
+}
+
+/**
+ * Get the default dimensions (config override or built-in default).
+ * @returns {number}
+ */
+function getDefaultDimensions() {
+  return getConfigValue('defaultDimensions') || DEFAULT_DIMENSIONS;
+}
+
 /** @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' },
@@ -22,5 +40,7 @@ module.exports = {
   DEFAULT_EMBED_MODEL,
   DEFAULT_RERANK_MODEL,
   DEFAULT_DIMENSIONS,
+  getDefaultModel,
+  getDefaultDimensions,
   MODEL_CATALOG,
 };