@qverisai/cli 0.1.0

package/README.md

@@ -0,0 +1,323 @@
+# QVeris CLI
+
+Discover, inspect, and call 10,000+ API capabilities from your terminal.
+
+```
+$ qveris discover "weather forecast API"
+Found 5 capabilities matching your query
+
+1. gridpoint_forecast  by Weather.gov
+   weather_gov.gridpoints.forecast.retrieve.v1
+   Returns a textual forecast for a 2.5km grid area
+   relevance: 95%  ·  success: 99.8%  ·  latency: ~180ms  ·  cost: 3 cr
+
+2. current_weather  by OpenWeather
+   openweathermap.weather.current.v1
+   Get current weather data for any location
+   relevance: 87%  ·  success: 99.5%  ·  latency: ~200ms  ·  cost: 2 cr
+
+$ qveris inspect 1
+gridpoint_forecast
+Returns a textual forecast for a 2.5km grid area
+
+  Provider:   Weather.gov
+  Latency:    ~180ms
+  Success:    99.8%
+  Cost:       3 credits
+
+  Parameters:
+    wfo     string   required
+      Forecast office ID
+      values: "LWX", "OKX", "LAX", ...
+    x       integer  required
+      Forecast grid X coordinate
+    y       integer  required
+      Forecast grid Y coordinate
+
+  Example:
+    {"wfo": "LWX", "x": 90, "y": 90}
+
+$ qveris call 1 --params '{"wfo":"LWX","x":90,"y":90}'
+✓ success  ·  523ms  ·  10 credits  ·  (1368087.93 remaining)
+tool: weather_gov...  ·  id: 7ebcaf9d-...
+
+{
+  "type": "Feature",
+  "properties": {
+    "periods": [
+      { "name": "Today", "temperature": 79, "shortForecast": "Partly Sunny" },
+      ...
+    ]
+  }
+}
+```
+
+## Install
+
+**One-liner (recommended):**
+
+```bash
+curl -fsSL https://qveris.ai/install | bash
+```
+
+**Or via npm:**
+
+```bash
+npm install -g @qverisai/cli
+```
+
+**Or run without installing:**
+
+```bash
+npx @qverisai/cli discover "stock price API"
+```
+
+Requires Node.js 18+.
+
+## Quick Start
+
+```bash
+# 1. Authenticate
+qveris login
+
+# 2. Discover capabilities
+qveris discover "weather forecast"
+
+# 3. Inspect a tool (by index from discover results)
+qveris inspect 1
+
+# 4. Call it
+qveris call 1 --params '{"wfo": "LWX", "x": 90, "y": 90}'
+```
+
+## Commands
+
+### Core
+
+| Command | Description |
+|---------|-------------|
+| `qveris discover <query>` | Find capabilities by natural language. Shows tool ID, provider, description, relevance, success rate, latency, and cost for each result. |
+| `qveris inspect <id\|index>` | View full tool details: parameters (type, required, description, enum values), example, provider info, execution history. |
+| `qveris call <id\|index>` | Execute a capability. Shows result data, execution time, cost, and remaining credits. |
+
+### Account
+
+| Command | Description |
+|---------|-------------|
+| `qveris login` | Authenticate with API key (opens browser or `--token` for direct input) |
+| `qveris logout` | Remove stored key |
+| `qveris whoami` | Show current auth status and key source |
+| `qveris credits` | Check credit balance |
+
+### Utilities
+
+| Command | Description |
+|---------|-------------|
+| `qveris interactive` | Launch REPL mode (discover/inspect/call/codegen in one session) |
+| `qveris doctor` | Self-check: Node.js version, API key, connectivity |
+| `qveris config <subcommand>` | Manage CLI settings (set, get, list, reset, path) |
+| `qveris completions <shell>` | Generate shell completions (bash/zsh/fish) |
+
+## Usage
+
+### Discover
+
+Search for capabilities using natural language. Each result shows the tool name, provider, tool ID, description, and quality metrics to help you choose.
+
+```bash
+qveris discover "stock price API"
+qveris discover "translate text" --limit 10
+```
+
+### Inspect
+
+View full details of a tool before calling it. Shows parameters with types, required/optional, descriptions, allowed values (enum), and example parameters.
+
+```bash
+# By index (from last discover)
+qveris inspect 1
+
+# By tool ID
+qveris inspect alphavantage.quote.execute.v1
+
+# Inspect multiple tools
+qveris inspect 1 2 3
+```
+
+### Call
+
+Execute a tool. Results are automatically truncated for terminal display (4KB). Large results get an OSS download link.
+
+```bash
+# Inline params
+qveris call 1 --params '{"symbol": "AAPL"}'
+
+# From file
+qveris call 1 --params @params.json
+
+# From stdin
+echo '{"symbol": "AAPL"}' | qveris call 1 --params -
+
+# Dry run (validate without executing, no credits consumed)
+qveris call 1 --params '{"symbol": "AAPL"}' --dry-run
+
+# Full result (no truncation)
+qveris call 1 --params '{"symbol": "AAPL"}' --max-size -1
+
+# Generate code snippet after call
+qveris call 1 --params '{"symbol": "AAPL"}' --codegen curl
+qveris call 1 --params '{"symbol": "AAPL"}' --codegen python
+qveris call 1 --params '{"symbol": "AAPL"}' --codegen js
+```
+
+#### Response Truncation
+
+For terminal use, results larger than 4KB are automatically truncated. The CLI shows:
+- A preview of the truncated content
+- A download link (valid 120 minutes) for the full result
+- The response schema so you know the data structure
+
+```
+✓ success  ·  1200ms  ·  5 credits
+
+Response truncated (32KB → 4KB preview)
+
+Full content (valid 120 min):
+  https://qveris-tool-results-cache-bj.oss-cn-beijing...
+  Download: curl -o result.json '<url>'
+
+Schema:
+  query: string
+  total_results: number
+  articles: array of
+    pmid: string
+    title: string
+
+Preview:
+  {"query": "evolution", "total_results": 890994, ...
+```
+
+For agent/script use (`--json` or piped output), the default increases to 20KB (matching the MCP server). Use `--max-size -1` for unlimited.
+
+### Interactive Mode
+
+```bash
+$ qveris interactive
+
+qveris> discover "weather API"
+Found 3 capabilities matching your query
+1. openweathermap.weather.current.v1  by OpenWeather
+   ...
+
+qveris> inspect 1
+openweathermap.weather.current.v1
+  Parameters:
+    city  string  required
+    ...
+
+qveris> call 1 '{"city": "London"}'
+✓ success  ·  200ms  ·  2 credits
+{ "temp": 18.5, ... }
+
+qveris> codegen curl
+curl -sS -X POST "https://qveris.ai/api/v1/tools/execute?tool_id=..." ...
+
+qveris> exit
+```
+
+## Configuration
+
+### API Key
+
+```bash
+# Option 1: Login (saves to ~/.config/qveris/config.json)
+qveris login
+
+# Option 2: Environment variable
+export QVERIS_API_KEY="sk-1_..."
+
+# Option 3: Per-command flag
+qveris discover "weather" --api-key "sk-1_..."
+```
+
+**Resolution order:** `--api-key` flag > `QVERIS_API_KEY` env > config file
+
+### Config File
+
+Located at `~/.config/qveris/config.json` (respects `XDG_CONFIG_HOME`).
+
+```bash
+qveris config list          # View all settings with sources
+qveris config set key value # Set a value
+qveris config get key       # Get a value
+qveris config path          # Print config file location
+qveris config reset         # Reset to defaults
+```
+
+### Shell Completions
+
+```bash
+# Bash
+eval "$(qveris completions bash)"
+
+# Zsh
+eval "$(qveris completions zsh)"
+
+# Fish
+qveris completions fish | source
+```
+
+## Global Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--json` | `-j` | Output raw JSON (for piping/agent use) |
+| `--api-key <key>` | | Override API key |
+| `--timeout <seconds>` | | Request timeout |
+| `--max-size <bytes>` | | Response size limit (-1 = unlimited) |
+| `--no-color` | | Disable colors |
+| `--version` | `-V` | Print version |
+| `--help` | `-h` | Show help |
+
+## Agent / LLM Integration
+
+When used by agents or in scripts, the CLI auto-detects non-TTY environments:
+
+| Context | `max_response_size` | Rationale |
+|---------|---------------------|-----------|
+| Terminal (TTY) | 4KB | Human-friendly, auto-truncate |
+| Piped / scripted | 20KB | Agent-friendly, matches MCP server |
+| `--json` flag | 20KB | Explicit agent mode |
+| `--max-size N` | N | User override |
+
+```bash
+# Agent workflow: discover → select → call → parse
+TOOL=$(qveris discover "weather" --json | jq -r '.results[0].tool_id')
+qveris call "$TOOL" --params '{"city":"London"}' --json | jq '.result.data'
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 2 | Usage error (bad arguments) |
+| 69 | Service unavailable |
+| 75 | Temporary failure (timeout, rate limit) |
+| 77 | Auth error (invalid key, insufficient credits) |
+| 78 | Config error (missing key) |
+
+## Zero Dependencies
+
+QVeris CLI uses only Node.js built-in APIs. No `chalk`, no `commander`, no `yargs`. Installs instantly via `npx`.
+
+## Links
+
+- Website: https://qveris.ai
+- API Docs: https://qveris.ai/docs
+- Get API Key: https://qveris.ai/account?page=api-keys
+- GitHub: https://github.com/QVerisAI/QVerisAI
+
+## License
+
+MIT

package/bin/qveris.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/main.mjs";
+
+main(process.argv).catch((err) => {
+  console.error(err.message || err);
+  process.exitCode = process.exitCode || 1;
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@qverisai/cli",
+  "version": "0.1.0",
+  "description": "QVeris CLI -- discover, inspect, and call 10,000+ capabilities",
+  "type": "module",
+  "bin": {
+    "qveris": "./bin/qveris.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/"
+  ],
+  "keywords": [
+    "qveris",
+    "cli",
+    "api",
+    "agent",
+    "capabilities",
+    "tool-calling"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/QVerisAI/QVerisAI",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://qveris.ai",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/install.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+# QVeris CLI Installer
+# Usage: curl -fsSL https://qveris.ai/install | bash
+set -euo pipefail
+
+BOLD='\033[1m'
+GREEN='\033[32m'
+YELLOW='\033[33m'
+CYAN='\033[36m'
+RED='\033[31m'
+DIM='\033[2m'
+RESET='\033[0m'
+
+info()  { echo -e "  ${CYAN}▸${RESET} $1"; }
+ok()    { echo -e "  ${GREEN}✓${RESET} $1"; }
+warn()  { echo -e "  ${YELLOW}!${RESET} $1"; }
+fail()  { echo -e "  ${RED}✘${RESET} $1"; exit 1; }
+
+echo ""
+echo -e "  ${BOLD}QVeris CLI Installer${RESET}"
+echo ""
+
+# ── 1. Check Node.js ──────────────────────────────────────────────────
+if ! command -v node &>/dev/null; then
+  fail "Node.js not found. Install Node.js 18+ first: ${CYAN}https://nodejs.org${RESET}"
+fi
+
+NODE_VERSION=$(node -v | sed 's/v//')
+NODE_MAJOR=$(echo "$NODE_VERSION" | cut -d. -f1)
+
+if [ "$NODE_MAJOR" -lt 18 ]; then
+  fail "Node.js $NODE_VERSION detected. QVeris CLI requires Node.js 18+."
+fi
+
+ok "Node.js v$NODE_VERSION"
+
+# ── 2. Check npm ──────────────────────────────────────────────────────
+if ! command -v npm &>/dev/null; then
+  fail "npm not found. Install npm first."
+fi
+
+ok "npm $(npm -v)"
+
+# ── 3. Install @qverisai/cli globally ────────────────────────────────
+info "Installing @qverisai/cli..."
+
+if ! npm install -g @qverisai/cli 2>&1 | while IFS= read -r line; do
+  # suppress verbose npm output, show only errors
+  case "$line" in
+    *ERR*|*error*|*Error*) echo "  $line" ;;
+  esac
+done; then
+  # If global install fails (permissions), try with --prefix
+  warn "Global install failed, trying user-local install..."
+  NPM_DIR="${HOME}/.npm-global"
+  mkdir -p "$NPM_DIR"
+  if ! npm_output=$(npm install -g @qverisai/cli --prefix "$NPM_DIR" 2>&1); then
+    echo "$npm_output" | grep -i err
+  fi
+fi
+
+# ── 4. Verify installation ───────────────────────────────────────────
+# Find where qveris was installed
+QVERIS_BIN=""
+if command -v qveris &>/dev/null; then
+  QVERIS_BIN=$(command -v qveris)
+else
+  # Check common locations
+  for dir in \
+    "$(npm prefix -g 2>/dev/null)/bin" \
+    "${HOME}/.npm-global/bin" \
+    "/usr/local/bin" \
+    "/opt/homebrew/bin" \
+    "${HOME}/.local/bin"; do
+    if [ -f "$dir/qveris" ]; then
+      QVERIS_BIN="$dir/qveris"
+      break
+    fi
+  done
+fi
+
+if [ -z "$QVERIS_BIN" ]; then
+  fail "Installation succeeded but 'qveris' not found in PATH."
+fi
+
+# ── 5. Check if qveris is in PATH ────────────────────────────────────
+if command -v qveris &>/dev/null; then
+  ok "qveris installed at $QVERIS_BIN"
+else
+  # Not in PATH — add it
+  BIN_DIR=$(dirname "$QVERIS_BIN")
+  SHELL_RC=""
+  case "${SHELL:-/bin/bash}" in
+    */zsh)  SHELL_RC="$HOME/.zshrc" ;;
+    */bash) SHELL_RC="$HOME/.bashrc" ;;
+    */fish) SHELL_RC="$HOME/.config/fish/config.fish" ;;
+    *)      SHELL_RC="$HOME/.profile" ;;
+  esac
+
+  # Add to PATH in shell rc if not already there
+  if [ -n "$SHELL_RC" ] && ! grep -Fq "$BIN_DIR" "$SHELL_RC" 2>/dev/null; then
+    echo "" >> "$SHELL_RC"
+    echo "# QVeris CLI" >> "$SHELL_RC"
+    if [[ "$SHELL_RC" == *"fish"* ]]; then
+      echo "set -gx PATH $BIN_DIR \$PATH" >> "$SHELL_RC"
+    else
+      echo "export PATH=\"$BIN_DIR:\$PATH\"" >> "$SHELL_RC"
+    fi
+    ok "Added $BIN_DIR to PATH in $SHELL_RC"
+    warn "Run ${CYAN}source $SHELL_RC${RESET} or open a new terminal to use 'qveris'"
+  fi
+  export PATH="$BIN_DIR:$PATH"
+  ok "qveris installed at $QVERIS_BIN"
+fi
+
+# ── 6. Print version and next steps ──────────────────────────────────
+VERSION=$(qveris --version 2>/dev/null || echo "unknown")
+
+echo ""
+echo -e "  ${GREEN}${BOLD}QVeris CLI installed successfully!${RESET} ${DIM}($VERSION)${RESET}"
+echo ""
+echo -e "  ${BOLD}Get started:${RESET}"
+echo -e "    ${CYAN}qveris login${RESET}                          Authenticate"
+echo -e "    ${CYAN}qveris discover${RESET} \"weather API\"         Find capabilities"
+echo -e "    ${CYAN}qveris inspect${RESET} 1                      View tool details"
+echo -e "    ${CYAN}qveris call${RESET} 1 --params '{...}'        Execute a tool"
+echo ""
+echo -e "  ${DIM}Docs: https://qveris.ai/docs${RESET}"
+echo ""

package/src/client/api.mjs

@@ -0,0 +1,96 @@
+import { resolve } from "../config/resolve.mjs";
+import { CliError } from "../errors/handler.mjs";
+
+function getBaseUrl(flagValue) {
+  return resolve("base_url", flagValue).value;
+}
+
+async function requestJson(path, { method = "POST", query = {}, body, timeoutMs = 30000, apiKey, baseUrl }) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const url = new URL(baseUrl.replace(/\/$/, "") + path);
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+
+    const response = await fetch(url.toString(), {
+      method,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      signal: controller.signal,
+    });
+
+    if (!response.ok) {
+      const status = response.status;
+      const rawText = (await response.text()).slice(0, 8192);
+      let errorDetail, jsonBody;
+      try {
+        jsonBody = JSON.parse(rawText);
+        errorDetail = jsonBody.error_message || jsonBody.message || null;
+      } catch { /* not JSON */ }
+      // For known error codes, pass errorDetail only if it's a meaningful message
+      // (not raw JSON); otherwise let the CliError template message apply
+      if (status === 401 || status === 403) throw new CliError("AUTH_INVALID_KEY", errorDetail);
+      if (status === 402) throw new CliError("CREDITS_INSUFFICIENT", errorDetail);
+      if (status === 429) throw new CliError("RATE_LIMITED", errorDetail);
+      const err = new CliError("API_ERROR", `HTTP ${status}: ${errorDetail || rawText}`);
+      if (jsonBody) err.responseData = jsonBody;
+      throw err;
+    }
+
+    try {
+      return await response.json();
+    } catch {
+      throw new CliError("API_ERROR", "Invalid JSON response from API");
+    }
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    if (err.name === "AbortError") throw new CliError("NET_TIMEOUT");
+    throw err;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function discoverTools({ apiKey, baseUrl: baseUrlFlag, query, limit = 5, timeoutMs = 30000 }) {
+  const baseUrl = getBaseUrl(baseUrlFlag);
+  return requestJson("/search", { apiKey, baseUrl, body: { query, limit }, timeoutMs });
+}
+
+export async function inspectToolsByIds({ apiKey, baseUrl: baseUrlFlag, toolIds, discoveryId, timeoutMs = 30000 }) {
+  const baseUrl = getBaseUrl(baseUrlFlag);
+  const body = { tool_ids: toolIds };
+  if (discoveryId) body.search_id = discoveryId;
+  return requestJson("/tools/by-ids", { apiKey, baseUrl, body, timeoutMs });
+}
+
+export async function callTool({
+  apiKey,
+  baseUrl: baseUrlFlag,
+  toolId,
+  discoveryId,
+  parameters,
+  maxResponseSize = 102400,
+  timeoutMs = 120000,
+}) {
+  const baseUrl = getBaseUrl(baseUrlFlag);
+  return requestJson("/tools/execute", {
+    apiKey,
+    baseUrl,
+    query: { tool_id: toolId },
+    body: {
+      search_id: discoveryId,
+      parameters,
+      max_response_size: maxResponseSize,
+    },
+    timeoutMs,
+  });
+}
+

package/src/client/auth.mjs

@@ -0,0 +1,26 @@
+import { resolve } from "../config/resolve.mjs";
+import { CliError } from "../errors/handler.mjs";
+
+const PLACEHOLDER_PATTERNS = [
+  /^your[_-]?(qveris)?[_-]?api[_-]?key/i,
+  /^sk-1_xxx/,
+  /^sk-1_$/,
+  /^YOUR_/,
+];
+
+export function resolveApiKey(flagValue) {
+  const { value } = resolve("api_key", flagValue);
+
+  if (!value || !value.trim()) {
+    throw new CliError("AUTH_MISSING_KEY");
+  }
+
+  const trimmed = value.trim();
+  for (const pattern of PLACEHOLDER_PATTERNS) {
+    if (pattern.test(trimmed)) {
+      throw new CliError("AUTH_MISSING_KEY", "API key appears to be a placeholder. Set a real key.");
+    }
+  }
+
+  return trimmed;
+}