run402 1.35.4 → 1.36.1

package/lib/email.mjs

@@ -56,6 +56,56 @@ Notes:
   - --project defaults to the active project
 `;
 
+const SUB_HELP = {
+  send: `run402 email send — Send an email (template or raw HTML)
+
+Usage:
+  run402 email send --to <email> --template <name> --var key=value [--var ...]
+  run402 email send --to <email> --subject "..." --html "..." [--text "..."]
+
+Options:
+  --to <email>        Recipient email address (required; single recipient)
+  --template <name>   Template name (template mode): project_invite, magic_link,
+                      notification
+  --var key=value     Template variable (repeatable; required keys vary by
+                      template)
+  --subject "..."     Subject line (raw HTML mode)
+  --html "..."        HTML body (raw HTML mode)
+  --text "..."        Plain-text body (raw HTML mode; optional)
+  --from-name "..."   Display name for the From header
+  --project <id>      Project ID (defaults to the active project)
+
+Templates:
+  project_invite      --var project_name=... --var invite_url=...
+  magic_link          --var project_name=... --var link_url=... --var expires_in=...
+  notification        --var project_name=... --var message=... (max 500 chars)
+
+Examples:
+  run402 email send --template project_invite --to user@example.com \\
+    --var project_name="My App" --var invite_url="https://example.com/invite/abc"
+  run402 email send --to user@example.com --subject "Welcome!" \\
+    --html "<h1>Hello</h1><p>Welcome aboard.</p>" --from-name "My App"
+  run402 email send --template notification --to admin@example.com \\
+    --var project_name="My App" --var message="Deploy complete"
+`,
+  "get-raw": `run402 email get-raw — Fetch raw RFC-822 bytes for an inbound message
+
+Usage:
+  run402 email get-raw <message_id> [--output <file>] [--project <id>]
+
+Arguments:
+  <message_id>        Message ID to fetch (inbound messages only)
+
+Options:
+  --output <file>     Write raw bytes to this file; omit to stream to stdout
+  --project <id>      Project ID (defaults to the active project)
+
+Examples:
+  run402 email get-raw msg_abc123 --output reply.eml
+  run402 email get-raw msg_abc123 > reply.eml
+`,
+};
+
 const SLUG_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 
 function parseFlag(args, flag) {
@@ -327,6 +377,7 @@ async function status(args) {
 
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h")) && sub !== "webhooks") { console.log(SUB_HELP[sub] || HELP); process.exit(0); }
   switch (sub) {
     case "create": await create(args); break;
     case "status": await status(args); break;

package/lib/functions.mjs

@@ -38,6 +38,95 @@ Notes:
   - Deploy may require payment if the project lease has expired
 `;
 
