@qverisai/cli 0.1.0

package/src/commands/call.mjs

@@ -0,0 +1,100 @@
+import { resolveApiKey } from "../client/auth.mjs";
+import { callTool } from "../client/api.mjs";
+import { resolveToolId, getSessionDiscoveryId } from "../session/session.mjs";
+import { resolveParams } from "../utils/params.mjs";
+import { formatCallResult } from "../output/formatter.mjs";
+import { outputJson } from "../output/json.mjs";
+import { createSpinner } from "../output/spinner.mjs";
+import { generateSnippet } from "../output/codegen.mjs";
+import { CliError } from "../errors/handler.mjs";
+import { bold, dim, cyan } from "../output/colors.mjs";
+
+// Smart max_response_size defaults:
+//   --max-size N   → user explicit override (highest priority)
+//   --json         → 20480 (agent/LLM scenario, matches MCP server)
+//   non-TTY        → 20480 (piped/scripted, likely agent)
+//   TTY            → 4096  (human terminal, auto-truncate large results)
+const MAX_SIZE_TTY = 4096;
+const MAX_SIZE_AGENT = 20480;
+
+function resolveMaxSize(flags) {
+  if (flags.maxSize !== undefined) {
+    const parsed = parseInt(flags.maxSize, 10);
+    if (isNaN(parsed)) throw new CliError("API_ERROR", "Invalid --max-size: must be an integer");
+    return parsed;
+  }
+  if (flags.json) return MAX_SIZE_AGENT;
+  if (!process.stdout.isTTY) return MAX_SIZE_AGENT;
+  return MAX_SIZE_TTY;
+}
+
+export async function runCall(idOrIndex, flags) {
+  const apiKey = resolveApiKey(flags.apiKey);
+  const timeoutMs = (parseInt(flags.timeout, 10) || 60) * 1000;
+  const maxSize = resolveMaxSize(flags);
+
+  const resolved = resolveToolId(idOrIndex);
+  const toolId = resolved.toolId;
+  let discoveryId = flags.discoveryId || null;
+
+  if (!discoveryId && resolved.fromSession && resolved.discoveryId) {
+    discoveryId = resolved.discoveryId;
+  }
+  if (!discoveryId) discoveryId = getSessionDiscoveryId();
+  if (!discoveryId && /^\d+$/.test(idOrIndex)) {
+    throw new CliError("SESSION_EXPIRED", "No discovery ID. Run 'qveris discover' first or pass --discovery-id.");
+  }
+
+  const parameters = resolveParams(flags.params || "{}");
+
+  if (flags.dryRun) {
+    if (flags.json) {
+      outputJson({ dry_run: true, tool_id: toolId, discovery_id: discoveryId, parameters, max_response_size: maxSize });
+    } else {
+      console.log(`\n  ${bold("Dry run")} -- would send:\n`);
+      console.log(`  Tool:         ${cyan(toolId)}`);
+      console.log(`  Discovery ID: ${dim(discoveryId)}`);
+      console.log(`  Max size:     ${maxSize}`);
+      console.log(`  Parameters:`);
+      console.log(JSON.stringify(parameters, null, 2).split("\n").map((l) => `    ${l}`).join("\n"));
+    }
+    return;
+  }
+
+  const spinner = flags.json ? { stop() {} } : createSpinner("Calling tool...");
+
+  try {
+    const result = await callTool({
+      apiKey,
+      baseUrl: flags.baseUrl,
+      toolId,
+      discoveryId,
+      parameters,
+      maxResponseSize: maxSize,
+      timeoutMs,
+    });
+
+    spinner.stop();
+
+    if (flags.json) {
+      outputJson(result);
+    } else {
+      console.log(formatCallResult(result));
+    }
+
+    if (flags.codegen && result.success) {
+      const snippet = generateSnippet(flags.codegen, {
+        toolId,
+        discoveryId,
+        parameters,
+        maxResponseSize: maxSize,
+      });
+      console.log(`\n  ${dim("--- Code snippet (" + flags.codegen + ") ---")}\n`);
+      console.log(snippet);
+      console.log();
+    }
+  } catch (err) {
+    spinner.stop();
+    throw err;
+  }
+}

