run402 1.53.1 → 1.54.1

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);

package/lib/deploy-v2.mjs

@@ -26,7 +26,7 @@
 import { readFileSync } from "node:fs";
 import { resolve, dirname, isAbsolute, join } from "node:path";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 import { allowanceAuthHeaders, resolveProjectId } from "./config.mjs";
 
 const APPLY_HELP = `run402 deploy apply — Unified deploy primitive (v1.34+)
@@ -107,8 +107,11 @@ export async function runDeployV2(sub, args) {
   if (sub === "resume") return await resumeCmd(args);
   if (sub === "list") return await listCmd(args);
   if (sub === "events") return await eventsCmd(args);
-  console.error(JSON.stringify({ status: "error", message: `Unknown deploy subcommand: ${sub}` }));
-  process.exit(1);
+  fail({
+    code: "BAD_USAGE",
+    message: `Unknown deploy subcommand: ${sub}`,
+    details: { subcommand: sub },
+  });
 }
 
 async function readStdin() {
@@ -142,8 +145,11 @@ async function applyCmd(args) {
       const manifestPath = isAbsolute(opts.manifest) ? opts.manifest : resolve(process.cwd(), opts.manifest);
       raw = readFileSync(manifestPath, "utf-8");
     } catch (err) {
-      console.error(JSON.stringify({ status: "error", message: `Failed to read manifest: ${err.message}` }));
-      process.exit(1);
+      fail({
+        code: "BAD_USAGE",
+        message: `Failed to read manifest: ${err.message}`,
+        details: { flag: "--manifest", path: opts.manifest },
+      });
     }
   } else {
     raw = await readStdin();
@@ -153,18 +159,21 @@ async function applyCmd(args) {
   try {
     spec = JSON.parse(raw);
   } catch (err) {
-    console.error(JSON.stringify({ status: "error", message: `Manifest is not valid JSON: ${err.message}` }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: `Manifest is not valid JSON: ${err.message}`,
+      details: { source: opts.manifest ? "manifest" : opts.spec ? "spec" : "stdin", parse_error: err.message },
+    });
   }
 
   if (opts.manifest) resolveFileDataPaths(spec, dirname(resolve(opts.manifest)));
 
   if (opts.project && spec.project_id && spec.project_id !== opts.project) {
-    console.error(JSON.stringify({
-      status: "error",
+    fail({
+      code: "BAD_USAGE",
       message: `project_id conflict: spec.project_id=${spec.project_id} but --project=${opts.project}`,
-    }));
-    process.exit(1);
+      details: { spec_project_id: spec.project_id, flag_project_id: opts.project },
+    });
   }
   if (opts.project) spec.project_id = opts.project;
   if (!spec.project_id) spec.project_id = resolveProjectId(null);
@@ -198,8 +207,11 @@ async function resumeCmd(args) {
     if (!args[i].startsWith("-") && !opts.operationId) opts.operationId = args[i];
   }
   if (!opts.operationId) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 deploy resume <operation_id>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <operation_id>.",
+      hint: "run402 deploy resume <operation_id>",
+    });
   }
 
   allowanceAuthHeaders("/deploy/v2/operations");
@@ -243,8 +255,11 @@ async function eventsCmd(args) {
     if (!args[i].startsWith("-") && !opts.operationId) opts.operationId = args[i];
   }
   if (!opts.operationId) {
-    console.error(JSON.stringify({ status: "error", message: "Usage: run402 deploy events <operation_id>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <operation_id>.",
+      hint: "run402 deploy events <operation_id>",
+    });
   }
 
   const project = resolveProjectId(opts.project);
@@ -383,11 +398,11 @@ function resolveFileDataPaths(spec, baseDir) {
           m.sql = readFileSync(p, "utf-8");
           delete m.sql_path;
         } catch (err) {
-          console.error(JSON.stringify({
-            status: "error",
+          fail({
+            code: "BAD_USAGE",
             message: `Failed to read migration sql_path '${m.sql_path}': ${err.message}`,
-          }));
-          process.exit(1);
+            details: { migration_id: m.id, sql_path: m.sql_path },
+          });
         }
       }
     }
@@ -421,10 +436,10 @@ function readFileEntry(entry, baseDir) {
     if (entry.contentType) out.contentType = entry.contentType;
     return out;
   } catch (err) {
-    console.error(JSON.stringify({
-      status: "error",
+    fail({
+      code: "BAD_USAGE",
       message: `Failed to read file '${entry.path}': ${err.message}`,
-    }));
-    process.exit(1);
+      details: { path: entry.path },
+    });
   }
 }

package/lib/deploy.mjs

@@ -3,7 +3,7 @@ import { dirname, resolve } from "path";
 import { resolveProjectId } from "./config.mjs";
 import { resolveFilePathsInManifest, resolveMigrationsFile } from "./manifest.mjs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 deploy — Deploy to an existing project on Run402
 
@@ -111,8 +111,8 @@ async function readStdin() {
  * Load + parse the manifest from --manifest file or stdin, and resolve any
  * referenced files[].path / migrations_file against the manifest's directory.
  *
- * Returns { manifest } on success, or { error } with a structured error object
- * on any fs / parse failure. Never throws.
+ * Returns the parsed manifest on success. On any fs / parse failure, calls
+ * `fail()` (which writes the canonical error envelope to stderr and exits 1).
  */
 async function loadManifest(opts) {
   let raw;
@@ -125,21 +125,18 @@ async function loadManifest(opts) {
       raw = readFileSync(opts.manifest, "utf-8");
     } catch (err) {
       if (err && err.code === "ENOENT") {
-        return { error: {
-          status: "error",
+        fail({
+          code: "BAD_USAGE",
           message: `File not found: ${manifestAbs}`,
-          field: "manifest",
-          path: manifestAbs,
           hint: "Check that --manifest points to an existing JSON file.",
-        } };
+          details: { field: "manifest", path: manifestAbs },
+        });
       }
-      return { error: {
-        status: "error",
+      fail({
+        code: "BAD_USAGE",
         message: err && err.message ? err.message : String(err),
-        field: "manifest",
-        path: manifestAbs,
-        ...(err && err.code ? { code: err.code } : {}),
-      } };
+        details: { field: "manifest", path: manifestAbs, ...(err && err.code ? { syscall_code: err.code } : {}) },
+      });
     }
   } else {
     raw = await readStdin();
@@ -149,12 +146,15 @@ async function loadManifest(opts) {
   try {
     manifest = JSON.parse(raw);
   } catch (err) {
-    return { error: {
-      status: "error",
+    fail({
+      code: "BAD_USAGE",
       message: `Manifest is not valid JSON: ${err.message}`,
-      field: opts.manifest ? "manifest" : "stdin",
-      ...(opts.manifest ? { path: resolve(opts.manifest) } : {}),
-    } };
+      details: {
+        field: opts.manifest ? "manifest" : "stdin",
+        ...(opts.manifest ? { path: resolve(opts.manifest) } : {}),
+        parse_error: err.message,
+      },
+    });
   }
 
   if (opts.manifest) {
@@ -163,25 +163,29 @@ async function loadManifest(opts) {
       resolveFilePathsInManifest(manifest, baseDir);
     } catch (err) {
       if (err && err.code === "ENOENT") {
-        return { error: {
-          status: "error",
+        fail({
+          code: "BAD_USAGE",
           message: `File not found: ${err.absPath || err.path || "<unknown>"}`,
-          field: err.field || "manifest",
-          ...(err.absPath || err.path ? { path: err.absPath || err.path } : {}),
           hint: `Paths in manifest.${err.field || "files[].path"} are resolved relative to the manifest file's directory (${baseDir}).`,