+const SUB_HELP = {
+  deploy: `run402 functions deploy — Deploy a function to a project
+
+Usage:
+  run402 functions deploy <project_id> <name> --file <file> [options]
+
+Arguments:
+  <project_id>        Target project ID
+  <name>              Function name (used in the invoke URL path)
+
+Options:
+  --file <file>       Required: path to the function source file
+  --timeout <s>       Runtime timeout in seconds
+  --memory <mb>       Memory in MB
+  --deps <pkg,...>    Comma-separated npm deps to bundle
+  --schedule <cron>   Cron schedule; pass '' to clear an existing schedule
+
+Notes:
+  Code must export a default async function:
+    export default async (req: Request) => Response
+  Deploy may require payment if the project lease has expired.
+
+Examples:
+  run402 functions deploy abc123 stripe-webhook --file handler.ts
+  run402 functions deploy abc123 send-reminders --file remind.ts \\
+    --schedule '*/15 * * * *'
+  run402 functions deploy abc123 send-reminders --file remind.ts --schedule ''
+`,
+  invoke: `run402 functions invoke — Invoke a deployed function
+
+Usage:
+  run402 functions invoke <project_id> <name> [options]
+
+Arguments:
+  <project_id>        Target project ID
+  <name>              Function name
+
+Options:
+  --method <M>        HTTP method (default POST)
+  --body <json>       Request body (ignored for GET/HEAD)
+
+Examples:
+  run402 functions invoke abc123 stripe-webhook --body '{"event":"test"}'
+  run402 functions invoke abc123 ping --method GET
+`,
+  logs: `run402 functions logs — Fetch or tail function logs
+
+Usage:
+  run402 functions logs <project_id> <name> [options]
+
+Arguments:
+  <project_id>        Target project ID
+  <name>              Function name
+
+Options:
+  --tail <n>          Number of most-recent entries (default 50)
+  --since <ts>        ISO timestamp or epoch ms; only entries after this
+  --follow            Poll every 3s and stream new entries (Ctrl-C to stop)
+
+Examples:
+  run402 functions logs abc123 stripe-webhook --tail 100
+  run402 functions logs abc123 stripe-webhook --since 2026-03-29T14:00:00Z
+  run402 functions logs abc123 stripe-webhook --follow
+`,
+  update: `run402 functions update — Update function config without re-deploying
+
+Usage:
+  run402 functions update <project_id> <name> [options]
+
+Arguments:
+  <project_id>        Target project ID
+  <name>              Function name
+
+Options:
+  --schedule <cron>   New cron schedule (pass '' to clear)
+  --schedule-remove   Explicitly remove the schedule
+  --timeout <s>       Runtime timeout in seconds
+  --memory <mb>       Memory in MB
+
+Notes:
+  Must provide at least one of the options above.
+
+Examples:
+  run402 functions update abc123 send-reminders --schedule '0 */4 * * *'
+  run402 functions update abc123 send-reminders --schedule-remove
+  run402 functions update abc123 my-func --timeout 15 --memory 256
+`,
+};
+
 async function deploy(projectId, name, args) {
   const p = findProject(projectId);
   const opts = { file: null, timeout: undefined, memory: undefined, deps: undefined, schedule: undefined };
@@ -213,7 +302,7 @@ async function deleteFunction(projectId, name) {
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
   if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
-    console.log(HELP);
+    console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }
   switch (sub) {

package/lib/init.mjs

@@ -112,16 +112,23 @@ export async function run(args = []) {
         });
         const data = await res.json();
         if (data.result) {
-          // Tempo faucet is instant — re-read balance once
-          try {
-            const raw = await client.readContract({ address: PATH_USD, abi: USDC_ABI, functionName: "balanceOf", args: [allowance.address] });
-            balance = Number(raw);
-          } catch {}
+          // Tempo faucet is "instant" on-chain, but the client RPC read can be
+          // racy relative to faucet settlement — poll up to 30s (GH-81), mirroring
+          // the x402 path below.
+          for (let i = 0; i < 30; i++) {
+            await new Promise(r => setTimeout(r, 1000));
+            try {
+              const raw = await client.readContract({ address: PATH_USD, abi: USDC_ABI, functionName: "balanceOf", args: [allowance.address] });
+              balance = Number(raw);
+              if (balance > 0) break;
+            } catch {}
+          }
           saveAllowance({ ...allowance, funded: true, lastFaucet: new Date().toISOString() });
+          summary.allowance.funded = true;
           if (balance > 0) {
             line("Balance", `${(balance / 1e6).toFixed(2)} pathUSD (funded)`);
           } else {
-            line("Balance", "faucet sent — checking balance...");
+            line("Balance", "faucet sent — not yet confirmed on-chain");
           }
         } else {
           line("Balance", `faucet failed: ${data.error?.message || "unknown error"}`);
@@ -131,6 +138,7 @@ export async function run(args = []) {
       }
     } else {
       line("Balance", `${(balance / 1e6).toFixed(2)} pathUSD`);
+      summary.allowance.funded = balance > 0;
     }
     summary.balance = { symbol: "pathUSD", usd_micros: balance };
   } else {
@@ -162,6 +170,7 @@ export async function run(args = []) {
           } catch {}
         }
         saveAllowance({ ...allowance, funded: true, lastFaucet: new Date().toISOString() });
+        summary.allowance.funded = true;
         if (balance > 0) {
           line("Balance", `${(balance / 1e6).toFixed(2)} USDC (funded)`);
         } else {
@@ -174,6 +183,7 @@ export async function run(args = []) {
       }
     } else {
       line("Balance", `${(balance / 1e6).toFixed(2)} USDC`);
+      summary.allowance.funded = balance > 0;
     }
     summary.balance = { symbol: "USDC", usd_micros: balance };
   }

package/lib/projects.mjs

@@ -1,5 +1,5 @@
 import { readFileSync } from "fs";