package/src/commands/completions.mjs

@@ -0,0 +1,58 @@
+const COMMANDS = [
+  "discover", "inspect", "call",
+  "login", "logout", "whoami", "credits",
+  "config", "interactive", "history", "doctor", "completions",
+];
+
+export async function runCompletions(shell) {
+  switch (shell) {
+    case "bash":
+      console.log(bashCompletions());
+      break;
+    case "zsh":
+      console.log(zshCompletions());
+      break;
+    case "fish":
+      console.log(fishCompletions());
+      break;
+    default:
+      console.error(`  Supported shells: bash, zsh, fish`);
+      console.error(`  Usage: eval "$(qveris completions bash)"`);
+      process.exitCode = 2;
+  }
+}
+
+function bashCompletions() {
+  return `# bash completion for qveris
+_qveris_completions() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  local commands="${COMMANDS.join(" ")}"
+  if [ "\${COMP_CWORD}" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "\${commands}" -- "\${cur}") )
+  fi
+}
+complete -F _qveris_completions qveris`;
+}
+
+function zshCompletions() {
+  return `# zsh completion for qveris
+#compdef qveris
+
+_qveris() {
+  local -a commands
+  commands=(
+${COMMANDS.map((c) => `    '${c}:${c} command'`).join("\n")}
+  )
+  _arguments '1:command:->cmds' '*::arg:->args'
+  case "$state" in
+    cmds) _describe 'command' commands ;;
+  esac
+}
+_qveris`;
+}
+
+function fishCompletions() {
+  return COMMANDS.map(
+    (c) => `complete -c qveris -n '__fish_use_subcommand' -a '${c}' -d '${c} command'`
+  ).join("\n");
+}

package/src/commands/config.mjs

@@ -0,0 +1,96 @@
+import { getConfigPath, getConfigValue, setConfigValue, writeConfig } from "../config/store.mjs";
+import { resolveAll } from "../config/resolve.mjs";
+import { bold, dim, cyan } from "../output/colors.mjs";
+import { outputJson } from "../output/json.mjs";
+
+const ALLOWED_KEYS = ["api_key", "base_url", "default_limit", "default_max_size", "color", "output_format"];
+
+export async function runConfig(subcommand, args, flags) {
+  switch (subcommand) {
+    case "set": return configSet(args[0], args[1], flags);
+    case "get": return configGet(args[0], flags);
+    case "list": return configList(flags);
+    case "reset": return configReset(flags);
+    case "path": return configPath(flags);
+    default:
+      console.error(`  Unknown config subcommand: ${subcommand}`);
+      console.error(`  Usage: qveris config <set|get|list|reset|path>`);
+      process.exitCode = 2;
+  }
+}
+
+function configSet(key, value, flags) {
+  if (!key || value === undefined) {
+    console.error("  Usage: qveris config set <key> <value>");
+    process.exitCode = 2;
+    return;
+  }
+  if (!ALLOWED_KEYS.includes(key)) {
+    console.error(`  Unknown config key: ${key}`);
+    console.error(`  Allowed: ${ALLOWED_KEYS.join(", ")}`);
+    process.exitCode = 2;
+    return;
+  }
+  let parsed = value;
+  if (key.endsWith("limit") || key.endsWith("size")) {
+    parsed = parseInt(value, 10);
+    if (isNaN(parsed)) {
+      console.error(`  Error: ${key} must be a valid integer.`);
+      process.exitCode = 2;
+      return;
+    }
+  }
+  setConfigValue(key, parsed);
+  if (flags.json) {
+    outputJson({ key, value: parsed });
+  } else {
+    console.log(`  ${key} = ${bold(String(parsed))}`);
+  }
+}
+
+function configGet(key, flags) {
+  if (!key) {
+    console.error("  Usage: qveris config get <key>");
+    process.exitCode = 2;
+    return;
+  }
+  const val = getConfigValue(key);
+  if (flags.json) {
+    outputJson({ key, value: val ?? null });
+  } else {
+    console.log(val !== undefined ? `  ${key} = ${bold(String(val))}` : `  ${key} is not set`);
+  }
+}
+
+function configList(flags) {
+  const all = resolveAll();
+  if (flags.json) {
+    const obj = {};
+    for (const [k, v] of Object.entries(all)) {
+      obj[k] = { value: k === "api_key" && v.value ? mask(v.value) : v.value, source: v.source };
+    }
+    outputJson(obj);
+    return;
+  }
+
+  console.log(`\n  ${bold("Key")}                 ${bold("Value")}                    ${bold("Source")}`);
+  for (const [key, { value, source }] of Object.entries(all)) {
+    const display = key === "api_key" && value ? mask(value) : String(value ?? dim("(not set)"));
+    console.log(`  ${cyan(key.padEnd(20))}${display.padEnd(25)}${dim(source)}`);
+  }
+  console.log();
+}
+
+function configReset() {
+  writeConfig({});
+  console.log("  Config reset to defaults.");
+}
+
+function configPath() {
+  console.log(getConfigPath());
+}
+
+function mask(key) {
+  if (typeof key !== "string" || key.length < 10) return "***";
+  return key.slice(0, 6) + "..." + key.slice(-4);
+}

