run402 1.36.0 → 1.37.0

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;