run402 1.36.0 → 1.36.1

package/lib/ai.mjs

@@ -22,6 +22,32 @@ Notes:
   - usage shows translation word quota for the current billing period
 `;
 
+const SUB_HELP = {
+  translate: `run402 ai translate — Translate text to another language
+
+Usage:
+  run402 ai translate <project_id> <text> --to <lang> [--from <lang>] [--context <hint>]
+
+Arguments:
+  <project_id>        Project ID (defaults to the active project if omitted)
+  <text>              Text to translate (quote it to preserve spaces)
+
+Options:
+  --to <lang>         Target language code (required, e.g. es, ja, fr)
+  --from <lang>       Source language code (optional; auto-detected if omitted)
+  --context <hint>    Optional translation hint (e.g. "formal business email")
+
+Notes:
+  - Requires the AI Translation add-on on the project
+  - 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 \\
+    --context "formal business email"
+`,
+};
+
 function parseFlag(args, flag) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === flag && args[i + 1]) return args[i + 1];
@@ -119,6 +145,7 @@ async function usage(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 "translate": await translate(args); break;
     case "moderate":  await moderate(args); break;

package/lib/allowance.mjs

@@ -29,6 +29,33 @@ Examples:
   run402 allowance history --limit 10
 `;
 
+const SUB_HELP = {
+  checkout: `run402 allowance checkout — Create a billing checkout session
+
+Usage:
+  run402 allowance checkout --amount <usd_micros>
+
+Options:
+  --amount <n>        Amount in USD micros (required; e.g. 5000000 for $5)
+
+Examples:
+  run402 allowance checkout --amount 5000000
+  run402 allowance checkout --amount 10000000
+`,
+  history: `run402 allowance history — View billing transaction history
+
+Usage:
+  run402 allowance history [--limit <n>]
+
+Options:
+  --limit <n>         Max entries to return (default: 20)
+
+Examples:
+  run402 allowance history
+  run402 allowance history --limit 10
+`,
+};
+
 const USDC_ABI = [{ name: "balanceOf", type: "function", stateMutability: "view", inputs: [{ name: "account", type: "address" }], outputs: [{ name: "", type: "uint256" }] }];
 const USDC_MAINNET = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
 const USDC_SEPOLIA = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
