agentsw 0.9.2 → 0.10.1

package/dist/discover.js

@@ -4,10 +4,15 @@ function modelListUrl(baseUrl) {
     if (url.protocol !== "https:" && url.protocol !== "http:")
         throw new Error("provider URL must use HTTP or HTTPS");
     const pathname = url.pathname.replace(/\/+$/, "");
-    url.pathname = /\/v\d+(?:beta\d*)?$/.test(pathname) ? `${pathname}/models` : `${pathname}/v1/models`;
+    url.pathname =
+        /\/v\d+(?:beta\d*)?$/.test(pathname) ? `${pathname}/models`
+            : /\/models$/.test(pathname) ? pathname
+                : `${pathname}/v1/models`;
     url.hash = "";
     return url;
 }
+/** Hard cap on model-list pages; an endpoint emitting endless fresh cursors must not loop forever. */
+export const MAX_MODEL_PAGES = 100;
 function parseModelPage(body) {
     if (!body || typeof body !== "object")
         throw new Error("invalid model-list response");
@@ -30,7 +35,7 @@ function parseModelPage(body) {
  * Resellers expose the id list here but no metadata (context, thinking, modalities) —
  * metadata is filled from models.dev afterwards (enrichModels).
  */
-export async function discoverProviderModels(opts) {
+export async function discoverProviderModels(opts, hooks = {}) {
     const url = modelListUrl(opts.baseUrl);
     const headers = opts.protocol === "anthropic"
         ? { "x-api-key": opts.apiKey, "anthropic-version": "2023-06-01" }
@@ -40,21 +45,25 @@ export async function discoverProviderModels(opts) {
     const initialCursor = url.searchParams.get("after_id");
     if (initialCursor)
         cursors.add(initialCursor);
-    while (true) {
+    for (let page = 1;; page++) {
+        if (page > MAX_MODEL_PAGES) {
+            throw new Error(`model-list pagination exceeded ${MAX_MODEL_PAGES} pages; the endpoint keeps reporting more models`);
+        }
         const res = await fetch(url.toString(), { headers, signal: AbortSignal.timeout(20000) });
         if (!res.ok)
             throw new Error(`model discovery -> HTTP ${res.status}`);
-        const page = parseModelPage(await res.json());
-        for (const id of page.ids)
+        const parsed = parseModelPage(await res.json());
+        for (const id of parsed.ids)
             ids.add(id);
-        if (!page.hasMore)
+        hooks.onPage?.({ page, count: ids.size });
+        if (!parsed.hasMore)
             break;
-        if (!page.lastId || !page.lastId.trim())
+        if (!parsed.lastId || !parsed.lastId.trim())
             throw new Error("model-list pagination is missing last_id");
-        if (cursors.has(page.lastId))
+        if (cursors.has(parsed.lastId))
             throw new Error("model-list pagination repeated a cursor");
-        cursors.add(page.lastId);
-        url.searchParams.set("after_id", page.lastId);
+        cursors.add(parsed.lastId);
+        url.searchParams.set("after_id", parsed.lastId);
     }
     if (ids.size === 0)
         throw new Error("provider returned no models");
@@ -65,7 +74,7 @@ export async function discoverProviderModels(opts) {
  * with each protocol's auth headers. Returns the protocols that responded
  * with a valid model list (at least one model id).
  */
-export async function probeProtocols(opts) {
+export async function probeProtocols(opts, hooks = {}) {
     const url = modelListUrl(opts.baseUrl).toString();
     const attempts = [
         { protocol: "openai", headers: { authorization: `Bearer ${opts.apiKey}` } },
@@ -73,6 +82,7 @@ export async function probeProtocols(opts) {
     ];
     const supported = [];
     for (const a of attempts) {
+        hooks.onAttempt?.(a.protocol);
         try {
             const res = await fetch(url, { headers: a.headers, signal: AbortSignal.timeout(15000) });
             if (!res.ok)

package/dist/gateway.js

@@ -2,10 +2,18 @@ import fs from "node:fs";
 import path from "node:path";
 import { readJsonIfExists, writeFileAtomic } from "./fsutil.js";
 import { configDir } from "./store.js";
+import { warn } from "./ui.js";
 const API_URL = "https://ai-gateway.vercel.sh/v1/models";
 const CACHE_FILE = path.join(configDir, "ai-gateway.json");
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 const MAX_BODY_BYTES = 5 * 1024 * 1024;
+/** Whole-request budget. A cold handshake through a tunnel measures ~3s here, so this is generous. */
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_ATTEMPTS = 2;
+const RETRY_DELAY_MS = 300;
+/** The endpoint answered — a status, an oversize body, a missing one. A retry repeats the answer. */
+class DefinitiveFailure extends Error {
+}
 const REASONING_EFFORTS = {
     none: true, minimal: true, low: true, medium: true, high: true, xhigh: true, max: true,
 };
@@ -136,10 +144,10 @@ async function readResponseBody(response) {
     const contentLength = response.headers.get("content-length");
     if (contentLength !== null && Number(contentLength) > MAX_BODY_BYTES) {
         await response.body?.cancel().catch(() => { });
-        throw new Error("AI Gateway catalog exceeds size limit");
+        throw new DefinitiveFailure("AI Gateway catalog exceeds size limit");
     }
     if (!response.body)
-        throw new Error("Missing AI Gateway catalog body");
+        throw new DefinitiveFailure("Missing AI Gateway catalog body");
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
     const chunks = [];
@@ -151,7 +159,7 @@ async function readResponseBody(response) {
                 break;
             size += value.byteLength;
             if (size > MAX_BODY_BYTES)
-                throw new Error("AI Gateway catalog exceeds size limit");
+                throw new DefinitiveFailure("AI Gateway catalog exceeds size limit");
             chunks.push(decoder.decode(value, { stream: true }));
         }
         chunks.push(decoder.decode());
@@ -165,6 +173,65 @@ async function readResponseBody(response) {
         reader.releaseLock();
     }
 }
+/** Diagnostics for a failure the user cannot otherwise see; opt in with AGENTSW_DEBUG=1. */
+function debug(message) {
+    if (process.env.AGENTSW_DEBUG !== "1")
+        return;
+    warn(message);
+}
+/** One-line reason for a failed attempt, for `AGENTSW_DEBUG` only — never part of the warning. */
+function describeFailure(error, timeoutMs) {
+    if (error instanceof Error && error.name === "TimeoutError")
+        return `no response within ${timeoutMs}ms`;
+    const cause = error instanceof Error ? error.cause : undefined;
+    const code = cause && typeof cause === "object" && "code" in cause ? ` (${String(cause.code)})` : "";
+    return `${error instanceof Error ? error.message : String(error)}${code}`;
+}
+/**
+ * Whole-request budget, overridable with `AGENTSW_GATEWAY_TIMEOUT_MS`. An unusable value is
+ * ignored rather than fatal: this is an escape hatch for a slow route, not configuration.
+ */
+function timeoutMs() {
+    const raw = process.env.AGENTSW_GATEWAY_TIMEOUT_MS;
+    if (raw === undefined)
+        return DEFAULT_TIMEOUT_MS;
+    const value = Number(raw);
+    return Number.isFinite(value) && value > 0 ? value : DEFAULT_TIMEOUT_MS;
+}
+async function requestOnce(budget) {
+    const response = await fetch(API_URL, {
+        signal: AbortSignal.timeout(budget),
+        credentials: "omit",
+        redirect: "error",
+    });
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => { });
+        throw new DefinitiveFailure(`HTTP ${response.status}`);
+    }
+    return readResponseBody(response);
+}
+/**
+ * Read the catalog text, retrying once when the attempt failed before the endpoint could
+ * answer. The likeliest failure by far is a transient one: a cold TLS handshake over whatever
+ * route this machine has measures an order of magnitude slower than a warm one, so a stall or a
+ * reset is far more common than a bad answer. A `DefinitiveFailure` is not retried — the second
+ * request would only repeat it — and neither is a body that arrived but would not parse, which
+ * is why parsing stays outside this call.
+ */
+async function requestCatalogText() {
+    const budget = timeoutMs();
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await requestOnce(budget);
+        }
+        catch (error) {
+            if (error instanceof DefinitiveFailure || attempt >= MAX_ATTEMPTS)
+                throw error;
+            debug(`AI Gateway attempt ${attempt} failed (${describeFailure(error, budget)}); retrying`);
+            await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+        }
+    }
+}
 /** Optional supplement: offline never fetches, and every failure leaves discovery usable. */
 export async function loadGatewayCatalog(opts = {}) {
     const cached = readCache();
@@ -173,29 +240,21 @@ export async function loadGatewayCatalog(opts = {}) {
     if (!opts.refresh && cached && Date.now() - Date.parse(cached.fetchedAt) < CACHE_TTL_MS)
         return cached;
     try {
-        const response = await fetch(API_URL, {
-            signal: AbortSignal.timeout(15_000),
-            credentials: "omit",
-            redirect: "error",
-        });
-        if (!response.ok) {
-            await response.body?.cancel().catch(() => { });
-            throw new Error("AI Gateway catalog request failed");
-        }
-        const body = JSON.parse(await readResponseBody(response));
+        const body = JSON.parse(await requestCatalogText());
         const catalog = parseGatewayCatalog(body, new Date().toISOString());
         try {
             writeFileAtomic(CACHE_FILE, JSON.stringify({ version: 1, fetchedAt: catalog.fetchedAt, body }) + "\n", 0o600);
         }
         catch {
-            process.stderr.write("warning: could not cache AI Gateway metadata\n");
+            warn("could not cache AI Gateway metadata");
         }
         return catalog;
     }
-    catch {
-        process.stderr.write(cached
-            ? "warning: could not refresh AI Gateway metadata; using cached metadata\n"
-            : "warning: could not load AI Gateway metadata\n");
+    catch (error) {
+        debug(`AI Gateway metadata unavailable: ${describeFailure(error, timeoutMs())}`);
+        warn(cached
+            ? "could not refresh AI Gateway metadata; using cached metadata"
+            : "could not load AI Gateway metadata");
         return cached;
     }
 }

package/dist/i18n.js

@@ -6,6 +6,7 @@ const messages = {
     "help.language": { en: "UI language: en | zh-CN (also AGENTSW_LANG)", "zh-CN": "界面语言: en | zh-CN (也可用 AGENTSW_LANG)" },
     "error.language": { en: "unsupported language \"{value}\"; use en or zh-CN", "zh-CN": "不支持语言 \"{value}\";请使用 en 或 zh-CN" },
     "error.unknownCommand": { en: "unknown command '{value}', see --help", "zh-CN": "未知命令 '{value}',请查看 --help" },
+    "error.limit": { en: "--limit must be a positive integer", "zh-CN": "--limit 必须是正整数" },
     "cmd.add": { en: "add or update a provider (interactive when flags are omitted)", "zh-CN": "添加或更新供应商(省略参数时进入交互流程)" },
     "cmd.quick": { en: "quick add — auto-detect protocol(s) and models from just base URL + API key", "zh-CN": "快速添加 — 只需 base URL + API key,自动探测协议和模型" },
     "cmd.list": { en: "list configured providers (or agent-local entries with --apps)", "zh-CN": "列出已配置供应商（--apps 可查看智能体独有配置）" },
@@ -130,8 +131,6 @@ const messages = {
     "menu.discoverFor": { en: "which provider's model list should be updated?", "zh-CN": "选择要更新模型列表的供应商" },
     "menu.pushRefresh": { en: "also sync this provider to agent configs after updating its model list?", "zh-CN": "更新模型列表后，是否同时将该供应商同步到智能体配置？" },
     "menu.removeProvider": { en: "which provider configuration should be deleted?", "zh-CN": "选择要删除配置的供应商" },
-    "menu.reallyRemove": { en: "really remove {id}?", "zh-CN": "确认删除 {id}?" },
-    "menu.pruneConfigs": { en: "also remove its entries from app configs?", "zh-CN": "同时从应用配置中移除其条目?" },
     "menu.upgrade": { en: "upgrade all installed agents that have updates?", "zh-CN": "是否升级所有有新版本的已安装智能体？" },
     "menu.installApp": { en: "Install a new coding agent", "zh-CN": "安装新的智能体" },
     "menu.pickApp": { en: "which agent to install?", "zh-CN": "安装哪个智能体?" },
@@ -149,7 +148,6 @@ const messages = {
     "add.baseUrlInvalid": { en: "must start with http(s)://", "zh-CN": "必须以 http(s):// 开头" },
     "add.apiKey": { en: "API key", "zh-CN": "API 密钥（API key）" },
     "add.models": { en: "model ids (comma separated, or leave blank to auto-discover)", "zh-CN": "模型 id(逗号分隔，留空则自动发现)" },
-    "add.cancelled": { en: "cancelled", "zh-CN": "已取消" },
     "import.already": { en: "already configured as {id}", "zh-CN": "已配置为 {id}" },
     "import.noneNew": { en: "nothing new to import (every discovered provider is already configured)", "zh-CN": "没有可导入的新供应商(发现项均已配置)" },
     "import.noneFound": { en: "no custom providers found in supported app configs or in cc-switch", "zh-CN": "支持的应用配置与 cc-switch 中均未发现自定义供应商" },
@@ -258,6 +256,152 @@ const messages = {
     },
     "refresh.checked": { en: "checked model metadata ({changed} provider(s) changed)", "zh-CN": "已检查模型元数据({changed} 个供应商有变化)" },
     "refresh.next": { en: "run `agentsw sync` to push updated metadata into app configs", "zh-CN": "运行 `agentsw sync` 将更新的元数据写入各智能体配置" },
+    "opt.json": {
+        en: "machine-readable JSON on stdout; disables prompts and progress",
+        "zh-CN": "stdout 输出机器可读 JSON(同时关闭交互提问与进度)",
+    },
+    "opt.quiet": {
+        en: "suppress progress, hints and warnings (keep results and errors)",
+        "zh-CN": "抑制进度、提示与警告(保留结果与错误)",
+    },
+    "opt.noColor": { en: "disable colored output (NO_COLOR also works)", "zh-CN": "关闭彩色输出(也支持 NO_COLOR)" },
+    "error.jsonRequiresCommand": {
+        en: "--json requires an explicit command (for example: agentsw status --json)",
+        "zh-CN": "--json 需要指定命令(例如 agentsw status --json)",
+    },
+    "common.cancelled": { en: "cancelled", "zh-CN": "已取消" },
+    "menu.cancelledAction": { en: "cancelled — back to menu", "zh-CN": "已取消 —— 返回菜单" },
+    "menu.back": { en: "← Back to main menu", "zh-CN": "← 返回主菜单" },
+    "progress.probe": { en: "probing {url} ({protocol}) …", "zh-CN": "正在探测 {url}({protocol})…" },
+    "progress.discoverPage": {
+        en: "listing models from {url} — page {page}, {count} models",
+        "zh-CN": "正在从 {url} 获取模型列表 —— 第 {page} 页,{count} 个模型",
+    },
+    "progress.catalog": { en: "loading models.dev catalog …", "zh-CN": "正在加载 models.dev 目录…" },
+    "progress.gateway": { en: "loading AI Gateway catalog …", "zh-CN": "正在加载 AI Gateway 目录…" },
+    "progress.metadata": { en: "supplementing model metadata …", "zh-CN": "正在补全模型元数据…" },
+    "progress.apps": {
+        en: "checking installed and latest versions … ({done}/{total})",
+        "zh-CN": "正在检查已安装版本与最新版本…({done}/{total})",
+    },
+    "progress.refresh": { en: "refreshing model metadata …", "zh-CN": "正在刷新模型元数据…" },
+    "add.retryDiscovery": {
+        en: "model discovery failed: {error}. Try again with the same endpoint?",
+        "zh-CN": "模型发现失败:{error}。用同一端点重试吗?",
+    },
+    "quick.retryProbe": {
+        en: "no protocol detected at {url}. Re-enter the base URL and API key?",
+        "zh-CN": "{url} 未探测到可用协议。重新输入 base URL 与 API key?",
+    },
+    "import.retryDiscovery": {
+        en: "discovery failed for {id}: {error}. Retry discovery for this provider?",
+        "zh-CN": "{id} 的模型发现失败:{error}。为该供应商重试?",
+    },
+    "import.skippedAfterFailure": {
+        en: "skipped {id}: discovery failed; add it later with agentsw add",
+        "zh-CN": "已跳过 {id}:发现失败;之后可用 agentsw add 补上",
+    },
+    "models.catalogUnavailable": {
+        en: "models.dev catalog unavailable (offline and no cache)\nrun: agentsw models --refresh (or check your network)",
+        "zh-CN": "models.dev 目录不可用(离线且无缓存)\n请运行 agentsw models --refresh(或检查网络)",
+    },
+    "models.usage": {
+        en: "usage: agentsw models <query> | agentsw models --provider <id>",
+        "zh-CN": "用法: agentsw models <查询> | agentsw models --provider <id>",
+    },
+    "models.noMatch": {
+        en: "no models.dev entries match \"{query}\"\nrun: agentsw models --refresh to update the catalog",
+        "zh-CN": "models.dev 中没有匹配 \"{query}\" 的条目\n请运行 agentsw models --refresh 更新目录",
+    },
+    "models.metadataRequiresProvider": {
+        en: "--metadata requires --provider (run: agentsw models --provider <id> --metadata)",
+        "zh-CN": "--metadata 需要配合 --provider(请运行 agentsw models --provider <id> --metadata)",
+    },
+    "status.noProviders": {
+        en: "no providers saved yet\nrun: agentsw add — or agentsw import to pull providers from your agents",
+        "zh-CN": "尚未保存任何供应商\n请运行 agentsw add,或用 agentsw import 从各智能体导入",
+    },
+    "apps.checking": { en: "checking installed and latest versions ...", "zh-CN": "正在检查已安装版本与最新版本..." },
+    "apps.notInstalled": { en: "not installed", "zh-CN": "未安装" },
+    "apps.installable": { en: "installable", "zh-CN": "可安装" },
+    "apps.upToDate": { en: "up to date", "zh-CN": "已是最新" },
+    "apps.upgradeAvailable": { en: "upgrade available", "zh-CN": "可升级" },
+    "apps.unknown": { en: "unknown", "zh-CN": "未知" },
+    "apps.checkFailedProbe": { en: "installed version check failed", "zh-CN": "已安装版本检查失败" },
+    "apps.checkFailedUnknown": { en: "installed version unknown", "zh-CN": "已安装版本未知" },
+    "apps.checkFailedLatest": { en: "latest version unavailable", "zh-CN": "无法获取最新版本" },
+    "apps.upgradeWith": { en: "upgrade with: agentsw upgrade {ids}", "zh-CN": "升级命令: agentsw upgrade {ids}" },
+    "install.unknownApp": { en: "unknown app \"{value}\" (supported: {apps})", "zh-CN": "未知应用 \"{value}\"(支持:{apps})" },
+    "install.notInstallable": {
+        en: "{name} is not installable on {platform} (or is managed by its desktop app)",
+        "zh-CN": "{name} 无法在 {platform} 上安装(或由桌面应用自行管理)",
+    },
+    "install.already": {
+        en: "{name} already installed ({version}); use `agentsw upgrade {id}`",
+        "zh-CN": "{name} 已安装({version});可用 `agentsw upgrade {id}`",
+    },
+    "install.installing": { en: "installing {name}: {command}", "zh-CN": "正在安装 {name}:{command}" },
+    "install.notDetected": {
+        en: "{name}: installer completed but the app is still not detected; check the installation and PATH",
+        "zh-CN": "{name}:安装命令已结束但仍未检测到该应用;请检查安装与 PATH",
+    },
+    "install.versionUnknown": {
+        en: "{name}: installer completed; app detected but version unknown",
+        "zh-CN": "{name}:安装命令已结束;检测到应用但版本未知",
+    },
+    "install.installed": { en: "{name} installed: {version}", "zh-CN": "{name} 已安装:{version}" },
+    "upgrade.unknownApps": { en: "unknown app(s): {ids}", "zh-CN": "未知应用:{ids}" },
+    "upgrade.checking": { en: "checking versions ...", "zh-CN": "正在检查版本..." },
+    "upgrade.statusUnknown": { en: "{id}: {reason}; update status unknown", "zh-CN": "{id}:{reason};升级状态未知" },
+    "upgrade.cannotDetermine": {
+        en: "could not determine update status for every installed app",
+        "zh-CN": "无法确定所有已安装应用的升级状态",
+    },
+    "upgrade.allCurrent": { en: "all checked apps are up to date", "zh-CN": "已检查的应用均为最新" },
+    "upgrade.none": { en: "no installed CLI-managed apps to upgrade", "zh-CN": "没有可升级的、由 CLI 管理的应用" },
+    "upgrade.notCli": { en: "{id}: not CLI-upgradable", "zh-CN": "{id}:不支持通过 CLI 升级" },
+    "upgrade.notInstalled": {
+        en: "{id}: not installed (use `agentsw install {id}`)",
+        "zh-CN": "{id}:未安装(请使用 `agentsw install {id}`)",
+    },
+    "upgrade.upgrading": { en: "upgrading {name}: {command}", "zh-CN": "正在升级 {name}:{command}" },
+    "upgrade.unknownVersion": {
+        en: "upgrade command completed but installed version is unknown or app is not detected",
+        "zh-CN": "升级命令已结束,但已安装版本未知或未检测到应用",
+    },
+    "upgrade.olderThanAvailable": {
+        en: "upgrade command completed but {version} is older than available {expected}",
+        "zh-CN": "升级命令已结束,但 {version} 低于可用的 {expected}",
+    },
+    "upgrade.done": { en: "{id} -> {version}", "zh-CN": "{id} -> {version}" },
+    "upgrade.failed": { en: "{id} upgrade failed: {message}", "zh-CN": "{id} 升级失败:{message}" },
+    "discover.defaultMissing": {
+        en: "default model {model} no longer listed; keeping it anyway",
+        "zh-CN": "默认模型 {model} 已不在列表中;仍然保留",
+    },
+    "discover.next": {
+        en: "run `agentsw sync` to push into app configs",
+        "zh-CN": "运行 `agentsw sync` 写入各智能体配置",
+    },
+    "dryRun.skip": { en: "skip", "zh-CN": "跳过" },
+    "dryRun.wouldWrite": {
+        en: "dry run — {count} file(s) would be written:",
+        "zh-CN": "预演 — 将写入 {count} 个文件:",
+    },
+    "preview.unchanged": { en: "unchanged", "zh-CN": "未变化" },
+    "preview.header": { en: "--- {file} (redacted configuration)", "zh-CN": "--- {file}(已脱敏配置)" },
+    "preview.contentWithheld": {
+        en: "[content withheld: unsupported or malformed configuration]",
+        "zh-CN": "[内容已隐去:配置格式不支持或无法解析]",
+    },
+    "preview.onlyRedacted": {
+        en: "[only redacted values or formatting changed]",
+        "zh-CN": "[仅脱敏值或格式发生变化]",
+    },
+    "preview.failedSafely": {
+        en: "configuration could not be previewed safely",
+        "zh-CN": "无法安全预览配置",
+    },
 };
 let current = detectSystemLocale();
 export function normalizeLocale(value) {

package/dist/index.js

@@ -6,6 +6,7 @@ import { detectSystemLocale, extractCliLocale, normalizeLocale, setLocale, t } f
 import { cmdMenu } from "./menu.js";
 import { loadStore } from "./store.js";
 import { cmdListLocalProviders, cmdRemoveProvider, cmdRename } from "./provider-actions.js";
+import { configureOutput, error, isJson, setCommandName } from "./ui.js";
 // Locale lookup is best effort: help/version and app-local commands do not need the store.
 function savedLocale() {
     try {
@@ -31,7 +32,16 @@ program
     .name("agentsw")
     .description(t("root.description"))
     .option("--lang <locale>", t("help.language"), parseLocale)
+    .option("--json", t("opt.json"))
+    .option("-q, --quiet", t("opt.quiet"))
+    .option("--no-color", t("opt.noColor"))
     .version(version);
+// Root options are accepted on either side of the subcommand; read the merged view and publish it once.
+program.hook("preAction", (_thisCommand, actionCommand) => {
+    const opts = actionCommand.optsWithGlobals();
+    configureOutput({ json: opts.json === true, quiet: opts.quiet === true, version });
+    setCommandName(actionCommand.name());
+});
 // bare invocation -> interactive menu (help on non-TTY); unknown subcommand -> error.
 // excess arguments are surfaced by us, so the message names the offending command.
 program
@@ -40,6 +50,9 @@ program
     const cmd = handlerArgs[handlerArgs.length - 1];
     if (cmd.args.length > 0)
         program.error(t("error.unknownCommand", { value: cmd.args[0] }));
+    // The menu is inherently interactive; reject instead of silently ignoring the flag.
+    if (isJson())
+        error(t("error.jsonRequiresCommand"));
     if (process.stdin.isTTY)
         return cmdMenu();
     program.outputHelp();
@@ -175,6 +188,5 @@ program
     .option("--gateway-models <json>", t("opt.gatewayModels"))
     .action(cmdRefreshMeta);
 program.parseAsync().catch((err) => {
-    process.stderr.write(`error: ${err.message}\n`);
-    process.exit(1);
+    error(err.message);
 });