voyageai-cli 1.1.0 → 1.3.0

package/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm ci
+      - run: npm test

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to voyageai-cli are documented here.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+### Added
+- `vai demo` — Interactive guided walkthrough of all features
+- ASCII banner when running `vai` with no arguments
+- CONTRIBUTING.md for open-source contributors
+- This changelog
+
+## [1.1.0] - 2026-02-03
+
+### Added
+- `vai config` — Persistent config management (`~/.vai/config.json`)
+  - `set`, `get`, `delete`, `path`, `reset` subcommands
+  - Secrets masked in output, config file chmod 600
+  - `--stdin` flag for secure key input (avoids shell history)
+- `vai ping` — Test API and MongoDB connectivity
+- `.env` file support via dotenv
+- Colored output with picocolors (green ✓, red ✗, score-based colors)
+- Animated spinners on all network operations
+- npm update notifier (checks daily, non-blocking)
+- GitHub Actions CI (Node 18, 20, 22)
+- README badges (CI, npm, license, node version)
+- Credential priority chain: env var → .env → config file
+- Security documentation in README
+
+### Fixed
+- `ping` command now falls back to config file for API key and MongoDB URI
+- `rerank` endpoint corrected from `/v1/reranking` to `/v1/rerank`
+- `index create` parseInt handling for dimensions (was producing NaN)
+
+## [1.0.0] - 2026-02-03
+
+### Added
+- `vai embed` — Generate embeddings (text, file, stdin, bulk)
+- `vai rerank` — Rerank documents with relevance scoring
+- `vai store` — Embed and insert into MongoDB Atlas (single + batch JSONL)
+- `vai search` — $vectorSearch with pre-filter support
+- `vai index` — Create, list, delete Atlas Vector Search indexes
+- `vai models` — List available Voyage AI models with pricing
+- REST API integration with `https://ai.mongodb.com/v1/`
+- MongoDB Atlas Vector Search integration
+- API retry on 429 with exponential backoff
+- `--json` and `--quiet` flags on all commands
+- 50+ unit tests

package/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing to voyageai-cli
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+```bash
+git clone https://github.com/mrlynn/voyageai-cli.git
+cd voyageai-cli
+npm install
+npm link  # makes `vai` available globally for testing
+```
+
+## Running Tests
+
+```bash
+npm test
+```
+
+Tests use Node.js built-in test runner (`node:test`). No external test framework needed.
+
+## Project Structure
+
+```
+src/
+├── cli.js              # Entry point
+├── commands/           # One file per command
+│   ├── embed.js
+│   ├── rerank.js
+│   ├── store.js
+│   ├── search.js
+│   ├── index.js
+│   ├── models.js
+│   ├── ping.js
+│   ├── config.js
+│   └── demo.js
+└── lib/                # Shared utilities
+    ├── api.js          # Voyage AI API client
+    ├── mongo.js        # MongoDB connection
+    ├── catalog.js      # Model catalog
+    ├── config.js       # Config file management
+    ├── format.js       # Table formatting
+    ├── input.js        # Text input resolution
+    ├── ui.js           # Colors, spinners, output helpers
+    └── banner.js       # ASCII banner
+test/
+├── commands/           # Command tests
+└── lib/                # Library tests
+```
+
+## Adding a New Command
+
+1. Create `src/commands/mycommand.js` exporting a `registerMyCommand(program)` function
+2. Register it in `src/cli.js`
+3. Add tests in `test/commands/mycommand.test.js`
+4. Update README.md with usage examples
+
+## Code Style
+
+- CommonJS (`require`/`module.exports`)
+- `'use strict';` at the top of every file
+- JSDoc comments on exported functions
+- `parseInt(x, 10)` — always include radix
+- Errors go to stderr (`console.error`)
+- Support `--json` and `--quiet` flags on all commands
+- No colors or spinners in `--json` mode
+
+## Pull Requests
+
+- Create a feature branch from `main`
+- Include tests for new functionality
+- Run `npm test` before submitting
+- Write clear commit messages
+
+## Reporting Issues
+
+Open an issue at https://github.com/mrlynn/voyageai-cli/issues with:
+- Node.js version (`node --version`)
+- OS and version
+- Steps to reproduce
+- Expected vs actual behavior

package/README.md

@@ -1,5 +1,7 @@
 # voyageai-cli
 
