@qverisai/cli 0.3.0 → 0.4.0

package/README.md

@@ -104,9 +104,9 @@ qveris call 1 --params '{"wfo": "LWX", "x": 90, "y": 90}'
 
 | Command | Description |
 |---------|-------------|
-| `qveris login` | Authenticate with API key (opens browser or `--token` for direct input) |
+| `qveris login` | Authenticate with API key (interactive region selection, opens browser, or `--token` for direct input) |
 | `qveris logout` | Remove stored key |
-| `qveris whoami` | Show current auth status and key source |
+| `qveris whoami` | Show current auth status, key source, and region |
 | `qveris credits` | Check credit balance |
 
 ### Utilities
@@ -114,7 +114,7 @@ qveris call 1 --params '{"wfo": "LWX", "x": 90, "y": 90}'
 | 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 doctor` | Self-check: Node.js version, API key, region, connectivity |
 | `qveris config <subcommand>` | Manage CLI settings (set, get, list, reset, path) |
 | `qveris completions <shell>` | Generate shell completions (bash/zsh/fish) |
 
@@ -251,13 +251,18 @@ The API region is auto-detected from your key prefix:
 | `sk-xxx` | Global | `https://qveris.ai/api/v1` |
 | `sk-cn-xxx` | China | `https://qveris.cn/api/v1` |
 
-No extra configuration needed. To override manually:
+No extra configuration needed. `qveris login` prompts for region selection interactively on first use.
+
+**Agent / script usage:** Use `--token` with a region-prefixed key, or set environment variables:
 
 ```bash
-# Via environment variable
+# Key prefix auto-detection (recommended)
+qveris login --token "sk-cn-xxx"
+
+# Or environment variable
 export QVERIS_REGION=cn
 
-# Or set a custom base URL
+# Or custom base URL
 export QVERIS_BASE_URL=https://custom.endpoint/api/v1
 
 # Or per-command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qverisai/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "QVeris CLI -- discover, inspect, and call 10,000+ capabilities",
   "type": "module",
   "bin": {

package/src/commands/config.mjs

@@ -1,5 +1,6 @@
 import { getConfigPath, getConfigValue, setConfigValue, writeConfig } from "../config/store.mjs";
-import { resolveAll } from "../config/resolve.mjs";
+import { resolve, resolveAll } from "../config/resolve.mjs";
+import { resolveBaseUrl } from "../config/region.mjs";
 import { bold, dim, cyan } from "../output/colors.mjs";
 import { outputJson } from "../output/json.mjs";
 
@@ -64,11 +65,17 @@ function configGet(key, flags) {
 
 function configList(flags) {
   const all = resolveAll();
+
+  // Resolve effective region
+  const { value: apiKey } = resolve("api_key", flags.apiKey);
+  const { region, source: regionSource, baseUrl } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
+
   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 };
     }
+    obj._region = { region, source: regionSource, baseUrl };
     outputJson(obj);
     return;
   }
@@ -78,6 +85,7 @@ function configList(flags) {
     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(`\n  ${bold("Effective region:")} ${region} ${dim(`(${regionSource})`)} → ${dim(baseUrl)}`);
   console.log();
 }
 

package/src/commands/credits.mjs

@@ -1,11 +1,14 @@
 import { resolveApiKey } from "../client/auth.mjs";
 import { discoverTools } from "../client/api.mjs";
+import { resolveBaseUrl, getSiteUrl } from "../config/region.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 { region, baseUrl } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
+  const accountUrl = `${getSiteUrl(region, baseUrl)}/account`;
 
   const spinner = flags.json ? { stop() {} } : createSpinner("Checking credits...");
 
@@ -20,10 +23,10 @@ export async function runCredits(flags) {
       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`);
