@qverisai/cli 0.4.0 → 0.6.0

package/src/commands/usage.mjs

@@ -0,0 +1,190 @@
+import { resolveApiKey } from "../client/auth.mjs";
+import { getUsageHistory, unwrapApiResponse } from "../client/api.mjs";
+import { outputJson } from "../output/json.mjs";
+import { createSpinner } from "../output/spinner.mjs";
+import {
+  DEFAULT_PAGE_SIZE,
+  MAX_EXPORT_ROWS,
+  MAX_SEARCH_SCAN_ROWS,
+  MAX_SUMMARY_ROWS,
+  buildUsageQuery,
+  buildUsageSummary,
+  buildUsageSummaryFromServer,
+  chooseBucket,
+  clampLimit,
+  extractItems,
+  extractTotal,
+  formatExportMetadata,
+  formatUsageRows,
+  formatUsageSummary,
+  matchesUsageFilters,
+  pickUsageRow,
+  resolveDateRange,
+  resolveMode,
+  writeJsonlExport,
+} from "../output/audit.mjs";
+
+export async function runUsage(flags) {
+  const apiKey = resolveApiKey(flags.apiKey);
+  const mode = resolveMode(flags.mode);
+  const timeoutMs = (parseInt(flags.timeout, 10) || 30) * 1000;
+  const limit = clampLimit(flags.limit);
+  const { startDate, endDate } = resolveDateRange(flags);
+  const bucket = chooseBucket(startDate, endDate, flags.bucket);
+
+  const spinner = flags.json ? { stop() {} } : createSpinner("Querying usage history...");
+
+  try {
+    if (mode === "search") {
+      const { rows, total, partial } = await collectUsageRows({
+        apiKey,
+        flags,
+        timeoutMs,
+        limit,
+        maxRows: MAX_SEARCH_SCAN_ROWS,
+        stopWhenLimitReached: true,
+      });
+      spinner.stop();
+      const payload = {
+        mode,
+        start_date: startDate,
+        end_date: endDate,
+        shown_records: rows.length,
+        matched_records: total,
+        truncated: partial,
+        items: rows.map(pickUsageRow),
+      };
+      if (flags.json) outputJson(payload);
+      else console.log(formatUsageRows(rows, { total, partial }));
+      return;
+    }
+
+    if (mode === "export_file") {
+      const { rows, total, partial } = await collectUsageRows({
+        apiKey,
+        flags,
+        timeoutMs,
+        limit: MAX_EXPORT_ROWS,
+        maxRows: MAX_EXPORT_ROWS,
+        stopWhenLimitReached: false,
+      });
+      spinner.stop();
+      const metadata = writeJsonlExport("usage_history", rows, {
+        start_date: startDate,
+        end_date: endDate,
+        matched_records: total,
+        truncated: partial,
+        filters: usageFilters(flags),
+      });
+      if (flags.json) outputJson(metadata);
+      else console.log(formatExportMetadata(metadata));
+      return;
+    }
+
+    const summaryResponse = unwrapApiResponse(await getUsageHistory({
+      apiKey,
+      baseUrl: flags.baseUrl,
+      query: buildUsageQuery(flags, {
+        page: 1,
+        pageSize: limit,
+        mode: "summary",
+      }),
+      timeoutMs,
+    }));
+    if (summaryResponse?.summary) {
+      spinner.stop();
+      const rows = extractItems(summaryResponse);
+      const total = extractTotal(summaryResponse, rows.length);
+      const summary = buildUsageSummaryFromServer(summaryResponse.summary, { startDate, endDate, bucket });
+      if (flags.json) {
+        outputJson({
+          mode,
+          summary,
+          scanned_records: rows.length,
+          matched_records: total,
+          truncated: false,
+        });
+      } else {
+        console.log(formatUsageSummary(summary, { scannedRows: rows.length, total, partial: false }));
+      }
+      return;
+    }
+
+    const { rows, total, partial, scannedRows } = await collectUsageRows({
+      apiKey,
+      flags,
+      timeoutMs,
+      limit: MAX_SUMMARY_ROWS,
+      maxRows: MAX_SUMMARY_ROWS,
+      stopWhenLimitReached: false,
+    });
+    spinner.stop();
+    const summary = buildUsageSummary(rows, { startDate, endDate, bucket });
+    if (flags.json) {
+      outputJson({
+        mode,
+        summary,
+        scanned_records: scannedRows,
+        matched_records: total,
+        truncated: partial,
+      });
+    } else {
+      console.log(formatUsageSummary(summary, { scannedRows, total, partial }));
+    }
+  } catch (err) {
+    spinner.stop();
+    throw err;
+  }
+}
+
+async function collectUsageRows({ apiKey, flags, timeoutMs, limit, maxRows, stopWhenLimitReached }) {
+  const rows = [];
+  let page = 1;
+  let total;
+  let scannedRows = 0;
+  let partial = false;
+
+  while (rows.length < limit && scannedRows < maxRows) {
+    const query = buildUsageQuery(flags, { page, pageSize: Math.min(DEFAULT_PAGE_SIZE, maxRows - scannedRows) });
+    const response = unwrapApiResponse(await getUsageHistory({
+      apiKey,
+      baseUrl: flags.baseUrl,
+      query,
+      timeoutMs,
+    }));
+    const items = extractItems(response);
+    if (total === undefined) total = extractTotal(response, undefined);
+    if (items.length === 0) break;
+    scannedRows += items.length;
+    for (const item of items) {
+      if (!matchesUsageFilters(item, flags)) continue;
+      rows.push(item);
+      if (stopWhenLimitReached && rows.length >= limit) break;
+    }
+    if (stopWhenLimitReached && rows.length >= limit) {
+      partial = Boolean(total && total > scannedRows);
+      break;
+    }
+    if (total !== undefined && scannedRows >= total) break;
+    if (items.length < DEFAULT_PAGE_SIZE) break;
+    page += 1;
+  }
+
+  if (total !== undefined && scannedRows < total) partial = true;
+  if (scannedRows >= maxRows && (total === undefined || scannedRows < total)) partial = true;
+
+  return { rows: rows.slice(0, limit), total, partial, scannedRows };
+}
+
+function usageFilters(flags) {
+  return {
+    execution_id: flags.executionId,
+    search_id: flags.searchId,
+    event_type: flags.eventType,
+    kind: flags.kind,
+    success: flags.success,
+    charge_outcome: flags.chargeOutcome,
+    min_credits: flags.minCredits,
+    max_credits: flags.maxCredits,
+  };
+}