+[![CI](https://github.com/mrlynn/voyageai-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/mrlynn/voyageai-cli/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/voyageai-cli.svg)](https://www.npmjs.com/package/voyageai-cli) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/node/v/voyageai-cli.svg)](https://nodejs.org)
+
 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.
 
 Generate embeddings, rerank search results, store vectors in Atlas, and run semantic search — all from the command line.
@@ -110,6 +112,20 @@ vai index list --db myapp --collection docs
 vai index delete --db myapp --collection docs --index-name my_index
 ```
 
+### `vai ping` — Test API connectivity
+
+```bash
+# Test Voyage AI API
+vai ping
+
+# Also tests MongoDB if MONGODB_URI is set
+export MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/"
+vai ping
+
+# JSON output
+vai ping --json
+```
+
 ### `vai models` — List available models
 
 ```bash
@@ -154,8 +170,41 @@ vai rerank --query "how does cloud database work" \
 
 | Variable | Required For | Description |
 |----------|-------------|-------------|
-| `VOYAGE_API_KEY` | embed, rerank, store, search | [Model API key](https://www.mongodb.com/docs/voyageai/management/api-keys/) from MongoDB Atlas |
-| `MONGODB_URI` | store, search, index | MongoDB Atlas connection string |
+| `VOYAGE_API_KEY` | embed, rerank, store, search, ping | [Model API key](https://www.mongodb.com/docs/voyageai/management/api-keys/) from MongoDB Atlas |
+| `MONGODB_URI` | store, search, index, ping (optional) | MongoDB Atlas connection string |
+
+Credentials are resolved in this order (highest priority first):
+
+1. **Environment variables** (`export VOYAGE_API_KEY=...`)
+2. **`.env` file** in your working directory
+3. **Config file** (`~/.vai/config.json` via `vai config set`)
+
+You can also create a `.env` file in your project directory instead of exporting variables:
+
+```
+VOYAGE_API_KEY=your-key
+MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/
+```
+
+> ⚠️ **Add `.env` to your `.gitignore`** to avoid accidentally committing secrets.
+
+Or use the built-in config store:
+
+```bash
+# Pipe to avoid key appearing in shell history
+echo "your-key" | vai config set api-key --stdin
+vai config set mongodb-uri "mongodb+srv://user:pass@cluster.mongodb.net/"
+
+# Verify (secrets are masked)
+vai config get
+```
+
+### Security
+
+- Config file (`~/.vai/config.json`) is created with `600` permissions (owner read/write only)
+- Secrets are always masked in `vai config get` output
+- 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
 
 ## Global Flags
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voyageai-cli",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "CLI for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search",
   "bin": {
     "vai": "./src/cli.js"
@@ -27,11 +27,18 @@
   "bugs": {
     "url": "https://github.com/mrlynn/voyageai-cli/issues"
   },
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  },
   "engines": {
     "node": ">=18.0.0"
   },
   "dependencies": {
     "commander": "^12.0.0",
-    "mongodb": "^6.0.0"
+    "dotenv": "^17.2.3",
+    "mongodb": "^6.0.0",
+    "ora": "^9.1.0",
+    "picocolors": "^1.1.1",
+    "update-notifier": "^7.3.1"
   }
 }

package/src/cli.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 'use strict';
 
+require('dotenv').config({ quiet: true });
+
 const { program } = require('commander');
 const { registerEmbed } = require('./commands/embed');
 const { registerRerank } = require('./commands/rerank');
@@ -8,11 +10,15 @@ const { registerStore } = require('./commands/store');
 const { registerSearch } = require('./commands/search');
 const { registerIndex } = require('./commands/index');
 const { registerModels } = require('./commands/models');
+const { registerPing } = require('./commands/ping');
+const { registerConfig } = require('./commands/config');
+const { registerDemo } = require('./commands/demo');
+const { showBanner, showQuickStart } = require('./lib/banner');
 
 program
   .name('vai')
   .description('Voyage AI embeddings, reranking, and Atlas Vector Search CLI')
-  .version('1.0.0');
+  .version('1.1.0');
 
 registerEmbed(program);
 registerRerank(program);
@@ -20,5 +26,16 @@ registerStore(program);
 registerSearch(program);
 registerIndex(program);
 registerModels(program);
+registerPing(program);
+registerConfig(program);
+registerDemo(program);
+
+// If no args (just `vai`), show banner + quick start + help
+if (process.argv.length <= 2) {
+  showBanner();
+  showQuickStart();
+  program.outputHelp();
+  process.exit(0);
+}
 
 program.parse();

package/src/commands/config.js

@@ -0,0 +1,157 @@
+'use strict';
+
+const fs = require('fs');
+const {
+  CONFIG_PATH,
+  KEY_MAP,
+  SECRET_KEYS,
+  loadConfig,
+  saveConfig,
+  getConfigValue,
+  setConfigValue,
+  deleteConfigValue,
+  maskSecret,
+} = require('../lib/config');
+const ui = require('../lib/ui');
+
+const VALID_KEYS = Object.keys(KEY_MAP);
+
+/**
+ * Register the config command on a Commander program.
+ * @param {import('commander').Command} program
+ */
+function registerConfig(program) {
+  const configCmd = program
+    .command('config')
+    .description('Manage persistent configuration (~/.vai/config.json)');
+
+  // ── config set <key> [value] ──
+  configCmd
+    .command('set <key> [value]')
+    .description('Set a config value (omit value to read from stdin)')
+    .option('--stdin', 'Read value from stdin (avoids shell history exposure)')
+    .action(async (key, value, opts) => {
+      const internalKey = KEY_MAP[key];
+      if (!internalKey) {
+        console.error(ui.error(`Unknown config key "${ui.cyan(key)}".`));
+        console.error(`Valid keys: ${VALID_KEYS.join(', ')}`);
+        process.exit(1);
+      }
+
+      // Read from stdin if no value provided or --stdin flag
+      if (!value || opts.stdin) {
+        if (process.stdin.isTTY && !value) {
+          // Interactive: prompt without echo for secrets
+          const isSecret = SECRET_KEYS.has(internalKey);
+          if (isSecret) {
+            process.stderr.write(`Enter ${key}: `);
+          } else {
+            process.stderr.write(`Enter ${key}: `);
+          }
+        }
+        if (!value) {
+          const chunks = [];
+          for await (const chunk of process.stdin) {
+            chunks.push(chunk);
+          }
+          value = Buffer.concat(chunks).toString('utf-8').trim();
+        }
+      }
+
+      if (!value) {
+        console.error(ui.error('No value provided.'));
+        process.exit(1);
+      }
+
+      // Parse numeric values for dimensions
+      const storedValue = key === 'default-dimensions' ? parseInt(value, 10) : value;
+      setConfigValue(internalKey, storedValue);
+      console.log(ui.success(`Set ${ui.cyan(key)} = ${SECRET_KEYS.has(internalKey) ? ui.dim(maskSecret(String(storedValue))) : storedValue}`));
+    });
+
+  // ── config get [key] ──
+  configCmd
+    .command('get [key]')
+    .description('Get a config value (or all if no key)')
+    .action((key) => {
+      if (key) {
+        const internalKey = KEY_MAP[key];
+        if (!internalKey) {
+          console.error(ui.error(`Unknown config key "${ui.cyan(key)}".`));
+          console.error(`Valid keys: ${VALID_KEYS.join(', ')}`);
+          process.exit(1);
+        }
+
+        const value = getConfigValue(internalKey);
+        if (value === undefined) {
+          console.log(`${ui.cyan(key)}: ${ui.dim('(not set)')}`);
+        } else {
+          const display = SECRET_KEYS.has(internalKey) ? ui.dim(maskSecret(String(value))) : value;
+          console.log(`${ui.cyan(key)}: ${display}`);
+        }
+      } else {
+        // Show all config
+        const config = loadConfig();
+        if (Object.keys(config).length === 0) {
+          console.log(ui.dim('No configuration set.'));
+          console.log(`Run: ${ui.cyan('vai config set <key> <value>')}`);
+          return;
+        }
+
+        // Build a reverse map: internalKey → cliKey
+        const reverseMap = {};
+        for (const [cliKey, intKey] of Object.entries(KEY_MAP)) {
+          reverseMap[intKey] = cliKey;
+        }
+
+        for (const [intKey, value] of Object.entries(config)) {
+          const cliKey = reverseMap[intKey] || intKey;
+          const display = SECRET_KEYS.has(intKey) ? ui.dim(maskSecret(String(value))) : value;
+          console.log(`${ui.cyan(cliKey)}: ${display}`);
+        }
+      }
+    });
+
+  // ── config delete <key> ──
+  configCmd
+    .command('delete <key>')
+    .description('Remove a config value')
+    .action((key) => {
+      const internalKey = KEY_MAP[key];
+      if (!internalKey) {
+        console.error(ui.error(`Unknown config key "${ui.cyan(key)}".`));
+        console.error(`Valid keys: ${VALID_KEYS.join(', ')}`);
+        process.exit(1);
+      }
+
+      deleteConfigValue(internalKey);
+      console.log(ui.success(`Deleted ${ui.cyan(key)}`));
+    });
+
+  // ── config path ──
+  configCmd
+    .command('path')
+    .description('Print the config file path')
+    .action(() => {
+      console.log(CONFIG_PATH);
+    });
+
+  // ── config reset ──
+  configCmd
+    .command('reset')
+    .description('Delete the entire config file')
+    .action(() => {
+      try {
+        fs.unlinkSync(CONFIG_PATH);
+        console.log(ui.success(`Config file deleted: ${ui.dim(CONFIG_PATH)}`));
+      } catch (err) {
+        if (err.code === 'ENOENT') {
+          console.log(ui.dim('No config file found. Nothing to reset.'));
+        } else {
+          throw err;
+        }
+      }
+    });
+}
+
+module.exports = { registerConfig };