-        } };
+          details: {
+            field: err.field || "manifest",
+            ...(err.absPath || err.path ? { path: err.absPath || err.path } : {}),
+          },
+        });
       }
-      return { error: {
-        status: "error",
+      fail({
+        code: "BAD_USAGE",
         message: err && err.message ? err.message : String(err),
-        ...(err && err.field ? { field: err.field } : {}),
-        ...(err && (err.absPath || err.path) ? { path: err.absPath || err.path } : {}),
-        ...(err && err.code ? { code: err.code } : {}),
-      } };
+        details: {
+          ...(err && err.field ? { field: err.field } : {}),
+          ...(err && (err.absPath || err.path) ? { path: err.absPath || err.path } : {}),
+          ...(err && err.code ? { syscall_code: err.code } : {}),
+        },
+      });
     }
   }
 
-  return { manifest };
+  return manifest;
 }
 
 export async function run(args) {
@@ -210,25 +214,20 @@ export async function run(args) {
     if (args[i] === "--project" && args[i + 1]) opts.project = args[++i];
   }
 
-  const manifestResult = await loadManifest(opts);
-  if (manifestResult.error) {
-    console.error(JSON.stringify(manifestResult.error));
-    process.exit(1);
-  }
-  const manifest = manifestResult.manifest;
+  const manifest = await loadManifest(opts);
 
   // If both sources set project_id and they disagree, refuse to deploy rather
   // than silently shipping to the wrong target.
   if (opts.project && manifest.project_id && opts.project !== manifest.project_id) {
-    const err = {
-      status: "error",
+    fail({
+      code: "BAD_USAGE",
       message: `project_id conflict: manifest.project_id=${manifest.project_id} but --project=${opts.project}`,
-      manifest_project_id: manifest.project_id,
-      flag_project_id: opts.project,
       hint: "Remove one of them or make them match. The --project flag and manifest.project_id must agree (or only one of them must be set).",
-    };
-    console.error(JSON.stringify(err));
-    process.exit(1);
+      details: {
+        manifest_project_id: manifest.project_id,
+        flag_project_id: opts.project,
+      },
+    });
   }
 
   if (opts.project) manifest.project_id = opts.project;

package/lib/domains.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 domains — Manage custom domains
 
@@ -40,7 +40,13 @@ async function add(args) {
   const { project, rest } = parseProjectFlag(args);
   const domain = rest[0];
   const subdomainName = rest[1];
-  if (!domain || !subdomainName) { console.error("Usage: run402 domains add <domain> <subdomain_name> [--project <id>]"); process.exit(1); }
+  if (!domain || !subdomainName) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <domain> and/or <subdomain_name>.",
+      hint: "run402 domains add <domain> <subdomain_name> [--project <id>]",
+    });
+  }
   const projectId = resolveProjectId(project);
   try {
     const data = await getSdk().domains.add(projectId, domain, subdomainName);
@@ -63,7 +69,13 @@ async function list(projectIdArg) {
 async function status(args) {
   const { project, rest } = parseProjectFlag(args);
   const domain = rest[0];
-  if (!domain) { console.error("Usage: run402 domains status <domain> [--project <id>]"); process.exit(1); }
+  if (!domain) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <domain>.",
+      hint: "run402 domains status <domain> [--project <id>]",
+    });
+  }
   const projectId = resolveProjectId(project);
   try {
     const data = await getSdk().domains.status(projectId, domain);
@@ -76,15 +88,19 @@ async function status(args) {
 async function deleteDomain(args) {
   const { project, rest } = parseProjectFlag(args);
   const domain = rest.find((a) => !a.startsWith("--"));
-  if (!domain) { console.error("Usage: run402 domains delete <domain> --confirm [--project <id>]"); process.exit(1); }
+  if (!domain) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing <domain>.",
+      hint: "run402 domains delete <domain> --confirm [--project <id>]",
+    });
+  }
   if (!Array.isArray(args) || !args.includes("--confirm")) {
-    console.error(JSON.stringify({
-      status: "error",
+    fail({
       code: "CONFIRMATION_REQUIRED",
       message: `Destructive: releasing custom domain '${domain}' detaches it from this project and clears its DNS/SSL configuration. This is irreversible. Re-run with --confirm to proceed.`,
       details: { domain },
-    }));
-    process.exit(1);
+    });
   }
   const projectId = resolveProjectId(project);
   try {

package/lib/email.mjs

@@ -1,6 +1,6 @@
 import { resolveProjectId } 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 email — Send emails from your project
 
@@ -130,14 +130,12 @@ function parseVars(args) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--vars" && args[i + 1]) {
       const raw = args[++i];
-      let parsed;
-      try { parsed = JSON.parse(raw); } catch {
-        console.error(JSON.stringify({ status: "error", message: "Invalid JSON for --vars. Expected a JSON object, e.g. '{\"key\":\"value\"}'" }));
-        process.exit(1);
-      }
+      const parsed = parseFlagJson("--vars", raw);
       if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        console.error(JSON.stringify({ status: "error", message: "--vars must be a JSON object, e.g. '{\"key\":\"value\"}'" }));
-        process.exit(1);
+        fail({
+          code: "BAD_USAGE",
+          message: "--vars must be a JSON object, e.g. '{\"key\":\"value\"}'",
+        });
       }
       for (const [k, v] of Object.entries(parsed)) vars[k] = typeof v === "string" ? v : String(v);
     }