+      console.log(`  ${dim("Manage at:")} ${cyan(accountUrl)}\n`);
     } else {
       console.log(`\n  ${dim("Credit balance not available in API response.")}`);
-      console.log(`  Check at: ${cyan("https://qveris.ai/account")}\n`);
+      console.log(`  Check at: ${cyan(accountUrl)}\n`);
     }
   } catch (err) {
     spinner.stop();

package/src/commands/discover.mjs

@@ -1,5 +1,6 @@
 import { resolveApiKey } from "../client/auth.mjs";
 import { discoverTools } from "../client/api.mjs";
+import { resolveBaseUrl } from "../config/region.mjs";
 import { writeSession } from "../session/session.mjs";
 import { formatDiscoverResult } from "../output/formatter.mjs";
 import { outputJson } from "../output/json.mjs";
@@ -25,9 +26,12 @@ export async function runDiscover(query, flags) {
 
     // Store richer session data for index resolution
     const tools = result.results ?? [];
+    const { region, baseUrl: resolvedBaseUrl } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
     writeSession({
       discoveryId: result.search_id,
       query,
+      region,
+      baseUrl: resolvedBaseUrl,
       results: tools.map((t, i) => ({
         index: i + 1,
         tool_id: t.tool_id,

package/src/commands/doctor.mjs

@@ -1,5 +1,6 @@
 import { resolve } from "../config/resolve.mjs";
 import { discoverTools } from "../client/api.mjs";
+import { resolveBaseUrl } from "../config/region.mjs";
 import { bold, green, red, dim, cyan } from "../output/colors.mjs";
 
 export async function runDoctor(flags) {
@@ -22,6 +23,10 @@ export async function runDoctor(flags) {
     const masked = apiKey.slice(0, 6) + "..." + apiKey.slice(-4);
     console.log(`  ${green("\u2713")} API key configured (${masked} via ${source})`);
 
+    // Show resolved region
+    const { baseUrl, region, source: regionSource } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey });
+    console.log(`  ${green("\u2713")} Region: ${region} ${dim(`(${regionSource})`)} → ${dim(baseUrl)}`);
+
     // Test connectivity
     process.stderr.write(`  \u2026 Testing API connectivity...\r`);
     try {

package/src/commands/interactive.mjs

@@ -1,6 +1,7 @@
 import { createInterface } from "node:readline";
 import { resolveApiKey } from "../client/auth.mjs";
 import { discoverTools, inspectToolsByIds, callTool } from "../client/api.mjs";
+import { resolveBaseUrl } from "../config/region.mjs";
 import { resolveParams } from "../utils/params.mjs";
 import { formatDiscoverResult, formatInspectResult, formatCallResult } from "../output/formatter.mjs";
 import { generateSnippet } from "../output/codegen.mjs";
@@ -14,6 +15,7 @@ import { createSpinner } from "../output/spinner.mjs";
 export async function runInteractive(flags) {
   const apiKey = resolveApiKey(flags.apiKey);
   const baseUrl = flags.baseUrl;
+  const { region, baseUrl: resolvedBaseUrl } = resolveBaseUrl({ baseUrlFlag: baseUrl, apiKey });
   const limit = parseInt(flags.limit, 10) || 5;
   const discoverTimeout = (parseInt(flags.timeout, 10) || 30) * 1000;
   const callTimeout = (parseInt(flags.timeout, 10) || 60) * 1000;
@@ -63,7 +65,7 @@ export async function runInteractive(flags) {
             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 });
+          writeSession({ discoveryId: result.search_id, query, region, baseUrl: resolvedBaseUrl, results: state.results });
           console.log(formatDiscoverResult(result));
           break;
         }

package/src/commands/login.mjs

@@ -5,11 +5,10 @@ import { resolve } from "../config/resolve.mjs";
 import { setConfigValue, deleteConfigValue } from "../config/store.mjs";
 import { discoverTools } from "../client/api.mjs";
 import { VERSION } from "../config/defaults.mjs";
+import { resolveBaseUrl, getSiteUrl } from "../config/region.mjs";
 import { bold, green, red, dim, cyan } from "../output/colors.mjs";
 import { printLoginBanner } from "../output/banner.mjs";
 
-const ACCOUNT_URL = "https://qveris.ai/account?page=api-keys";
-
 function openBrowser(url) {
   const cmds = { darwin: "open", win32: "cmd", linux: "xdg-open" };
   const cmd = cmds[platform()] || "xdg-open";
@@ -87,9 +86,54 @@ function prompt(question) {
   });
 }
 
+/**
+ * Prompt user to select region interactively.
+ * Skipped if region is already determined via --base-url, QVERIS_REGION, or QVERIS_BASE_URL.
+ */
+function promptRegion() {
+  return new Promise((pResolve, pReject) => {
+    console.log(`  ${bold("Select your region / 选择站点区域:")}\n`);
+    console.log(`    ${cyan("1)")} Global  — qveris.ai  (International users)`);
+    console.log(`    ${cyan("2)")} China   — qveris.cn  (中国大陆用户)\n`);
+
+    if (!process.stdin.isTTY) {
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      rl.question("  Enter 1 or 2: ", (answer) => { rl.close(); pResolve(answer.trim()); });
+      return;
+    }
+
+    process.stderr.write("  Enter 1 or 2: ");
+
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      try { process.stdin.setRawMode(false); } catch {}
+      process.stdin.pause();
+    };
+    const onExit = () => { try { process.stdin.setRawMode(false); } catch {} };
+    process.once("exit", onExit);
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf-8");
+
+    const onData = (chunk) => {
+      const ch = chunk[0];
+      if (ch === "\x03") { cleanup(); process.removeListener("exit", onExit); process.stderr.write("\n"); pReject(new Error("Aborted")); return; }
+      if (ch === "1" || ch === "2") {
+        cleanup();
+        process.removeListener("exit", onExit);
+        process.stderr.write(`${ch}\n`);
+        pResolve(ch);
+      }
+      // Ignore other keys
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
 export async function runLogin(flags) {
   if (flags.token) {
-    await validateAndSave(flags.token);
+    await validateAndSave(flags.token, flags.baseUrl);
     return;
   }
 
@@ -97,10 +141,29 @@ export async function runLogin(flags) {
     printLoginBanner({ version: VERSION, noColor: flags.noColor });
   }
 
-  console.log(`  Get your API key at: ${cyan(ACCOUNT_URL)}\n`);
+  // Determine region: if already set via flag/env, use that; otherwise ask the user.
+  const { region: presetRegion, baseUrl: presetBaseUrl, source: regionSource } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl });
+  let region;
+  let baseUrl = presetBaseUrl;
+  if (regionSource !== "default") {
+    // Region explicitly configured — use it directly
+    region = presetRegion;
+  } else {
+    // No explicit region — let user choose interactively
+    let choice;
+    try {
+      choice = await promptRegion();
+    } catch {
+      return; // Ctrl+C
+    }
+    region = choice === "2" ? "cn" : "global";
+  }
+
+  const accountUrl = `${getSiteUrl(region, baseUrl)}/account?page=api-keys`;
+  console.log(`\n  Get your API key at: ${cyan(accountUrl)}\n`);
 
   if (!flags.noBrowser) {
-    openBrowser(ACCOUNT_URL);
+    openBrowser(accountUrl);
   }
 
   let key;
@@ -116,18 +179,21 @@ export async function runLogin(flags) {
     return;
   }
 
-  await validateAndSave(key);
+  await validateAndSave(key, flags.baseUrl);
 }
 
-async function validateAndSave(key) {
+async function validateAndSave(key, baseUrlFlag) {
   process.stderr.write(`  Validating key...`);
 
+  const { baseUrl, region, source } = resolveBaseUrl({ baseUrlFlag, apiKey: key });
+
   try {
-    await discoverTools({ apiKey: key, query: "test", limit: 1, timeoutMs: 10000 });
+    await discoverTools({ apiKey: key, baseUrl, query: "test", limit: 1, timeoutMs: 10000 });
     setConfigValue("api_key", key);
     const masked = key.slice(0, 6) + "..." + key.slice(-4);
     console.error(`\r\x1b[K`);
     console.log(`  ${green("\u2713")} Authenticated as ${bold(masked)}`);
+    console.log(`  ${dim("Region:")} ${region} ${dim(`(${source})`)}`);
     console.log(`  ${dim("Key saved to config.")}`);
   } catch {
     console.error(`\r\x1b[K`);
@@ -151,15 +217,17 @@ export async function runWhoami(flags) {
   }
 
   const masked = key.slice(0, 6) + "..." + key.slice(-4);
+  const { baseUrl, region, source: regionSource } = resolveBaseUrl({ baseUrlFlag: flags.baseUrl, apiKey: key });
 
   process.stderr.write(`  Validating...`);
 
   try {
-    await discoverTools({ apiKey: key, query: "test", limit: 1, timeoutMs: 10000 });
+    await discoverTools({ apiKey: key, baseUrl, query: "test", limit: 1, timeoutMs: 10000 });
     process.stderr.write("\r\x1b[K");
     console.log(`\n  ${green("\u2713")} Authenticated`);
     console.log(`  Key:    ${bold(masked)}`);
     console.log(`  Source: ${dim(source)}`);
+    console.log(`  Region: ${region} ${dim(`(${regionSource})`)}`);
   } catch {
     console.error(`\r\x1b[K`);
     console.log(`\n  ${red("\u2718")} Key ${masked} is ${red("invalid")}`);

package/src/config/region.mjs

@@ -13,6 +13,26 @@ const REGION_URLS = {
   cn: "https://qveris.cn/api/v1",
 };
 
+const SITE_URLS = {
+  global: "https://qveris.ai",
+  cn: "https://qveris.cn",
+};
+
+/**
+ * Get the site URL (not API URL) for a given region.
+ * For custom regions, attempts to infer from the base URL domain.
+ * @param {string} region
+ * @param {string} [baseUrl] - The resolved API base URL (used to infer site for custom regions)
+ * @returns {string}
+ */
+export function getSiteUrl(region, baseUrl) {
+  if (region === "custom" && baseUrl) {
+    if (baseUrl.includes("qveris.cn")) return SITE_URLS.cn;
+    if (baseUrl.includes("qveris.ai")) return SITE_URLS.global;
+  }
+  return SITE_URLS[region] || SITE_URLS.global;
+}
+
 /**
  * Detect region from API key prefix.
  * @param {string} apiKey

package/src/main.mjs

@@ -241,12 +241,18 @@ function printUsage(flags = {}) {
   ${bold("Global Flags:")}
     --json, -j             Output raw JSON
     --api-key <key>        Override API key
+    --base-url <url>       Override API base URL
     --timeout <seconds>    Request timeout
     --no-color             Disable colors
     --verbose, -v          Show request details
     --version, -V          Print version
     --help, -h             Show help
 
+  ${bold("Environment Variables:")}
+    QVERIS_API_KEY         API key
+    QVERIS_REGION          Region override (global | cn)
+    QVERIS_BASE_URL        Custom API base URL
+
   ${bold("Examples:")}
     qveris discover "weather forecast API"
     qveris inspect 1
@@ -254,6 +260,6 @@ function printUsage(flags = {}) {
     qveris call 1 --params @params.json --codegen curl
     qveris interactive
 
-  ${dim("https://qveris.ai")}
+  ${dim("https://qveris.ai (global) / https://qveris.cn (China)")}
 `);
 }