-import { findProject, loadKeyStore, saveProject, removeProject, API, allowanceAuthHeaders, setActiveProjectId, getActiveProjectId } from "./config.mjs";
+import { findProject, loadKeyStore, saveProject, removeProject, API, allowanceAuthHeaders, setActiveProjectId, getActiveProjectId, resolveProjectId } from "./config.mjs";
 
 const HELP = `run402 projects — Manage your deployed Run402 projects
 
@@ -11,17 +11,17 @@ Subcommands:
   provision [--tier <tier>] [--name <n>]  Provision a new Postgres project (pays via x402)
   use   <id>                              Set the active project (used as default for other commands)
   list                                    List all your projects (IDs, URLs, active marker)
-  info  <id>                              Show project details: REST URL, keys
-  keys  <id>                              Print anon_key and service_key as JSON
-  sql   <id> "<query>" [--file <path>] [--params '<json>']  Run a SQL query (supports parameterized queries)
-  rest  <id> <table> [params]             Query a table via the REST API (PostgREST)
-  usage <id>                              Show compute/storage usage for a project
-  schema <id>                             Inspect the database schema
-  rls   <id> <template> <tables_json>     Apply Row-Level Security policies
-  delete <id>                             Immediately and irreversibly delete a project (cascade purge) and remove from local state
-  pin   <id>                              Pin a project (prevents expiry/GC)
-  promote-user <id> <email>               Promote a user to project_admin role
-  demote-user  <id> <email>               Demote a user from project_admin role
+  info  [id]                              Show project details: REST URL, keys
+  keys  [id]                              Print anon_key and service_key as JSON
+  sql   [id] "<query>" [--file <path>] [--params '<json>']  Run a SQL query (supports parameterized queries)
+  rest  [id] <table> [params]             Query a table via the REST API (PostgREST)
+  usage [id]                              Show compute/storage usage for a project
+  schema [id]                             Inspect the database schema
+  rls   [id] <template> <tables_json>     Apply Row-Level Security policies
+  delete [id]                             Immediately and irreversibly delete a project (cascade purge) and remove from local state
+  pin   [id]                              Pin a project (prevents expiry/GC)
+  promote-user [id] <email>               Promote a user to project_admin role
+  demote-user  [id] <email>               Demote a user from project_admin role
 
 Examples:
   run402 projects quote
@@ -36,18 +36,66 @@ Examples:
   run402 projects rest abc123 users "limit=10&select=id,name"
   run402 projects usage abc123
   run402 projects schema abc123
-  run402 projects rls abc123 public_read '[{"table":"posts"}]'
+  run402 projects rls abc123 public_read_authenticated_write '[{"table":"posts"}]'
   run402 projects keys abc123
   run402 projects delete abc123
 
 Notes:
-  - <id> is the project_id shown in 'run402 projects list'
-  - Most commands that take <id> default to the active project if omitted
+  - <id> is the project_id shown in 'run402 projects list' (prefix: 'prj_')
+  - Most commands that take <id> default to the active project when omitted
+    (set it with 'run402 projects use <id>'). Project IDs start with 'prj_';
+    any first positional that doesn't is treated as the next argument instead.
   - 'rest' uses PostgREST query syntax (table name + optional query string)
   - 'provision' requires a funded allowance — payment is automatic via x402
-  - RLS templates: user_owns_rows, public_read, public_read_write
+  - RLS templates (prefer user_owns_rows for user-scoped data):
+      user_owns_rows                    users access only their own rows (requires owner_column)
+      public_read_authenticated_write   anyone reads; any authenticated user writes any row
+      public_read_write_UNRESTRICTED    fully open (anon_key writes); use 'run402 deploy' with a manifest
+                                        that includes "i_understand_this_is_unrestricted": true
 `;
 