@@ -161,8 +159,11 @@ async function create(args) {
   }
   const projectId = resolveProjectId(projectOpt);
   if (!slug) {
-    console.error(JSON.stringify({ status: "error", message: "Missing slug. Usage: run402 email create <slug>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing slug.",
+      hint: "run402 email create <slug>",
+    });
   }
 
   try {
@@ -184,8 +185,7 @@ async function send(args) {
   const variables = parseVars(args);
 
   if (!to) {
-    console.error(JSON.stringify({ status: "error", message: "Missing --to <email>" }));
-    process.exit(1);
+    fail({ code: "BAD_USAGE", message: "Missing --to <email>" });
   }
 
   try {
@@ -228,8 +228,11 @@ async function get(args) {
   }
   const projectId = resolveProjectId(projectOpt);
   if (!messageId) {
-    console.error(JSON.stringify({ status: "error", message: "Missing message_id. Usage: run402 email get <message_id>" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing message_id.",
+      hint: "run402 email get <message_id>",
+    });
   }
   try {
     const data = await getSdk().email.get(projectId, messageId);
@@ -250,8 +253,11 @@ async function getRaw(args) {
   }
   const projectId = resolveProjectId(projectOpt);
   if (!messageId) {
-    console.error(JSON.stringify({ status: "error", message: "Missing message_id. Usage: run402 email get-raw <message_id> [--output <file>]" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing message_id.",
+      hint: "run402 email get-raw <message_id> [--output <file>]",
+    });
   }
 
   try {
@@ -286,12 +292,17 @@ async function reply(args) {
   const projectId = resolveProjectId(projectOpt);
 
   if (!messageId) {
-    console.error(JSON.stringify({ status: "error", message: "Missing message_id. Usage: run402 email reply <message_id> --html \"...\"" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Missing message_id.",
+      hint: 'run402 email reply <message_id> --html "..."',
+    });
   }
   if (!html && !text) {
-    console.error(JSON.stringify({ status: "error", message: "Provide --html and/or --text for the reply body" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Provide --html and/or --text for the reply body",
+    });
   }
 
   try {
@@ -299,12 +310,11 @@ async function reply(args) {
     const original = await getSdk().email.get(projectId, messageId);
     const replyTo = original.from || original.from_address || original.sender || null;
     if (!replyTo) {
-      console.error(JSON.stringify({
-        status: "error",
+      fail({
+        code: "BAD_USAGE",
         message: "Original message has no from address to reply to",
-        original_keys: Object.keys(original),
-      }));
-      process.exit(1);
+        details: { original_keys: Object.keys(original) },
+      });
     }
     const origSubject = typeof original.subject === "string" ? original.subject : "";
     const defaultSubject = origSubject && origSubject.toLowerCase().startsWith("re:")
@@ -339,11 +349,10 @@ async function deleteMailbox(args) {
   const confirmed = args.includes("--confirm");
 
   if (!confirmed) {
-    console.error(JSON.stringify({
-      status: "error",
+    fail({
+      code: "CONFIRMATION_REQUIRED",
       message: "Destructive: deleting a mailbox is irreversible (drops all messages and webhook subscriptions). Re-run with --confirm to proceed.",
-    }));
-    process.exit(1);
+    });
   }
 
   try {

package/lib/functions.mjs

@@ -1,7 +1,7 @@
 import { readFileSync } from "fs";
 import { findProject, 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 functions — Manage serverless functions
 
@@ -152,7 +152,9 @@ async function deploy(projectId, name, args) {
     if (args[i] === "--deps" && args[i + 1]) opts.deps = args[++i].split(",");
     if (args[i] === "--schedule" && i + 1 < args.length) opts.schedule = args[++i];
   }
-  if (!opts.file) { console.error(JSON.stringify({ status: "error", message: "Missing --file <file>" })); process.exit(1); }
+  if (!opts.file) {
+    fail({ code: "BAD_USAGE", message: "Missing --file <file>" });
+  }
   const code = readFileSync(opts.file, "utf-8");
 
   const deployOpts = { name, code };
@@ -212,7 +214,13 @@ async function logs(projectId, name, args) {
   if (since !== undefined) {
     const parsed = Number(since);
     const ms = Number.isNaN(parsed) ? new Date(since).getTime() : parsed;
-    if (Number.isNaN(ms)) { console.error(JSON.stringify({ status: "error", message: `Invalid --since value: ${since}` })); process.exit(1); }
+    if (Number.isNaN(ms)) {
+      fail({
+        code: "BAD_USAGE",
+        message: `Invalid --since value: ${since}`,
+        details: { flag: "--since", value: since },
+      });
+    }
     sinceIso = new Date(ms).toISOString();
   }
 
@@ -282,8 +290,10 @@ async function update(projectId, name, args) {
   if (memory !== undefined) updateOpts.memory = memory;
 
   if (Object.keys(updateOpts).length === 0) {
-    console.error(JSON.stringify({ status: "error", message: "Provide at least one of: --schedule, --schedule-remove, --timeout, --memory" }));
-    process.exit(1);
+    fail({
+      code: "BAD_USAGE",
+      message: "Provide at least one of: --schedule, --schedule-remove, --timeout, --memory",
+    });
   }
 
   try {

package/lib/image.mjs

@@ -1,6 +1,6 @@
 import { writeFileSync } from "fs";
 import { getSdk } from "./sdk.mjs";
-import { reportSdkError } from "./sdk-errors.mjs";
+import { reportSdkError, fail } from "./sdk-errors.mjs";
 
 const HELP = `run402 image — Generate AI images via x402 micropayments
 
@@ -49,7 +49,13 @@ export async function run(sub, args) {
     i++;
   }
 
-  if (!opts.prompt) { console.error(JSON.stringify({ status: "error", message: "Prompt required. Usage: run402 image generate \"your prompt\"" })); process.exit(1); }
+  if (!opts.prompt) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Prompt required.",
+      hint: 'run402 image generate "your prompt"',
+    });
+  }
 
   try {
     const data = await getSdk().ai.generateImage({ prompt: opts.prompt, aspect: opts.aspect });