package/src/commands/credits.mjs

@@ -0,0 +1,32 @@
+import { resolveApiKey } from "../client/auth.mjs";
+import { discoverTools } from "../client/api.mjs";
+import { bold, dim, cyan, yellow, green } from "../output/colors.mjs";
+import { outputJson } from "../output/json.mjs";
+import { createSpinner } from "../output/spinner.mjs";
+
+export async function runCredits(flags) {
+  const apiKey = resolveApiKey(flags.apiKey);
+
+  const spinner = flags.json ? { stop() {} } : createSpinner("Checking credits...");
+
+  try {
+    // The backend returns remaining_credits in every /search response
+    const result = await discoverTools({ apiKey, baseUrl: flags.baseUrl, query: "credit balance", limit: 1, timeoutMs: 10000 });
+    spinner.stop();
+
+    const credits = result.remaining_credits;
+
+    if (flags.json) {
+      outputJson({ remaining_credits: credits ?? null });
+    } else if (credits !== undefined && credits !== null) {
+      console.log(`\n  ${green("\u2713")} Credits remaining: ${bold(yellow(String(credits)))}`);
+      console.log(`  ${dim("Manage at:")} ${cyan("https://qveris.ai/account")}\n`);
+    } else {
+      console.log(`\n  ${dim("Credit balance not available in API response.")}`);
+      console.log(`  Check at: ${cyan("https://qveris.ai/account")}\n`);
+    }
+  } catch (err) {
+    spinner.stop();
+    throw err;
+  }
+}

package/src/commands/discover.mjs