+const SUB_HELP = {
+  provision: `run402 projects provision — Provision a new Postgres project
+
+Usage:
+  run402 projects provision [--tier <tier>] [--name <name>]
+
+Options:
+  --tier <tier>       Tier for the new project (default: prototype)
+  --name <name>       Human-readable name for the project
+
+Notes:
+  - Payment is automatic via x402; requires a funded allowance
+  - The new project becomes the active project after provisioning
+
+Examples:
+  run402 projects provision
+  run402 projects provision --tier prototype
+  run402 projects provision --tier hobby --name my-app
+`,
+  sql: `run402 projects sql — Run a SQL query against a project's database
+
+Usage:
+  run402 projects sql [id] "<query>" [options]
+  run402 projects sql [id] --file <path> [options]
+
+Arguments:
+  [id]                Project ID (defaults to the active project if omitted;
+                      must start with 'prj_' — any other first arg is treated
+                      as the query instead)
+  <query>             Inline SQL query (quote it to preserve spaces)
+
+Options:
+  --file <path>       Read SQL from a file instead of an inline query
+  --params '<json>'   JSON array of parameters for a parameterized query
+
+Examples:
+  run402 projects sql abc123 "SELECT * FROM users LIMIT 5"
+  run402 projects sql abc123 "SELECT * FROM users WHERE id = $1" --params '[42]'
+  run402 projects sql abc123 --file setup.sql
+`,
+};
+
 async function quote() {
   const res = await fetch(`${API}/tiers/v1`);
   const data = await res.json();
@@ -69,8 +117,34 @@ async function provision(args) {
     headers: { "Content-Type": "application/json", ...authHeaders },
     body: JSON.stringify(body),
   });