package/src/compat/aliases.mjs

@@ -13,6 +13,7 @@ const FLAG_ALIASES = {
 export function normalizeLegacyArgs(args) {
   const result = [...args];
   const warnings = [];
+  const originalCommand = result[0];
 
   if (result.length > 0 && COMMAND_ALIASES[result[0]]) {
     warnings.push(`'${result[0]}' is deprecated; use '${COMMAND_ALIASES[result[0]]}' instead.`);
@@ -20,6 +21,9 @@ export function normalizeLegacyArgs(args) {
   }
 
   for (let i = 0; i < result.length; i++) {
+    if (originalCommand === "usage" && result[i] === "--search-id") {
+      continue;
+    }
     if (FLAG_ALIASES[result[i]]) {
       warnings.push(`'${result[i]}' is deprecated; use '${FLAG_ALIASES[result[i]]}' instead.`);
       result[i] = FLAG_ALIASES[result[i]];

package/src/errors/codes.mjs

@@ -29,9 +29,24 @@ export const ERROR_CODES = {
   },
   PARAMS_INVALID_JSON: {
     message: "Invalid JSON in --params",
-    hint: "Check JSON syntax in --params value",
+    hint: "Check JSON syntax in --params value, or pass a file with --params @params.json",
     exit: EX_USAGE,
   },
+  INIT_PARAMS_REQUIRED: {
+    message: "Init could not infer safe parameters for the selected capability",
+    hint: "Run 'qveris inspect 1' to review required params, then rerun 'qveris init --resume --params <json>'",
+    exit: EX_USAGE,
+  },
+  TOOL_CALL_FAILED: {
+    message: "Capability call failed",
+    hint: "Review the error, adjust --params, then rerun 'qveris init --resume --params <json>'",
+    exit: EX_UNAVAILABLE,
+  },
+  PROVIDER_FAILURE: {
+    message: "Remote provider failed",
+    hint: "Try another discovered capability with 'qveris inspect 2' and 'qveris call 2', or rerun discovery with a broader query",
+    exit: EX_UNAVAILABLE,
+  },
   TOOL_NOT_FOUND: {
     message: "Tool not found",
     hint: "Run 'qveris discover' to find available tools",
@@ -44,12 +59,12 @@ export const ERROR_CODES = {
   },
   CREDITS_INSUFFICIENT: {
     message: "Insufficient credits",
-    hint: "Purchase credits at https://qveris.ai/pricing",
+    hint: "Purchase credits at https://qveris.ai/pricing, then confirm balance with 'qveris credits'",
     exit: EX_NOPERM,
   },
   SESSION_EXPIRED: {
     message: "Session expired",
-    hint: "Run 'qveris discover' to start a new session",
+    hint: "Run 'qveris discover' or 'qveris init' to start a new session",
     exit: EX_USAGE,
   },
 };

package/src/main.mjs

@@ -52,6 +52,11 @@ export async function main(argv) {
         await runCall(rest[0], flags);
         break;
       }
+      case "init": {
+        const { runInit } = await import("./commands/init.mjs");
+        await runInit(rest.join(" "), flags);
+        break;
+      }
       case "login": {
         const { runLogin } = await import("./commands/login.mjs");
         await runLogin(flags);
@@ -72,6 +77,16 @@ export async function main(argv) {
         await runCredits(flags);
         break;
       }
+      case "usage": {
+        const { runUsage } = await import("./commands/usage.mjs");
+        await runUsage(flags);
+        break;
+      }
+      case "ledger": {
+        const { runLedger } = await import("./commands/ledger.mjs");
+        await runLedger(flags);
+        break;
+      }
       case "config": {
         const subcommand = rest[0];
         const subArgs = rest.slice(1);
@@ -80,6 +95,14 @@ export async function main(argv) {
         await runConfig(subcommand, subArgs, flags);
         break;
       }
+      case "mcp": {
+        const subcommand = rest[0];
+        const subArgs = rest.slice(1);
+        if (!subcommand) { console.error("  Usage: qveris mcp <configure|validate> [target]"); process.exitCode = 2; return; }
+        const { runMcp } = await import("./commands/mcp.mjs");
+        await runMcp(subcommand, subArgs, flags);
+        break;
+      }
       case "interactive":
       case "repl": {
         const { runInteractive } = await import("./commands/interactive.mjs");
@@ -119,6 +142,12 @@ const VALUE_FLAGS = {
   "api-key": "apiKey", "base-url": "baseUrl", timeout: "timeout",
   limit: "limit", "discovery-id": "discoveryId", params: "params",
   "max-size": "maxSize", codegen: "codegen", token: "token",
+  query: "query", "tool-id": "toolId", target: "target", output: "output",
+  mode: "mode", "start-date": "startDate", "end-date": "endDate",
+  bucket: "bucket", "execution-id": "executionId", "search-id": "searchId",
+  "event-type": "eventType", kind: "kind", success: "success",
+  "charge-outcome": "chargeOutcome", "entry-type": "entryType",
+  direction: "direction", "min-credits": "minCredits", "max-credits": "maxCredits",
 };
 
 function takeNext(args, i, flag) {
@@ -177,6 +206,18 @@ function extractGlobalFlags(args) {
         flags.version = true; break;
       case "--dry-run":
         flags.dryRun = true; break;
+      case "--write":
+        flags.write = true; break;
+      case "--print":
+        flags.print = true; break;
+      case "--include-key":
+        flags.includeKey = true; break;
+      case "--validate":
+        flags.validate = true; break;
+      case "--probe":
+        flags.probe = true; break;
+      case "--resume":
+        flags.resume = true; break;
       case "--no-browser":
         flags.noBrowser = true; break;
       case "--clear":
@@ -199,6 +240,42 @@ function extractGlobalFlags(args) {
         flags.codegen = takeNext(args, i++, arg); break;
       case "--token":
         flags.token = takeNext(args, i++, arg); break;
+      case "--target":
+        flags.target = takeNext(args, i++, arg); break;
+      case "--output":
+        flags.output = takeNext(args, i++, arg); break;
+      case "--query":
+        flags.query = takeNext(args, i++, arg); break;
+      case "--tool-id":
+        flags.toolId = takeNext(args, i++, arg); break;
+      case "--mode":
+        flags.mode = takeNext(args, i++, arg); break;
+      case "--start-date":
+        flags.startDate = takeNext(args, i++, arg); break;
+      case "--end-date":
+        flags.endDate = takeNext(args, i++, arg); break;
+      case "--bucket":
+        flags.bucket = takeNext(args, i++, arg); break;
+      case "--execution-id":
+        flags.executionId = takeNext(args, i++, arg); break;
+      case "--search-id":
+        flags.searchId = takeNext(args, i++, arg); break;
+      case "--event-type":
+        flags.eventType = takeNext(args, i++, arg); break;
+      case "--kind":
+        flags.kind = takeNext(args, i++, arg); break;
+      case "--success":
+        flags.success = takeNext(args, i++, arg); break;
+      case "--charge-outcome":
+        flags.chargeOutcome = takeNext(args, i++, arg); break;
+      case "--entry-type":
+        flags.entryType = takeNext(args, i++, arg); break;
+      case "--direction":
+        flags.direction = takeNext(args, i++, arg); break;
+      case "--min-credits":
+        flags.minCredits = takeNext(args, i++, arg); break;
+      case "--max-credits":
+        flags.maxCredits = takeNext(args, i++, arg); break;
       default:
         flags._positional.push(arg);
     }
@@ -219,6 +296,7 @@ function printUsage(flags = {}) {
     qveris <command> [args] [flags]
 
   ${bold("Core Commands:")}
+    ${cyan("init")}                         Guided first-call wizard
     ${cyan("discover")} <query>             Find capabilities by natural language
     ${cyan("inspect")}  <tool_id|index>     View tool details, parameters, and stats
     ${cyan("call")}     <tool_id|index>     Execute a capability
@@ -228,9 +306,12 @@ function printUsage(flags = {}) {
     ${cyan("logout")}                       Remove stored API key
     ${cyan("whoami")}                       Show current auth status
     ${cyan("credits")}                      Show credit balance
+    ${cyan("usage")}                        Summarize or search usage audit history
+    ${cyan("ledger")}                       Summarize or search credit ledger entries
 
   ${bold("Configuration:")}
     ${cyan("config")}   set|get|list|reset  Manage CLI settings
+    ${cyan("mcp")}      configure|validate   Generate and validate MCP client config
 
   ${bold("Utilities:")}
     ${cyan("interactive")}                  Launch interactive REPL mode
@@ -243,6 +324,19 @@ function printUsage(flags = {}) {
     --api-key <key>        Override API key
     --base-url <url>       Override API base URL
     --timeout <seconds>    Request timeout
+    --target <target>      MCP target: cursor | claude-desktop | claude-code | opencode | openclaw | generic
+    --output <path>        MCP config output path
+    --write                Write MCP config to disk
+    --include-key          Include resolved API key instead of placeholder
+    --probe                Start MCP server and verify visible tools during validation
+    --query <query>        Init discovery query override
+    --tool-id <id>         Init selected capability override
+    --resume               Resume init from the last discovery session
+    --mode <mode>          summary | search | export-file for usage/ledger
+    --start-date <date>    Usage/ledger range start (YYYY-MM-DD)
+    --end-date <date>      Usage/ledger range end (YYYY-MM-DD)
+    --min-credits <n>      Usage/ledger amount lower bound
+    --max-credits <n>      Usage/ledger amount upper bound
     --no-color             Disable colors
     --verbose, -v          Show request details
     --version, -V          Print version
@@ -254,10 +348,17 @@ function printUsage(flags = {}) {
     QVERIS_BASE_URL        Custom API base URL
 
   ${bold("Examples:")}
+    qveris init
+    qveris init --query "weather forecast API"
+    qveris init --resume --params '{"city": "London"}'
     qveris discover "weather forecast API"
     qveris inspect 1
     qveris call 1 --params '{"city": "London"}'
     qveris call 1 --params @params.json --codegen curl
+    qveris mcp configure --target cursor --write --include-key
+    qveris mcp validate --target cursor
+    qveris usage --mode search --execution-id <id>
+    qveris ledger --mode search --min-credits 50 --direction consume
     qveris interactive
 
   ${dim("https://qveris.ai (global) / https://qveris.cn (China)")}