@@ -0,0 +1,48 @@
+import { resolveApiKey } from "../client/auth.mjs";
+import { discoverTools } from "../client/api.mjs";
+import { writeSession } from "../session/session.mjs";
+import { formatDiscoverResult } from "../output/formatter.mjs";
+import { outputJson } from "../output/json.mjs";
+import { createSpinner } from "../output/spinner.mjs";
+
+export async function runDiscover(query, flags) {
+  const apiKey = resolveApiKey(flags.apiKey);
+  const limit = parseInt(flags.limit, 10) || 5;
+  const timeoutMs = (parseInt(flags.timeout, 10) || 30) * 1000;
+
+  const spinner = flags.json ? { stop() {} } : createSpinner("Discovering capabilities...");
+
+  try {
+    const result = await discoverTools({
+      apiKey,
+      baseUrl: flags.baseUrl,
+      query,
+      limit,
+      timeoutMs,
+    });
+
+    spinner.stop();
+
+    // Store richer session data for index resolution
+    const tools = result.results ?? [];
+    writeSession({
+      discoveryId: result.search_id,
+      query,
+      results: tools.map((t, i) => ({
+        index: i + 1,
+        tool_id: t.tool_id,
+        name: t.name,
+        provider_name: t.provider_name,
+      })),
+    });
+
+    if (flags.json) {
+      outputJson(result);
+    } else {
+      console.log(formatDiscoverResult(result));
+    }
+  } catch (err) {
+    spinner.stop();
+    throw err;
+  }
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,47 @@
+import { resolve } from "../config/resolve.mjs";
+import { discoverTools } from "../client/api.mjs";
+import { bold, green, red, dim, cyan } from "../output/colors.mjs";
+
+export async function runDoctor(flags) {
+  console.log(`\n  ${bold("QVeris CLI Doctor")}\n`);
+  let allOk = true;
+
+  // Check Node.js version
+  const nodeVersion = process.version;
+  const major = parseInt(nodeVersion.slice(1), 10);
+  if (major >= 18) {
+    console.log(`  ${green("\u2713")} Node.js ${nodeVersion}`);
+  } else {
+    console.log(`  ${red("\u2718")} Node.js ${nodeVersion} -- requires >=18`);
+    allOk = false;
+  }
+
+  // Check API key
+  const { value: apiKey, source } = resolve("api_key", flags.apiKey);
+  if (apiKey && apiKey.trim()) {
+    const masked = apiKey.slice(0, 6) + "..." + apiKey.slice(-4);
+    console.log(`  ${green("\u2713")} API key configured (${masked} via ${source})`);
+
+    // Test connectivity
+    process.stderr.write(`  \u2026 Testing API connectivity...\r`);
+    try {
+      await discoverTools({ apiKey, baseUrl: flags.baseUrl, query: "test", limit: 1, timeoutMs: 10000 });
+      console.log(`  ${green("\u2713")} API connectivity OK                `);
+    } catch (err) {
+      console.log(`  ${red("\u2718")} API connectivity failed: ${err.message}  `);
+      allOk = false;
+    }
+  } else {
+    console.log(`  ${red("\u2718")} No API key configured`);
+    console.log(`     Run ${cyan("qveris login")} or set QVERIS_API_KEY`);
+    allOk = false;
+  }
+
+  console.log();
+  if (allOk) {
+    console.log(`  ${green("All checks passed.")}\n`);
+  } else {
+    console.log(`  ${red("Some checks failed.")}\n`);
+    process.exitCode = 1;
+  }
+}

package/src/commands/history.mjs

@@ -0,0 +1,47 @@
+import { readSession, writeSession } from "../session/session.mjs";
+import { bold, dim, cyan } from "../output/colors.mjs";
+import { outputJson } from "../output/json.mjs";
+
+export async function runHistory(flags) {
+  const session = readSession();
+
+  if (!session) {
+    if (flags.json) {
+      outputJson({ session: null });
+    } else {
+      console.log(`\n  ${dim("No active session. Run")} ${cyan("qveris discover")} ${dim("to start one.")}\n`);
+    }
+    return;
+  }
+
+  if (flags.clear) {
+    writeSession({});
+    console.log("  Session cleared.");
+    return;
+  }
+
+  if (flags.json) {
+    outputJson(session);
+    return;
+  }
+
+  console.log(`\n  ${bold("Current Session")}\n`);
+  console.log(`  Query:        ${session.query || dim("N/A")}`);
+  console.log(`  Discovery ID: ${dim(session.discoveryId || "N/A")}`);
+
+  const results = session.results ?? [];
+  if (results.length > 0) {
+    console.log(`  Results:`);
+    for (const r of results) {
+      console.log(`    ${dim(String(r.index))}  ${cyan(r.tool_id)}  ${r.name || ""}`);
+    }
+  }
+
+  if (session.timestamp) {
+    const age = Math.round((Date.now() - session.timestamp) / 1000);
+    const mins = Math.floor(age / 60);
+    const secs = age % 60;
+    console.log(`  Age:          ${dim(mins > 0 ? `${mins}m ${secs}s` : `${secs}s`)}`);
+  }
+  console.log();
+}

package/src/commands/inspect.mjs

@@ -0,0 +1,47 @@
+import { resolveApiKey } from "../client/auth.mjs";
+import { inspectToolsByIds } from "../client/api.mjs";
+import { resolveToolId, getSessionDiscoveryId } from "../session/session.mjs";
+import { formatInspectResult } from "../output/formatter.mjs";
+import { outputJson } from "../output/json.mjs";
+import { createSpinner } from "../output/spinner.mjs";
+
+export async function runInspect(idsOrIndexes, flags) {
+  const apiKey = resolveApiKey(flags.apiKey);
+  const timeoutMs = (parseInt(flags.timeout, 10) || 30) * 1000;
+
+  const toolIds = [];
+  let discoveryId = flags.discoveryId || null;
+
+  for (const raw of idsOrIndexes) {
+    const resolved = resolveToolId(raw);
+    toolIds.push(resolved.toolId);
+    if (resolved.fromSession && resolved.discoveryId && !discoveryId) {
+      discoveryId = resolved.discoveryId;
+    }
+  }
+
+  if (!discoveryId) discoveryId = getSessionDiscoveryId();
+
+  const spinner = flags.json ? { stop() {} } : createSpinner("Inspecting tools...");
+
+  try {
+    const result = await inspectToolsByIds({
+      apiKey,
+      baseUrl: flags.baseUrl,
+      toolIds,
+      discoveryId,
+      timeoutMs,
+    });
+
+    spinner.stop();
+
+    if (flags.json) {
+      outputJson(result);
+    } else {
+      console.log(formatInspectResult(result));
+    }
+  } catch (err) {
+    spinner.stop();
+    throw err;
+  }
+}

package/src/commands/interactive.mjs

@@ -0,0 +1,171 @@
+import { createInterface } from "node:readline";
+import { resolveApiKey } from "../client/auth.mjs";
+import { discoverTools, inspectToolsByIds, callTool } from "../client/api.mjs";
+import { resolveParams } from "../utils/params.mjs";
+import { formatDiscoverResult, formatInspectResult, formatCallResult } from "../output/formatter.mjs";
+import { generateSnippet } from "../output/codegen.mjs";
+import { writeSession } from "../session/session.mjs";
+import { bold, dim, cyan } from "../output/colors.mjs";
+import { handleError } from "../errors/handler.mjs";
+import { createSpinner } from "../output/spinner.mjs";
+
+export async function runInteractive(flags) {
+  const apiKey = resolveApiKey(flags.apiKey);
+  const baseUrl = flags.baseUrl;
+  const limit = parseInt(flags.limit, 10) || 5;
+  const discoverTimeout = (parseInt(flags.timeout, 10) || 30) * 1000;
+  const callTimeout = (parseInt(flags.timeout, 10) || 60) * 1000;
+
+  const state = {
+    discoveryId: null,
+    results: [],
+    lastCallContext: null,
+  };
+
+  console.log(`\n  ${bold("QVeris Interactive Mode")}`);
+  console.log(`  ${dim("Type 'help' for commands, 'exit' to quit.")}\n`);
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: `${cyan("qveris")}${dim(">")} `,
+  });
+
+  rl.prompt();
+
+  rl.on("line", async (line) => {
+    const input = line.trim();
+    if (!input) { rl.prompt(); return; }
+
+    rl.pause(); // Prevent race conditions on rapid input
+
+    const parts = parseArgs(input);
+    const cmd = parts[0]?.toLowerCase();
+    const rest = parts.slice(1);
+
+    try {
+      switch (cmd) {
+        case "discover":
+        case "search": {
+          const query = rest.join(" ");
+          if (!query) { console.log("  Usage: discover <query>"); break; }
+          const sp = createSpinner("Discovering...");
+          const result = await discoverTools({ apiKey, baseUrl, query, limit, timeoutMs: discoverTimeout });
+          sp.stop();
+          state.discoveryId = result.search_id;
+          state.results = (result.results ?? []).map((t, i) => ({
+            index: i + 1, tool_id: t.tool_id, name: t.name, provider_name: t.provider_name,
+          }));
+          // Persist session so index shortcuts work in subsequent non-interactive calls
+          writeSession({ discoveryId: result.search_id, query, results: state.results });
+          console.log(formatDiscoverResult(result));
+          break;
+        }
+        case "inspect": {
+          const toolId = resolveId(rest[0], state);
+          if (!toolId) { console.log("  Usage: inspect <index|tool_id>"); break; }
+          const sp2 = createSpinner("Inspecting...");
+          const result = await inspectToolsByIds({ apiKey, baseUrl, toolIds: [toolId], discoveryId: state.discoveryId, timeoutMs: discoverTimeout });
+          sp2.stop();
+          console.log(formatInspectResult(result));
+          break;
+        }
+        case "call": {
+          const toolId = resolveId(rest[0], state);
+          if (!toolId) { console.log("  Usage: call <index|tool_id> <json_params>"); break; }
+          if (!state.discoveryId) { console.log("  Run 'discover' first."); break; }
+          const paramsStr = rest.slice(1).join(" ") || "{}";
+          const parameters = resolveParams(paramsStr);
+          const sp3 = createSpinner("Calling...");
+          const result = await callTool({ apiKey, baseUrl, toolId, discoveryId: state.discoveryId, parameters, timeoutMs: callTimeout });
+          sp3.stop();
+          console.log(formatCallResult(result));
+          if (result.success) {
+            state.lastCallContext = { toolId, discoveryId: state.discoveryId, parameters };
+          }
+          break;
+        }
+        case "codegen": {
+          if (!state.lastCallContext) { console.log("  No successful call yet."); break; }
+          const lang = rest[0] || "curl";
+          console.log(`\n${generateSnippet(lang, state.lastCallContext)}\n`);
+          break;
+        }
+        case "history": {
+          if (!state.discoveryId) { console.log("  No session."); break; }
+          console.log(`\n  Discovery ID: ${dim(state.discoveryId)}`);
+          for (const r of state.results) {
+            console.log(`    ${dim(String(r.index))}  ${cyan(r.tool_id)}`);
+          }
+          console.log();
+          break;
+        }
+        case "help":
+          printHelp();
+          break;
+        case "exit":
+        case "quit":
+          rl.close();
+          return;
+        default:
+          console.log(`  Unknown command: ${cmd}. Type 'help' for commands.`);
+      }
+    } catch (err) {
+      handleError(err, false);
+    } finally {
+      rl.resume();
+      rl.prompt();
+    }
+  });
+
+  rl.on("close", () => {
+    console.log(`\n  ${dim("Bye.")}\n`);
+  });
+}
+
+function resolveId(raw, state) {
+  if (!raw) return null;
+  if (/^\d+$/.test(raw)) {
+    const index = parseInt(raw, 10) - 1;
+    if (index >= 0 && index < state.results.length) {
+      return state.results[index].tool_id;
+    }
+  }
+  return raw;
+}
+
+/** Shell-style argument splitting: handles double quotes, single quotes, and backslash escapes. */
+function parseArgs(input) {
+  const args = [];
+  let current = "";
+  let inDouble = false;
+  let inSingle = false;
+  let escape = false;
+
+  for (const ch of input) {
+    if (escape) { current += ch; escape = false; continue; }
+    if (ch === "\\" && !inSingle) { escape = true; continue; }
+    if (ch === '"' && !inSingle) { inDouble = !inDouble; continue; }
+    if (ch === "'" && !inDouble) { inSingle = !inSingle; continue; }
+    if ((ch === " " || ch === "\t") && !inDouble && !inSingle) {
+      if (current) { args.push(current); current = ""; }
+      continue;
+    }
+    current += ch;
+  }
+  if (current) args.push(current);
+  return args;
+}
+
+function printHelp() {
+  console.log(`
+  ${bold("Commands:")}
+    discover <query>             Find capabilities
+    inspect  <index|tool_id>     View tool details
+    call     <index|tool_id> {}  Execute a tool with JSON params
+    codegen  <curl|js|python>    Generate code from last call
+    history                      Show session state
+    help                         Show this help
+    exit                         Quit
+`);
+}