run402 1.54.0 → 1.54.2

package/lib/agent.mjs

@@ -1,6 +1,6 @@
 import { allowanceAuthHeaders } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 agent — Manage agent identity
 
@@ -24,7 +24,9 @@ async function contact(args) {
     if (args[i] === "--email" && args[i + 1]) email = args[++i];
     if (args[i] === "--webhook" && args[i + 1]) webhook = args[++i];
   }
-  if (!name) { console.error(JSON.stringify({ status: "error", message: "Missing --name <name>" })); process.exit(1); }
+  if (!name) {
+    fail({ code: "BAD_USAGE", message: "Missing --name <name>" });
+  }
   // Preserve the aggressive early exit when no allowance is configured.
   allowanceAuthHeaders("/agent/v1/contact");
 

package/lib/ai.mjs

@@ -1,6 +1,6 @@
 import { resolveProjectId } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 ai — AI translation and moderation tools
 
@@ -13,10 +13,10 @@ Subcommands:
   usage     <project_id>
 
 Examples:
-  run402 ai translate proj-001 "Hello world" --to es
-  run402 ai translate proj-001 "Hello" --to ja --from en --context "formal business email"
-  run402 ai moderate proj-001 "content to check"
-  run402 ai usage proj-001
+  run402 ai translate prj_abc123 "Hello world" --to es
+  run402 ai translate prj_abc123 "Hello" --to ja --from en --context "formal business email"
+  run402 ai moderate prj_abc123 "content to check"
+  run402 ai usage prj_abc123
 
 Notes:
   - translate requires the AI Translation add-on on the project
@@ -44,8 +44,8 @@ Notes:
   - Counts against the project's translation word quota
 
 Examples:
-  run402 ai translate proj-001 "Hello world" --to es
-  run402 ai translate proj-001 "Hello" --to ja --from en \\
+  run402 ai translate prj_abc123 "Hello world" --to es
+  run402 ai translate prj_abc123 "Hello" --to ja --from en \\
     --context "formal business email"
 `,
 };
@@ -76,8 +76,16 @@ async function translate(args) {
   const from = parseFlag(args, "--from");
   const context = parseFlag(args, "--context");
 
-  if (!text) { console.error(JSON.stringify({ status: "error", message: "Text required. Usage: run402 ai translate <project_id> <text> --to <lang>" })); process.exit(1); }
-  if (!to) { console.error(JSON.stringify({ status: "error", message: "--to <lang> is required" })); process.exit(1); }
+  if (!text) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Text required.",
+      hint: "run402 ai translate <project_id> <text> --to <lang>",
+    });
+  }
+  if (!to) {
+    fail({ code: "BAD_USAGE", message: "--to <lang> is required" });
+  }
 
   try {
     const data = await getSdk().ai.translate(projectId, { text, to, from: from ?? undefined, context: context ?? undefined });
@@ -101,7 +109,13 @@ async function moderate(args) {
   const projectId = resolveProjectId(projectOpt || positional[0]);
   text = positional[1] || null;
 
-  if (!text) { console.error(JSON.stringify({ status: "error", message: "Text required. Usage: run402 ai moderate <project_id> <text>" })); process.exit(1); }
+  if (!text) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Text required.",
+      hint: "run402 ai moderate <project_id> <text>",
+    });
+  }
 
   try {
     const data = await getSdk().ai.moderate(projectId, text);

package/lib/allowance.mjs

@@ -1,6 +1,6 @@
 import { readAllowance, saveAllowance, ALLOWANCE_FILE, API } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 allowance — Manage your agent allowance
 
@@ -82,7 +82,7 @@ async function status() {
     const data = await getSdk().allowance.status();
     if (!data.configured) {
       console.log(JSON.stringify({ status: "no_wallet", message: "No agent allowance found. Run: run402 allowance create" }));
-      return;
+      process.exit(1);
     }
     // Preserve CLI's rail field (SDK doesn't surface it; read from local allowance).
     const w = readAllowance();
@@ -115,8 +115,11 @@ async function create() {
   } catch (err) {
     const msg = (err instanceof Error) ? err.message : String(err);
     if (/already exists/i.test(msg)) {
-      console.log(JSON.stringify({ status: "error", message: "Agent allowance already exists. Use 'status' to check it." }));
-      process.exit(1);
+      fail({
+        code: "ALLOWANCE_EXISTS",
+        message: "Agent allowance already exists.",
+        hint: "Use 'status' to check it.",
+      });
     }
     reportSdkError(err);
   }
@@ -124,7 +127,13 @@ async function create() {
 
 async function fund() {
   const w = readAllowance();
-  if (!w) { console.log(JSON.stringify({ status: "error", message: "No agent allowance. Run: run402 allowance create" })); process.exit(1); }
+  if (!w) {
+    fail({
+      code: "NO_ALLOWANCE",
+      message: "No agent allowance.",
+      hint: "Run: run402 allowance create",
+    });
+  }
 
   if (w.rail === "mpp") {
     // Tempo Moderato faucet — instant, no polling needed
@@ -139,8 +148,11 @@ async function fund() {
     });
     const data = await res.json();
     if (data.error) {
-      console.log(JSON.stringify({ status: "error", message: data.error.message || "Tempo faucet failed" }));
-      process.exit(1);
+      fail({
+        code: "FAUCET_FAILED",
+        message: data.error.message || "Tempo faucet failed",
+        details: { rail: "mpp" },
+      });
     }
 
     // Re-read balance once (instant confirmation)
@@ -164,8 +176,11 @@ async function fund() {
   const res = await fetch(`${API}/faucet/v1`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ address: w.address }) });
   const data = await res.json();
   if (!res.ok) {
-    console.log(JSON.stringify({ status: "error", ...data }));
-    process.exit(1);
+    fail({
+      code: data?.code || "FAUCET_FAILED",
+      message: data?.message || "Faucet request failed",
+      details: { http: res.status, ...data },
+    });
   }
 
   const MAX_WAIT = 30;
@@ -196,7 +211,13 @@ async function readUsdcBalance(client, usdc, address) {
 
 async function balance() {
   const w = readAllowance();
-  if (!w) { console.log(JSON.stringify({ status: "error", message: "No agent allowance. Run: run402 allowance create" })); process.exit(1); }
+  if (!w) {
+    fail({
+      code: "NO_ALLOWANCE",
+      message: "No agent allowance.",
+      hint: "Run: run402 allowance create",
+    });
+  }
 
   const { createPublicClient, http, base, baseSepolia, tempoModerato } = await loadDeps();
   const mainnetClient = createPublicClient({ chain: base, transport: http() });
@@ -229,19 +250,30 @@ async function exportAddr() {
     const address = await getSdk().allowance.export();
     console.log(address);
   } catch {
-    console.log(JSON.stringify({ status: "error", message: "No agent allowance." }));
-    process.exit(1);
+    fail({ code: "NO_ALLOWANCE", message: "No agent allowance." });
   }
 }
 
 async function checkout(args) {
   const w = readAllowance();
-  if (!w) { console.log(JSON.stringify({ status: "error", message: "No agent allowance. Run: run402 allowance create" })); process.exit(1); }
+  if (!w) {
+    fail({
+      code: "NO_ALLOWANCE",
+      message: "No agent allowance.",
+      hint: "Run: run402 allowance create",
+    });
+  }
   let amount = null;
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--amount" && args[i + 1]) amount = parseInt(args[++i], 10);
   }
-  if (!amount) { console.error(JSON.stringify({ status: "error", message: "Missing --amount <usd_micros> (e.g. --amount 5000000 for $5)" })); process.exit(1); }
+  if (!amount) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --amount <usd_micros>",
+      hint: "e.g. --amount 5000000 for $5",
+    });
+  }
   const res = await fetch(`${API}/billing/v1/checkouts`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
@@ -254,7 +286,13 @@ async function checkout(args) {
 
 async function history(args) {
   const w = readAllowance();
-  if (!w) { console.log(JSON.stringify({ status: "error", message: "No agent allowance. Run: run402 allowance create" })); process.exit(1); }
+  if (!w) {
+    fail({
+      code: "NO_ALLOWANCE",
+      message: "No agent allowance.",
+      hint: "Run: run402 allowance create",
+    });
+  }
   let limit = 20;
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--limit" && args[i + 1]) limit = parseInt(args[++i], 10);

package/lib/apps.mjs

@@ -1,6 +1,6 @@
 import { allowanceAuthHeaders, saveProject } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 apps — Browse and manage the app marketplace
 
@@ -23,11 +23,11 @@ Examples:
   run402 apps browse
   run402 apps browse --tag auth
   run402 apps fork ver_abc123 my-todo --tier prototype
-  run402 apps publish proj123 --description "Todo app" --tags todo,auth --visibility public --fork-allowed
-  run402 apps versions proj123
+  run402 apps publish prj_abc123 --description "Todo app" --tags todo,auth --visibility public --fork-allowed
+  run402 apps versions prj_abc123
   run402 apps inspect ver_abc123
-  run402 apps update proj123 ver_abc123 --description "Updated" --tags todo
-  run402 apps delete proj123 ver_abc123
+  run402 apps update prj_abc123 ver_abc123 --description "Updated" --tags todo
+  run402 apps delete prj_abc123 ver_abc123
 `;
 
 const SUB_HELP = {
@@ -76,8 +76,8 @@ Options:
   --fork-allowed      Allow other users to fork this app
 
 Examples:
-  run402 apps publish proj123 --description "Todo app" --tags todo,auth
-  run402 apps publish proj123 --visibility public --fork-allowed
+  run402 apps publish prj_abc123 --description "Todo app" --tags todo,auth
+  run402 apps publish prj_abc123 --visibility public --fork-allowed
 `,
   update: `run402 apps update — Update a published version's metadata
 
@@ -96,9 +96,9 @@ Options:
   --no-fork           Disable forking for this version
 
 Examples:
-  run402 apps update proj123 ver_abc123 --description "Updated"
-  run402 apps update proj123 ver_abc123 --tags todo,auth --fork-allowed
-  run402 apps update proj123 ver_abc123 --no-fork
+  run402 apps update prj_abc123 ver_abc123 --description "Updated"
+  run402 apps update prj_abc123 ver_abc123 --tags todo,auth --fork-allowed
+  run402 apps update prj_abc123 ver_abc123 --no-fork
 `,
 };
 
@@ -177,7 +177,9 @@ async function versions(projectId) {
 }
 
 async function inspect(versionId) {
-  if (!versionId) { console.error(JSON.stringify({ status: "error", message: "Missing version ID" })); process.exit(1); }
+  if (!versionId) {
+    fail({ code: "BAD_USAGE", message: "Missing version ID" });
+  }
   try {
     const data = await getSdk().apps.getApp(versionId);
     console.log(JSON.stringify(data, null, 2));

package/lib/argparse.mjs

@@ -0,0 +1,147 @@
+import { fail } from "./sdk-errors.mjs";
+
+export function normalizeArgv(argv = []) {
+  const out = [];
+  for (const arg of argv ?? []) {
+    if (typeof arg === "string" && arg.startsWith("--") && arg.includes("=")) {
+      const eq = arg.indexOf("=");
+      out.push(arg.slice(0, eq), arg.slice(eq + 1));
+    } else {
+      out.push(arg);
+    }
+  }
+  return out;
+}
+
+export function hasHelp(args = []) {
+  return args.includes("--help") || args.includes("-h");
+}
+
+export function assertKnownFlags(args = [], knownFlags = [], flagsWithValues = []) {
+  const known = new Set(knownFlags);
+  const valueFlags = new Set(flagsWithValues);
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (valueFlags.has(arg)) {
+      i += 1;
+      continue;
+    }
+    if (typeof arg !== "string" || !arg.startsWith("-") || arg === "-") continue;
+    if (known.has(arg)) continue;
+    failUnknownFlag(arg, known);
+  }
+}
+
+export function failUnknownFlag(flag, knownFlags = []) {
+  const known = [...knownFlags].filter((f) => typeof f === "string" && f.startsWith("-"));
+  const closest = closestFlag(flag, known);
+  fail({
+    code: "UNKNOWN_FLAG",
+    message: closest ? `Unknown flag: ${flag}. Did you mean ${closest}?` : `Unknown flag: ${flag}.`,
+    details: { flag, closest: closest ? [closest] : [] },
+  });
+}
+
+export function flagValue(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx === -1) return null;
+  if (idx + 1 >= args.length) {
+    fail({
+      code: "BAD_FLAG",
+      message: `${flag} requires a value`,
+      details: { flag },
+    });
+  }
+  return args[idx + 1];
+}
+
+export function parseIntegerFlag(name, value, { min = 1, max = Number.POSITIVE_INFINITY, def } = {}) {
+  if (value === undefined || value === null) {
+    if (def !== undefined) return def;
+    fail({
+      code: "BAD_FLAG",
+      message: `${name} requires an integer value`,
+      details: { flag: name },
+    });
+  }
+  const raw = String(value);
+  if (!/^-?\d+$/.test(raw)) {
+    fail({
+      code: "BAD_FLAG",
+      message: `${name} must be an integer, got: ${raw}`,
+      details: { flag: name, value: raw },
+    });
+  }
+  const n = Number.parseInt(raw, 10);
+  if (n < min) {
+    fail({
+      code: "BAD_FLAG",
+      message: `${name} must be >= ${min}, got: ${n}`,
+      details: { flag: name, value: n, min },
+    });
+  }
+  if (n > max) {
+    fail({
+      code: "BAD_FLAG",
+      message: `${name} must be <= ${max}, got: ${n}`,
+      details: { flag: name, value: n, max },
+    });
+  }
+  return n;
+}
+
+export function failBadProjectId(value) {
+  fail({
+    code: "BAD_PROJECT_ID",
+    message: `Argument '${value}' is not a project id. Project IDs must start with 'prj_'.`,
+    hint: "Omit the project id to use the active project, or pass the full prj_... id.",
+    details: { value, expected_prefix: "prj_" },
+  });
+}
+
+export function positionalArgs(args = [], flagsWithValues = []) {
+  const valueFlags = new Set(flagsWithValues);
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (valueFlags.has(arg)) {
+      i += 1;
+      continue;
+    }
+    if (typeof arg === "string" && arg.startsWith("-")) continue;
+    out.push(arg);
+  }
+  return out;
+}
+
+function closestFlag(flag, candidates) {
+  let best = null;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const candidate of candidates) {
+    const d = levenshtein(flag, candidate);
+    if (d < bestDistance) {
+      best = candidate;
+      bestDistance = d;
+    }
+  }
+  if (!best) return null;
+  return bestDistance <= 3 ? best : null;
+}
+
+function levenshtein(a, b) {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  const curr = Array.from({ length: b.length + 1 }, () => 0);
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1] + 1,
+        prev[j] + 1,
+        prev[j - 1] + cost,
+      );
+    }
+    for (let j = 0; j <= b.length; j++) prev[j] = curr[j];
+  }
+  return prev[b.length];
+}

package/lib/auth.mjs

@@ -1,6 +1,6 @@
 import { findProject, resolveProjectId, API } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 auth — Manage project user authentication
 
@@ -93,7 +93,7 @@ Notes:
 
 Examples:
   run402 auth settings --allow-password-set true
-  run402 auth settings --allow-password-set false --project abc123
+  run402 auth settings --allow-password-set false --project prj_abc123
 `,
   providers: `run402 auth providers — List available auth providers
 
@@ -105,7 +105,7 @@ Options:
 
 Examples:
   run402 auth providers
-  run402 auth providers --project abc123
+  run402 auth providers --project prj_abc123
 `,
 };
 
@@ -121,8 +121,12 @@ async function magicLink(args) {
   const redirect = parseFlag(args, "--redirect");
   const projectId = resolveProjectId(parseFlag(args, "--project"));
 
-  if (!email) { console.error(JSON.stringify({ status: "error", message: "Missing --email" })); process.exit(1); }
-  if (!redirect) { console.error(JSON.stringify({ status: "error", message: "Missing --redirect <url>" })); process.exit(1); }
+  if (!email) {
+    fail({ code: "BAD_USAGE", message: "Missing --email" });
+  }
+  if (!redirect) {
+    fail({ code: "BAD_USAGE", message: "Missing --redirect <url>" });
+  }
 
   try {
     await getSdk().auth.requestMagicLink(projectId, { email, redirectUrl: redirect });
@@ -136,7 +140,9 @@ async function verify(args) {
   const token = parseFlag(args, "--token");
   const projectId = resolveProjectId(parseFlag(args, "--project"));
 
-  if (!token) { console.error(JSON.stringify({ status: "error", message: "Missing --token" })); process.exit(1); }
+  if (!token) {
+    fail({ code: "BAD_USAGE", message: "Missing --token" });
+  }
 
   try {
     const data = await getSdk().auth.verifyMagicLink(projectId, token);
@@ -152,8 +158,12 @@ async function setPassword(args) {
   const currentPassword = parseFlag(args, "--current");
   const projectId = resolveProjectId(parseFlag(args, "--project"));
 
-  if (!accessToken) { console.error(JSON.stringify({ status: "error", message: "Missing --token <bearer_token>" })); process.exit(1); }
-  if (!newPassword) { console.error(JSON.stringify({ status: "error", message: "Missing --new <password>" })); process.exit(1); }
+  if (!accessToken) {
+    fail({ code: "BAD_USAGE", message: "Missing --token <bearer_token>" });
+  }
+  if (!newPassword) {
+    fail({ code: "BAD_USAGE", message: "Missing --new <password>" });
+  }
 
   try {
     await getSdk().auth.setUserPassword(projectId, {
@@ -171,7 +181,12 @@ async function settings(args) {
   const allowPasswordSet = parseFlag(args, "--allow-password-set");
   const projectId = resolveProjectId(parseFlag(args, "--project"));
 
-  if (allowPasswordSet === null) { console.error(JSON.stringify({ status: "error", message: "Missing --allow-password-set <true|false>" })); process.exit(1); }
+  if (allowPasswordSet === null) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --allow-password-set <true|false>",
+    });
+  }
 
   try {
     await getSdk().auth.settings(projectId, { allow_password_set: allowPasswordSet === "true" });

package/lib/billing.mjs

@@ -1,6 +1,6 @@
 import { API } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 billing — Email billing accounts, Stripe tier checkout, email packs
 
@@ -97,8 +97,11 @@ function parseFlag(args, flag) {
 async function createEmail(args) {
   const email = args[0];
   if (!email) {
-    console.error(JSON.stringify({ status: "error", message: "Missing email. Usage: run402 billing create-email <email>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing email.",
+      hint: "run402 billing create-email <email>",
+    });
   }
   try {
     const data = await getSdk().billing.createEmailAccount(email);
@@ -112,8 +115,11 @@ async function linkWallet(args) {
   const accountId = args[0];
   const wallet = args[1];
   if (!accountId || !wallet) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 billing link-wallet <account_id> <wallet>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <account_id> and/or <wallet>.",
+      hint: "run402 billing link-wallet <account_id> <wallet>",
+    });
   }
   try {
     await getSdk().billing.linkWallet(accountId, wallet);
@@ -126,14 +132,16 @@ async function linkWallet(args) {
 async function tierCheckout(args) {
   const tier = args[0];
   if (!tier) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 billing tier-checkout <tier> [--email <e> | --wallet <w>]" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <tier>.",
+      hint: "run402 billing tier-checkout <tier> [--email <e> | --wallet <w>]",
+    });
   }
   const email = parseFlag(args, "--email");
   const wallet = parseFlag(args, "--wallet");
   if (!email && !wallet) {
-    console.error(JSON.stringify({ status: "error", message: "Must provide --email or --wallet" }));
-    process.exit(1);
+    fail({ code: "BAD_USAGE", message: "Must provide --email or --wallet" });
   }
   try {
     const data = await getSdk().billing.tierCheckout(tier, { email: email ?? undefined, wallet: wallet ?? undefined });
@@ -147,8 +155,7 @@ async function buyPack(args) {
   const email = parseFlag(args, "--email");
   const wallet = parseFlag(args, "--wallet");
   if (!email && !wallet) {
-    console.error(JSON.stringify({ status: "error", message: "Must provide --email or --wallet" }));
-    process.exit(1);
+    fail({ code: "BAD_USAGE", message: "Must provide --email or --wallet" });
   }
   try {
     const data = await getSdk().billing.buyEmailPack({ email: email ?? undefined, wallet: wallet ?? undefined });
@@ -162,8 +169,11 @@ async function autoRecharge(args) {
   const accountId = args[0];
   const state = args[1];
   if (!accountId || !state || !["on", "off"].includes(state)) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 billing auto-recharge <account_id> <on|off> [--threshold <n>]" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <account_id> and/or <on|off>.",
+      hint: "run402 billing auto-recharge <account_id> <on|off> [--threshold <n>]",
+    });
   }
   const thresholdStr = parseFlag(args, "--threshold");
   try {
@@ -182,8 +192,11 @@ async function balance(args) {
   // Accepts email OR wallet — SDK only models wallet, so keep direct fetch.
   const id = args[0];
   if (!id) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 billing balance <email-or-wallet>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <email-or-wallet>.",
+      hint: "run402 billing balance <email-or-wallet>",
+    });
   }
   const res = await fetch(`${API}/billing/v1/accounts/${encodeURIComponent(id)}`);
   const data = await res.json();
@@ -194,8 +207,11 @@ async function balance(args) {
 async function history(args) {
   const id = args[0];
   if (!id) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 billing history <email-or-wallet> [--limit <n>]" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <email-or-wallet>.",
+      hint: "run402 billing history <email-or-wallet> [--limit <n>]",
+    });
   }
   const limit = parseFlag(args, "--limit") || "50";
   const res = await fetch(`${API}/billing/v1/accounts/${encodeURIComponent(id)}/history?limit=${encodeURIComponent(limit)}`);