-  const data = await res.json();
-  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  // Content-type aware parsing: gateways (ALB, CloudFront, etc.) return HTML on
+  // 502/504/etc., which would otherwise crash res.json() with SyntaxError (GH-84).
+  const contentType = res.headers.get("content-type") || "";
+  let data = null;
+  let parseError = null;
+  let bodyText = null;
+  if (contentType.includes("application/json")) {
+    try {
+      data = await res.json();
+    } catch (e) {
+      parseError = e;
+      try { bodyText = await res.text(); } catch { bodyText = ""; }
+    }
+  } else {
+    try { bodyText = await res.text(); } catch { bodyText = ""; }
+  }
+  if (!res.ok || parseError || data === null) {
+    const err = { status: "error", http: res.status, content_type: contentType || null };
+    if (data && typeof data === "object") {
+      Object.assign(err, data);
+    } else {
+      const preview = typeof bodyText === "string" ? bodyText.slice(0, 500) : "";
+      err.body_preview = preview;
+      if (parseError) err.parse_error = "response body was not valid JSON";
+    }
+    console.error(JSON.stringify(err));
+    process.exit(1);
+  }
   // Save project credentials locally and set as active
   if (data.project_id) {
     saveProject(data.project_id, {
@@ -227,13 +301,26 @@ async function deleteProject(projectId) {
   }
 }
 
+// Resolve a positional project_id argument with active-project fallback (GH-102).
+// Heuristic: real project IDs start with "prj_". If args[0] is missing OR
+// doesn't start with "prj_", fall back to the active project and return the
+// full args array as remaining positionals. Otherwise consume args[0] as the
+// project_id and return args.slice(1) as remaining positionals.
+function resolvePositionalProject(args) {
+  const first = Array.isArray(args) ? args[0] : undefined;
+  if (typeof first === "string" && first.startsWith("prj_")) {
+    return { projectId: first, rest: args.slice(1) };
+  }
+  return { projectId: resolveProjectId(null), rest: Array.isArray(args) ? args : [] };
+}
+
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') {
     console.log(HELP);
     process.exit(0);
   }
   if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
-    console.log(HELP);
+    console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }
   switch (sub) {
@@ -241,17 +328,17 @@ export async function run(sub, args) {
     case "provision": await provision(args); break;
     case "use":       await use(args[0]); break;
     case "list":      await list(); break;
-    case "info":      await info(args[0]); break;
-    case "keys":      await keys(args[0]); break;
-    case "sql":       await sqlCmd(args[0], args.slice(1)); break;
-    case "rest":      await rest(args[0], args[1], args[2]); break;
-    case "usage":     await usage(args[0]); break;
-    case "schema":    await schema(args[0]); break;
-    case "rls":       await rls(args[0], args[1], args[2]); break;
-    case "delete":    await deleteProject(args[0]); break;
-    case "pin":          await pin(args[0]); break;
-    case "promote-user": await promoteUser(args[0], args[1]); break;
-    case "demote-user":  await demoteUser(args[0], args[1]); break;
+    case "info":      { const { projectId } = resolvePositionalProject(args); await info(projectId); break; }
+    case "keys":      { const { projectId } = resolvePositionalProject(args); await keys(projectId); break; }
+    case "sql":       { const { projectId, rest } = resolvePositionalProject(args); await sqlCmd(projectId, rest); break; }
+    case "rest":      { const { projectId, rest: restArgs } = resolvePositionalProject(args); await rest(projectId, restArgs[0], restArgs[1]); break; }
+    case "usage":     { const { projectId } = resolvePositionalProject(args); await usage(projectId); break; }
+    case "schema":    { const { projectId } = resolvePositionalProject(args); await schema(projectId); break; }
+    case "rls":       { const { projectId, rest } = resolvePositionalProject(args); await rls(projectId, rest[0], rest[1]); break; }
+    case "delete":    { const { projectId } = resolvePositionalProject(args); await deleteProject(projectId); break; }
+    case "pin":       { const { projectId } = resolvePositionalProject(args); await pin(projectId); break; }
+    case "promote-user": { const { projectId, rest } = resolvePositionalProject(args); await promoteUser(projectId, rest[0]); break; }
+    case "demote-user":  { const { projectId, rest } = resolvePositionalProject(args); await demoteUser(projectId, rest[0]); break; }
     default:
       console.error(`Unknown subcommand: ${sub}\n`);
       console.log(HELP);

package/lib/secrets.mjs

@@ -22,6 +22,31 @@ Notes:
   - Values are write-only — list returns keys with a value_hash (first 8 hex chars of SHA-256) for verifying the correct value was set
 `;
 
+const SUB_HELP = {
+  set: `run402 secrets set — Set a secret on a project
+
+Usage:
+  run402 secrets set <id> <key> <value> [--file <path>]
+  run402 secrets set <id> <key> --file <path>
+
+Arguments:
+  <id>                Project ID (from 'run402 projects list')
+  <key>               Secret key name (exposed as process.env.<key>)
+  <value>             Inline secret value (omit if using --file)
+
+Options:
+  --file <path>       Read the secret value from a file instead of inline
+
+Notes:
+  - Secrets are injected as process.env in serverless functions
+  - Values are write-only; 'list' returns a value_hash for verification
+
+Examples:
+  run402 secrets set abc123 STRIPE_KEY sk-1234
+  run402 secrets set abc123 TLS_CERT --file cert.pem
+`,
+};
+
 async function set(projectId, key, args = []) {
   const p = findProject(projectId);
   let file = null;
@@ -69,7 +94,7 @@ async function deleteSecret(projectId, key) {
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
   if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) {
-    console.log(HELP);
+    console.log(SUB_HELP[sub] || HELP);
     process.exit(0);
   }
   switch (sub) {

package/lib/sender-domain.mjs

@@ -117,6 +117,7 @@ async function inboundToggle(action, args) {
 
 export async function run(sub, args) {
   if (!sub || sub === "--help" || sub === "-h") { console.log(HELP); process.exit(0); }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) { console.log(HELP); process.exit(0); }
   switch (sub) {
     case "register": await register(args); break;
     case "status": await status(args); break;

package/lib/service.mjs

@@ -17,15 +17,15 @@ async function fetchAndEmit(path) {
   try {
     res = await fetch(`${API}${path}`);
   } catch (err) {
-    console.log(JSON.stringify({ error: "fetch_failed", message: err?.message || String(err) }));
-    return;
+    console.error(JSON.stringify({ status: "error", message: err?.message || String(err) }));
+    process.exit(1);
   }
   const text = await res.text();
   let body;
   try { body = JSON.parse(text); } catch { body = text; }
   if (!res.ok) {
-    console.log(JSON.stringify({ error: "non_2xx", status: res.status, body }, null, 2));
-    return;
+    console.error(JSON.stringify({ status: "error", http: res.status, body }));
+    process.exit(1);
   }
   console.log(JSON.stringify(body, null, 2));
 }

package/lib/sites.mjs

@@ -45,6 +45,41 @@ Notes:
   - Free with active tier — requires allowance auth
 `;
 
+const SUB_HELP = {
+  deploy: `run402 sites deploy — Deploy a static site from a manifest
+
+Usage:
+  run402 sites deploy --manifest <file> [--project <id>] [--target <target>] [--inherit]
+  cat manifest.json | run402 sites deploy [--project <id>] [--target <target>]
+
+Options:
+  --manifest <file>   Path to manifest JSON file (or read from stdin)
+  --project <id>      Project ID (defaults to the active project)
+  --target <target>   Deployment target (e.g. 'production')
+  --inherit           Copy unchanged files from the previous deployment
+                      (only upload changed files)
+
+Manifest format (JSON):
+  {
+    "files": [
+      { "file": "index.html", "data": "<html>...</html>" },
+      { "file": "style.css", "path": "./dist/style.css" }
+    ]
+  }
+  Paths are resolved relative to the manifest file's directory.
+  Binary files are auto-detected and base64-encoded.
+
+Notes:
+  - Must include at least index.html in the files array
+  - Free with active tier — requires allowance auth
+
+Examples:
+  run402 sites deploy --manifest site.json
+  run402 sites deploy --manifest site.json --target production --inherit
+  cat site.json | run402 sites deploy
+`,
+};
+
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);
@@ -96,6 +131,7 @@ async function status(args) {
 
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) { console.log(SUB_HELP[sub] || HELP); process.exit(0); }
   switch (sub) {
     case "deploy":  await deploy(args); break;
     case "status":  await status(args); break;

package/lib/storage.mjs

@@ -25,6 +25,29 @@ Notes:
   - Upload reads from --file or stdin if no --file is given
 `;
 
+const SUB_HELP = {
+  upload: `run402 storage upload — Upload a file to a project's storage bucket
+
+Usage:
+  run402 storage upload <id> <bucket> <path> [--file <local>] [--content-type <mime>]
+  echo "..." | run402 storage upload <id> <bucket> <path> [--content-type <mime>]
+
+Arguments:
+  <id>                Project ID (from 'run402 projects list')
+  <bucket>            Target bucket name
+  <path>              Destination path within the bucket
+
+Options:
+  --file <local>      Local file to upload; if omitted, content is read from stdin
+  --content-type <mime>  MIME type of the upload (default: text/plain)
+
+Examples:
+  run402 storage upload abc123 assets logo.png --file ./logo.png \\
+    --content-type image/png
+  echo "hello" | run402 storage upload abc123 data notes.txt
+`,
+};
+
 async function readStdin() {
   const chunks = [];
   for await (const chunk of process.stdin) chunks.push(chunk);
@@ -88,6 +111,7 @@ async function list(projectId, bucket) {
 
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) { console.log(SUB_HELP[sub] || HELP); process.exit(0); }
   switch (sub) {
     case "upload":   await upload(args[0], args[1], args[2], args.slice(3)); break;
     case "download": await download(args[0], args[1], args[2]); break;

package/lib/subdomains.mjs

@@ -24,6 +24,31 @@ Notes:
   - Creates <name>.run402.com pointing to the deployment
 `;
 
+const SUB_HELP = {
+  claim: `run402 subdomains claim — Claim a custom subdomain for a deployment
+
+Usage:
+  run402 subdomains claim <name> [--project <id>] [--deployment <id>]
+
+Arguments:
+  <name>              Subdomain name (3-63 chars, lowercase alphanumeric +
+                      hyphens). Creates <name>.run402.com.
+
+Options:
+  --project <id>      Project ID (defaults to the active project)
+  --deployment <id>   Deployment ID to point at (defaults to the project's
+                      last deployment)
+
+Notes:
+  - Legacy syntax 'claim <deployment_id> <name>' is still supported
+  - Deploy a site first (or pass --deployment) so there is a target to claim
+
+Examples:
+  run402 subdomains claim myapp
+  run402 subdomains claim myapp --deployment dpl_abc123 --project proj123
+`,
+};
+
 async function claim(positionalArgs, flagArgs) {
   const opts = { project: null, deployment: null };
   for (let i = 0; i < flagArgs.length; i++) {
@@ -85,6 +110,7 @@ async function list(projectId) {
 
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  if (Array.isArray(args) && (args.includes("--help") || args.includes("-h"))) { console.log(SUB_HELP[sub] || HELP); process.exit(0); }
   switch (sub) {
     case "claim": {
       const positional = [];

package/lib/tier.mjs

@@ -29,7 +29,14 @@ async function status() {
   const res = await fetch(`${API}/tiers/v1/status`, {
     headers: { ...authHeaders },
   });
-  const data = await res.json();
+  const text = await res.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    console.error(JSON.stringify({ status: "error", http: res.status, message: "Non-JSON response from server", body: text.slice(0, 500) }));
+    process.exit(1);
+  }
   if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
   console.log(JSON.stringify(data, null, 2));
 }