@@ -213,6 +240,10 @@ export async function run(sub, args) {
     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 "status":  await status(); break;
     case "create":  await create(); break;

package/lib/apps.mjs

@@ -28,6 +28,78 @@ Examples:
   run402 apps delete proj123 ver_abc123
 `;
 
+const SUB_HELP = {
+  browse: `run402 apps browse — Browse public apps in the marketplace
+
+Usage:
+  run402 apps browse [--tag <tag>]
+
+Options:
+  --tag <tag>         Filter by tag; repeat the flag to filter on multiple tags
+
+Examples:
+  run402 apps browse
+  run402 apps browse --tag auth
+  run402 apps browse --tag todo --tag auth
+`,
+  fork: `run402 apps fork — Fork a published app into your own project
+
+Usage:
+  run402 apps fork <version_id> <name> [options]
+
+Arguments:
+  <version_id>        Published version ID (e.g. ver_abc123)
+  <name>              Name for the forked project
+
+Options:
+  --tier <tier>       Tier for the new project (default: prototype)
+  --subdomain <name>  Claim a subdomain for the forked project
+
+Examples:
+  run402 apps fork ver_abc123 my-todo
+  run402 apps fork ver_abc123 my-todo --tier hobby --subdomain todo-v2
+`,
+  publish: `run402 apps publish — Publish a project as an app
+
+Usage:
+  run402 apps publish <id> [options]
+
+Arguments:
+  <id>                Project ID to publish
+
+Options:
+  --description <d>   Human-readable description of the app
+  --tags <t1,t2>      Comma-separated list of tags
+  --visibility <v>    Visibility: 'public' or 'private'
+  --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
+`,
+  update: `run402 apps update — Update a published version's metadata
+
+Usage:
+  run402 apps update <project_id> <version_id> [options]
+
+Arguments:
+  <project_id>        Project ID that owns the version
+  <version_id>        Published version ID to update
+
+Options:
+  --description <d>   New description
+  --tags <t1,t2>      New comma-separated list of tags
+  --visibility <v>    New visibility ('public' or 'private')
+  --fork-allowed      Enable forking for this version
+  --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
+`,
+};
+
 async function browse(args) {
   let url = `${API}/apps/v1`;
   const tags = [];
@@ -152,6 +224,7 @@ async function deleteVersion(projectId, versionId) {
 
 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 "browse":   await browse(args); break;
     case "fork":     await fork(args[0], args[1], args.slice(2)); break;

package/lib/auth.mjs

@@ -29,6 +29,84 @@ Examples:
   run402 auth providers
 `;
 
+const SUB_HELP = {
+  "magic-link": `run402 auth magic-link — Send a passwordless login link
+
+Usage:
+  run402 auth magic-link --email <addr> --redirect <url> [options]
+
+Options:
+  --email <addr>      Required: recipient email address
+  --redirect <url>    Required: URL to redirect to after the user clicks
+  --project <id>      Project ID (defaults to active project)
+
+Notes:
+  Auto-creates the user on first use. Uses the project's anon_key.
+
+Examples:
+  run402 auth magic-link --email user@example.com \\
+    --redirect https://myapp.run402.com/cb
+`,
+  verify: `run402 auth verify — Exchange a magic-link token for session tokens
+
+Usage:
+  run402 auth verify --token <token> [options]
+
+Options:
+  --token <token>     Required: the one-time magic-link token
+  --project <id>      Project ID (defaults to active project)
+
+Notes:
+  Returns an access_token + refresh_token pair on success.
+
+Examples:
+  run402 auth verify --token abc123def456
+`,
+  "set-password": `run402 auth set-password — Change, reset, or set a user's password
+
+Usage:
+  run402 auth set-password --token <bearer> --new <password> [options]
+
+Options:
+  --token <bearer>    Required: the user's access_token (Bearer token)
+  --new <password>    Required: new password
+  --current <pwd>     Current password (required when one is already set)
+  --project <id>      Project ID (defaults to active project)
+
+Examples:
+  run402 auth set-password --token eyJ... --new "new-pass" \\
+    --current "old-pass"
+`,
+  settings: `run402 auth settings — Update project auth settings
+
+Usage:
+  run402 auth settings --allow-password-set <true|false> [options]
+
+Options:
+  --allow-password-set <true|false>  Required: toggle password-set flow
+  --project <id>                     Project ID (defaults to active project)
+
+Notes:
+  Requires the project's service_key (admin-level).
+
+Examples:
+  run402 auth settings --allow-password-set true
+  run402 auth settings --allow-password-set false --project abc123
+`,
+  providers: `run402 auth providers — List available auth providers
+
+Usage:
+  run402 auth providers [options]
+
+Options:
+  --project <id>      Project ID (defaults to active project)
+
+Examples:
+  run402 auth providers
+  run402 auth providers --project abc123
+`,
+};
+
 function parseFlag(args, flag) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === flag && args[i + 1]) return args[i + 1];
@@ -90,6 +168,8 @@ async function setPassword(args) {
   const accessToken = parseFlag(args, "--token");
   const newPassword = parseFlag(args, "--new");
   const currentPassword = parseFlag(args, "--current");
+  const projectId = resolveProjectId(parseFlag(args, "--project"));
+  const p = findProject(projectId);
 
   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); }
