run402 1.54.0 → 1.54.1

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
 
@@ -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
 
@@ -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/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
 
@@ -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)}`);

package/lib/blob.mjs

@@ -36,7 +36,7 @@ import { pipeline } from "node:stream/promises";
 
 import { resolveProject, 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 blob — Direct-to-S3 blob storage
 
@@ -182,9 +182,8 @@ Examples:
 
 const UPLOAD_STATE_DIR = join(homedir(), ".run402", "uploads");
 
-function die(msg, code = 1) {
-  console.error(JSON.stringify({ status: "error", message: msg }));
-  process.exit(code);
+function die(msg, exit_code = 1) {
+  fail({ code: "BAD_USAGE", message: msg, exit_code });
 }
 
 function parseArgs(args) {

package/lib/cdn.mjs

@@ -15,7 +15,7 @@
 
 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 cdn — CloudFront CDN diagnostics for public blob URLs
 
@@ -68,9 +68,8 @@ Examples:
 `,
 };
 
-function die(msg, code = 1) {
-  console.error(JSON.stringify({ status: "error", message: msg }));
-  process.exit(code);
+function die(msg, exit_code = 1) {
+  fail({ code: "BAD_USAGE", message: msg, exit_code });
 }
 
 function parseArgs(args) {

package/lib/config.mjs

@@ -7,6 +7,7 @@ import { getApiBase, getConfigDir, getKeystorePath, getAllowancePath } from "../
 import { readAllowance as coreReadAllowance, saveAllowance as coreSaveAllowance } from "../core-dist/allowance.js";
 import { loadKeyStore, getProject, saveProject, updateProject, removeProject, saveKeyStore, getActiveProjectId, setActiveProjectId } from "../core-dist/keystore.js";
 import { getAllowanceAuthHeaders as coreGetAllowanceAuthHeaders } from "../core-dist/allowance-auth.js";
+import { fail } from "./sdk-errors.mjs";
 
 export const CONFIG_DIR = getConfigDir();
 export const ALLOWANCE_FILE = getAllowancePath();
@@ -23,31 +24,54 @@ export function saveAllowance(data) {
 
 export function allowanceAuthHeaders(path) {
   const headers = coreGetAllowanceAuthHeaders(path);
-  if (!headers) { console.error(JSON.stringify({ status: "error", message: "No agent allowance found. Run: run402 allowance create" })); process.exit(1); }
+  if (!headers) {
+    fail({
+      code: "NO_ALLOWANCE",
+      message: "No agent allowance found.",
+      hint: "Run: run402 allowance create",
+    });
+  }
   return headers;
 }
 
 export function findProject(id) {
   const p = getProject(id);
   if (!p) {
-    const hint = id && !id.startsWith("prj_")
-      ? ` Hint: project IDs start with "prj_". Check that the argument order is <project_id> <name>.`
-      : "";
-    console.error(`Project ${id} not found in local registry.${hint}`);
-    process.exit(1);
+    const idStr = id ?? "";
+    const hint = idStr && !String(idStr).startsWith("prj_")
+      ? `project IDs start with "prj_". Check that the argument order is <project_id> <name>.`
+      : undefined;
+    fail({
+      code: "PROJECT_NOT_FOUND",
+      message: `Project ${idStr} not found in local registry.`,
+      hint,
+      details: { project_id: idStr, source: "local_registry" },
+    });
   }
   return p;
 }
 
 export function resolveProject(id) {
   const projectId = id || getActiveProjectId();
-  if (!projectId) { console.error("Error: no project specified and no active project set. Run: run402 projects provision"); process.exit(1); }
+  if (!projectId) {
+    fail({
+      code: "NO_ACTIVE_PROJECT",
+      message: "no project specified and no active project set.",
+      hint: "Run: run402 projects provision",
+    });
+  }
   return findProject(projectId);
 }
 
 export function resolveProjectId(id) {
   const projectId = id || getActiveProjectId();
-  if (!projectId) { console.error("Error: no project specified and no active project set. Run: run402 projects provision"); process.exit(1); }
+  if (!projectId) {
+    fail({
+      code: "NO_ACTIVE_PROJECT",
+      message: "no project specified and no active project set.",
+      hint: "Run: run402 projects provision",
+    });
+  }
   return projectId;
 }
 

package/lib/contracts.mjs

@@ -1,6 +1,6 @@
 import { findProject, API } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail, parseFlagJson } from "./sdk-errors.mjs";
 
 const HELP = `run402 contracts — KMS-backed Ethereum wallets for smart-contract calls
 
@@ -100,8 +100,10 @@ async function provisionWallet(projectId, args) {
   const p = findProject(projectId);
   const chain = parseFlag(args, "--chain");
   if (!chain) {
-    console.error(JSON.stringify({ status: "error", message: "Missing --chain (base-mainnet or base-sepolia)" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing --chain (base-mainnet or base-sepolia)",
+    });
   }
   const recovery = parseFlag(args, "--recovery");
   // Soft default of one wallet — confirm if project already has one. This
@@ -115,8 +117,11 @@ async function provisionWallet(projectId, args) {
       const list = await listRes.json();
       const active = (list.wallets || []).filter((w) => w.status === "active");
       if (active.length >= 1 && !hasFlag(args, "--yes")) {
-        console.error(`This project already has ${active.length} active wallet(s). Adding another costs $0.04/day each ($1.20/month). Re-run with --yes to confirm.`);
-        process.exit(1);
+        fail({
+          code: "CONFIRMATION_REQUIRED",
+          message: `This project already has ${active.length} active wallet(s). Adding another costs $0.04/day each ($1.20/month). Re-run with --yes to confirm.`,
+          details: { active_wallets: active.length },
+        });
       }
     }
   } catch { /* best-effort */ }
@@ -154,8 +159,10 @@ async function setRecovery(projectId, walletId, args) {
   const clear = hasFlag(args, "--clear");
   const address = parseFlag(args, "--address");
   if (!clear && !address) {
-    console.error(JSON.stringify({ status: "error", message: "Provide --address 0x... or --clear" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Provide --address 0x... or --clear",
+    });
   }
   try {
     await getSdk().contracts.setRecovery(projectId, walletId, clear ? null : address);
@@ -168,8 +175,7 @@ async function setRecovery(projectId, walletId, args) {
 async function setAlert(projectId, walletId, args) {
   const threshold = parseFlag(args, "--threshold-wei");
   if (!threshold) {
-    console.error(JSON.stringify({ status: "error", message: "Missing --threshold-wei <n>" }));
-    process.exit(1);
+    fail({ code: "BAD_USAGE", message: "Missing --threshold-wei <n>" });
   }
   try {
     await getSdk().contracts.setLowBalanceAlert(projectId, walletId, threshold);
@@ -188,17 +194,22 @@ async function call(projectId, walletId, args) {
   const chain = parseFlag(args, "--chain") || "base-mainnet";
   const idempotency = parseFlag(args, "--idempotency-key");
   if (!to || !abi || !fn || !argsJson) {
-    console.error(JSON.stringify({ status: "error", message: "Required flags: --to, --abi, --fn, --args. Cost: chain gas + $0.000005 KMS sign fee." }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Required flags: --to, --abi, --fn, --args.",
+      hint: "Cost: chain gas + $0.000005 KMS sign fee.",
+    });
   }
+  const abiFragment = parseFlagJson("--abi", abi);
+  const callArgs = parseFlagJson("--args", argsJson);
   try {
     const data = await getSdk().contracts.call(projectId, {
       walletId,
       chain,
       contractAddress: to,
-      abiFragment: JSON.parse(abi),
+      abiFragment,
       functionName: fn,
-      args: JSON.parse(argsJson),
+      args: callArgs,
       value: value ?? undefined,
       idempotencyKey: idempotency ?? undefined,
     });
@@ -215,16 +226,20 @@ async function read(args) {
   const fn = parseFlag(args, "--fn");
   const argsJson = parseFlag(args, "--args");
   if (!chain || !to || !abi || !fn || !argsJson) {
-    console.error(JSON.stringify({ status: "error", message: "Required flags: --chain, --to, --abi, --fn, --args" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Required flags: --chain, --to, --abi, --fn, --args",
+    });
   }
+  const abiFragment = parseFlagJson("--abi", abi);
+  const callArgs = parseFlagJson("--args", argsJson);
   try {
     const data = await getSdk().contracts.read({
       chain,
       contractAddress: to,
-      abiFragment: JSON.parse(abi),
+      abiFragment,
       functionName: fn,
-      args: JSON.parse(argsJson),
+      args: callArgs,
     });
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
@@ -244,8 +259,11 @@ async function status(projectId, callId) {
 async function drain(projectId, walletId, args) {
   const to = parseFlag(args, "--to");
   if (!to || !hasFlag(args, "--confirm")) {
-    console.error(JSON.stringify({ status: "error", message: "Required: --to 0x... and --confirm. Cost: chain gas + $0.000005 KMS sign fee." }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Required: --to 0x... and --confirm.",
+      hint: "Cost: chain gas + $0.000005 KMS sign fee.",
+    });
   }
   try {
     const data = await getSdk().contracts.drain(projectId, walletId, to);
@@ -257,8 +275,7 @@ async function drain(projectId, walletId, args) {
 
 async function deleteWallet(projectId, walletId, args) {
   if (!hasFlag(args, "--confirm")) {
-    console.error(JSON.stringify({ status: "error", message: "Required: --confirm" }));
-    process.exit(1);
+    fail({ code: "BAD_USAGE", message: "Required: --confirm" });
   }
   try {
     const data = await getSdk().contracts.deleteWallet(projectId, walletId);