@@ -97,9 +177,16 @@ async function setPassword(args) {
   const body = { new_password: newPassword };
   if (currentPassword) body.current_password = currentPassword;
 
+  // /auth/v1/* is gated by apikeyAuth middleware: the `apikey` header must be
+  // the project's anon_key. `Authorization: Bearer <access_token>` stays as
+  // the user's identity so the server knows whose password to change.
   const res = await fetch(`${API}/auth/v1/user/password`, {
     method: "PUT",
-    headers: { "Authorization": `Bearer ${accessToken}`, "Content-Type": "application/json" },
+    headers: {
+      "apikey": p.anon_key,
+      "Authorization": `Bearer ${accessToken}`,
+      "Content-Type": "application/json",
+    },
     body: JSON.stringify(body),
   });
   const data = await res.json();
@@ -155,7 +242,7 @@ async function providers(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) {

package/lib/billing.mjs

@@ -22,6 +22,69 @@ Examples:
   run402 billing balance user@example.com
 `;
 
+const SUB_HELP = {
+  "tier-checkout": `run402 billing tier-checkout — Create a Stripe tier checkout session
+
+Usage:
+  run402 billing tier-checkout <tier> [--email <e> | --wallet <w>]
+
+Arguments:
+  <tier>              Tier name (e.g. hobby, pro)
+
+Options:
+  --email <e>         Email billing account to charge
+  --wallet <w>        Wallet address (0x...) to associate with the checkout
+
+Examples:
+  run402 billing tier-checkout hobby --email user@example.com
+  run402 billing tier-checkout pro --wallet 0x1234...
+`,
+  "buy-email-pack": `run402 billing buy-email-pack — Buy a $5 email pack (10,000 emails)
+
+Usage:
+  run402 billing buy-email-pack [--email <e> | --wallet <w>]
+
+Options:
+  --email <e>         Email billing account to charge
+  --wallet <w>        Wallet address (0x...) to associate with the purchase
+
+Examples:
+  run402 billing buy-email-pack --email user@example.com
+  run402 billing buy-email-pack --wallet 0x1234...
+`,
+  "auto-recharge": `run402 billing auto-recharge — Toggle email-pack auto-recharge
+
+Usage:
+  run402 billing auto-recharge <account_id> <on|off> [--threshold <n>]
+
+Arguments:
+  <account_id>        Billing account ID
+  <on|off>            Enable or disable auto-recharge
+
+Options:
+  --threshold <n>     Remaining-email threshold that triggers auto-recharge
+
+Examples:
+  run402 billing auto-recharge acct_abc on --threshold 2000
+  run402 billing auto-recharge acct_abc off
+`,
+  history: `run402 billing history — Show ledger history for an email or wallet
+
+Usage:
+  run402 billing history <identifier> [--limit <n>]
+
+Arguments:
+  <identifier>        Email address or wallet (0x...)
+
+Options:
+  --limit <n>         Max entries to return (default: 50)
+
+Examples:
+  run402 billing history user@example.com
+  run402 billing history 0x1234... --limit 100
+`,
+};
+
 function parseFlag(args, flag) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === flag && args[i + 1]) return args[i + 1];
@@ -153,6 +216,7 @@ async function history(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 "create-email": await createEmail(args); break;
     case "link-wallet": await linkWallet(args); break;

package/lib/blob.mjs

@@ -68,6 +68,89 @@ Examples:
   run402 blob sign images/logo.png --project abc123 --ttl 600
 `;
 
+const SUB_HELP = {
+  put: `run402 blob put — Upload one or more files to blob storage
+
+Usage:
+  run402 blob put <file> [files...] [options]
+
+Arguments:
+  <file>              Path to a file (or glob); pass multiple files to batch-upload
+
+Options:
+  --project <id>      Project ID (defaults to active project from 'run402 projects use')
+  --key <dest>        Destination key; defaults to file basename. Use trailing '/' as prefix.
+  --private           Upload as private (not served by CDN; apikey required to read)
+  --immutable         Append content-hash suffix so overwrites produce distinct URLs
+  --concurrency N     Concurrent part PUTs for multipart uploads (default 4)
+  --no-resume         Ignore any cached resumable-upload state and start fresh
+  --json              Emit NDJSON progress events on stdout (for agent consumption)
+
+Examples:
+  run402 blob put ./artifact.tgz --project abc123
+  run402 blob put ./dist/**/*.png --project abc123 --key assets/
+  run402 blob put huge.bin --project abc123 --immutable --concurrency 8
+`,
+  get: `run402 blob get — Download a blob by key
+
+Usage:
+  run402 blob get <key> --output <file> [options]
+
+Arguments:
+  <key>               Blob key to download
+
+Options:
+  --output <file>     Local destination path (required)
+  --project <id>      Project ID (defaults to active project)
+
+Examples:
+  run402 blob get images/logo.png --output /tmp/logo.png --project abc123
+`,
+  ls: `run402 blob ls — List blob keys in a project
+
+Usage:
+  run402 blob ls [options]
+
+Options:
+  --project <id>      Project ID (defaults to active project)
+  --prefix <p>        Only list keys starting with this prefix
+  --limit <n>         Max results (default 100, max 1000)
+
+Examples:
+  run402 blob ls --project abc123
+  run402 blob ls --project abc123 --prefix images/ --limit 500
+`,
+  rm: `run402 blob rm — Delete a blob
+
+Usage:
+  run402 blob rm <key> [options]
+
+Arguments:
+  <key>               Blob key to delete
+
+Options:
+  --project <id>      Project ID (defaults to active project)
+
+Examples:
+  run402 blob rm images/logo.png --project abc123
+`,
+  sign: `run402 blob sign — Create a presigned download URL for a blob
+
+Usage:
+  run402 blob sign <key> [options]
+
+Arguments:
+  <key>               Blob key to sign
+
+Options:
+  --project <id>      Project ID (defaults to active project)
+  --ttl <seconds>     Signed-URL TTL (default 3600, max 604800)
+
+Examples:
+  run402 blob sign reports/2025-q4.pdf --project abc123 --ttl 600
+`,
+};
+
 const UPLOAD_STATE_DIR = join(homedir(), ".run402", "uploads");
 
 function die(msg, code = 1) {
@@ -428,7 +511,7 @@ export async function run(sub, args) {
     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);
   }
   const defaultProject = process.env.RUN402_PROJECT ?? null;

package/lib/contracts.mjs

@@ -36,6 +36,144 @@ Examples:
   run402 contracts call proj_abc cwlt_xyz --to 0x1234... --abi '[{"type":"function","name":"ping","inputs":[],"outputs":[]}]' --fn ping --args '[]'
 `;
 
+const SUB_HELP = {
+  "provision-wallet": `run402 contracts provision-wallet — Provision a KMS-backed wallet
+
+Usage:
+  run402 contracts provision-wallet <project_id> --chain <chain> [options]
+
+Arguments:
+  <project_id>        Target project ID
+
+Options:
+  --chain <chain>     Required: base-mainnet or base-sepolia
+  --recovery 0x...    Optional recovery address (can be set later)
+  --yes               Skip confirmation when project already has a wallet
+
+Pricing:
+  $0.04/day per wallet ($1.20/month). Creation requires $1.20 prepay
+  (30 days of rent). Non-custodial — see terms.html#non-custodial-kms-wallets.
+
+Examples:
+  run402 contracts provision-wallet proj_abc --chain base-mainnet
+  run402 contracts provision-wallet proj_abc --chain base-sepolia --recovery 0xAbC...
+`,
+  "set-recovery": `run402 contracts set-recovery — Set or clear the wallet recovery address
+
+Usage:
+  run402 contracts set-recovery <project_id> <wallet_id> [options]
+
+Arguments:
+  <project_id>        Target project ID
+  <wallet_id>         KMS wallet ID (cwlt_...)
+
+Options:
+  --address 0x...     New recovery address
+  --clear             Clear the recovery address (mutually exclusive with --address)
+
+Examples:
+  run402 contracts set-recovery proj_abc cwlt_xyz --address 0xAbC...
+  run402 contracts set-recovery proj_abc cwlt_xyz --clear
+`,
+  "set-alert": `run402 contracts set-alert — Set the low-balance alert threshold
+
+Usage:
+  run402 contracts set-alert <project_id> <wallet_id> --threshold-wei <n>
+
+Arguments:
+  <project_id>        Target project ID
+  <wallet_id>         KMS wallet ID (cwlt_...)
+
+Options:
+  --threshold-wei <n> Required: alert threshold in wei
+
+Examples:
+  run402 contracts set-alert proj_abc cwlt_xyz --threshold-wei 1000000000000000
+`,
+  call: `run402 contracts call — Submit a contract write call
+
+Usage:
+  run402 contracts call <project_id> <wallet_id> --to 0x... --abi <json>
+    --fn <name> --args <json> [options]
+
+Arguments:
+  <project_id>        Target project ID
+  <wallet_id>         KMS wallet ID (cwlt_...)
+
+Options:
+  --to 0x...          Required: contract address
+  --abi <json>        Required: ABI fragment (JSON string)
+  --fn <name>         Required: function name to invoke
+  --args <json>       Required: function args (JSON array)
+  --value-wei <n>     Native value to send (default 0)
+  --chain <chain>     Chain override (default: base-mainnet)
+  --idempotency-key <k>  Idempotency key for safe retries
+
+Pricing:
+  Chain gas + $0.000005 KMS sign fee per call.
+
+Examples:
+  run402 contracts call proj_abc cwlt_xyz --to 0x1234... \\
+    --abi '[{"type":"function","name":"ping","inputs":[],"outputs":[]}]' \\
+    --fn ping --args '[]'
+`,
+  read: `run402 contracts read — Read-only contract call (free)
+
+Usage:
+  run402 contracts read --chain <chain> --to 0x... --abi <json>
+    --fn <name> --args <json>
+
+Options:
+  --chain <chain>     Required: base-mainnet or base-sepolia
+  --to 0x...          Required: contract address
+  --abi <json>        Required: ABI fragment (JSON string)
+  --fn <name>         Required: function name to invoke
+  --args <json>       Required: function args (JSON array)
+
+Examples:
+  run402 contracts read --chain base-mainnet --to 0x1234... \\
+    --abi '[{"type":"function","name":"balanceOf","inputs":[{"type":"address"}],"outputs":[{"type":"uint256"}]}]' \\
+    --fn balanceOf --args '["0xAbC..."]'
+`,
+  drain: `run402 contracts drain — Drain native balance to a destination address
+
+Usage:
+  run402 contracts drain <project_id> <wallet_id> --to 0x... --confirm
+
+Arguments:
+  <project_id>        Target project ID
+  <wallet_id>         KMS wallet ID (cwlt_...)
+
+Options:
+  --to 0x...          Required: destination address
+  --confirm           Required: explicit confirmation flag
+
+Notes:
+  Works on suspended wallets. Cost: chain gas + $0.000005 KMS sign fee.
+
+Examples:
+  run402 contracts drain proj_abc cwlt_xyz --to 0xAbC... --confirm
+`,
+  delete: `run402 contracts delete — Schedule the KMS key for deletion
+
+Usage:
+  run402 contracts delete <project_id> <wallet_id> --confirm
+
+Arguments:
+  <project_id>        Target project ID
+  <wallet_id>         KMS wallet ID (cwlt_...)
+
+Options:
+  --confirm           Required: explicit confirmation flag
+
+Notes:
+  Refused if wallet balance is greater than or equal to dust. Drain first.
+
+Examples:
+  run402 contracts delete proj_abc cwlt_xyz --confirm
+`,
+};
+
 function parseFlag(args, flag) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === flag && args[i + 1]) return args[i + 1];
@@ -243,6 +381,7 @@ async function deleteWallet(projectId, walletId, 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 "provision-wallet": await provisionWallet(args[0], args.slice(1)); break;
     case "get-wallet":       await getWallet(args[0], args[1]); break;

package/lib/domains.mjs

@@ -92,6 +92,7 @@ async function deleteDomain(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 "add":    await add(args); break;
     case "list":   await list(args[0]); break;

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
@@ -41,8 +41,10 @@ Examples:
   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 (prefer user_owns_rows for user-scoped data):
@@ -52,6 +54,48 @@ Notes:
                                         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();
@@ -73,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, {
@@ -231,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) {
@@ -245,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));
 }

package/lib/webhooks.mjs

@@ -21,6 +21,47 @@ Examples:
   run402 email webhooks delete whk_123
 `;
 
+const SUB_HELP = {
+  update: `run402 email webhooks update — Update an existing webhook
+
+Usage:
+  run402 email webhooks update <webhook_id> [--url <url>] [--events <e1,e2>] [--project <id>]
+
+Arguments:
+  <webhook_id>        Webhook ID to update
+
+Options:
+  --url <url>         New delivery URL for the webhook
+  --events <e1,e2>    Comma-separated event list to replace the current events
+                      Valid: delivery, bounced, complained, reply_received
+  --project <id>      Project ID (defaults to the active project)
+
+Notes:
+  - Provide at least one of --url or --events
+
+Examples:
+  run402 email webhooks update whk_123 --url https://new.example.com/hook
+  run402 email webhooks update whk_123 --events delivery,bounced
+`,
+  register: `run402 email webhooks register — Register a new webhook
+
+Usage:
+  run402 email webhooks register --url <url> --events <e1,e2> [--project <id>]
+
+Options:
+  --url <url>         Delivery URL for the webhook (required)
+  --events <e1,e2>    Comma-separated event list (required)
+                      Valid: delivery, bounced, complained, reply_received
+  --project <id>      Project ID (defaults to the active project)
+
+Examples:
+  run402 email webhooks register --url https://example.com/hook \\
+    --events delivery,bounced
+  run402 email webhooks register --url https://example.com/hook \\
+    --events reply_received --project proj123
+`,
+};
+
 function parseFlag(args, flag) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === flag && args[i + 1]) return args[i + 1];
@@ -207,6 +248,7 @@ async function register(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 "list":     await list(args); break;
     case "get":      await get(args); break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "1.36.0",
+  "version": "1.36.1",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {