run402 4.8.0 → 4.10.0

package/lib/image.mjs

@@ -1,7 +1,7 @@
 import { writeFileSync } from "fs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertAllowedValue, assertKnownFlags, flagValue, normalizeArgv, positionalArgs } from "./argparse.mjs";
+import { assertAllowedValue, assertKnownFlags, flagValue, normalizeArgv, positionalArgs, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 image — Generate AI images via x402 micropayments
 
@@ -67,7 +67,7 @@ export async function run(sub, args) {
   }
 
   if (sub !== "generate") {
-    fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown image subcommand: ${sub}`, hint: "Run `run402 image --help` for usage.", details: { command: "image", subcommand: sub } });
+    failUnknownSubcommand("image", sub);
   }
 
   const parsedArgs = normalizeArgv(args);

package/lib/jobs.mjs

@@ -14,6 +14,7 @@ import {
   positionalArgs,
   requirePositionalCount,
   validateRegularFile,
+  failUnknownSubcommand,
 } from "./argparse.mjs";
 
 const HELP = `run402 jobs — Submit and inspect platform-managed jobs
@@ -27,7 +28,7 @@ Subcommands:
   logs            <job_id>                Read job logs
   cancel          <job_id>                Cancel a queued or running job
   purge                                   Purge all job runs for the project
-  artifacts get   <job_id> <file>         Download a completed job's artifact
+  artifacts get   <job_id> --file <name>  Download a completed job's artifact (legacy: <job_id> <file>)
 
 Examples:
   run402 jobs submit --file job.json
@@ -120,6 +121,9 @@ recorded filenames on a given run.
   "artifacts get": `run402 jobs artifacts get — Download a completed job's artifact
 
 Usage:
+  run402 jobs artifacts get <job_id> --file <name> --output <path> [--project <id>]
+
+Legacy (still supported):
   run402 jobs artifacts get <job_id> <file> --output <path> [--project <id>]
 
 Options:
@@ -355,24 +359,27 @@ async function artifactsGet(args = []) {
     process.exit(0);
   }
   const parsed = normalizeArgv(args);
-  const valueFlags = ["--project", "--output", "-o"];
-  assertKnownFlags(parsed, ["--project", "--output", "-o", "--help", "-h"], valueFlags);
+  const valueFlags = ["--project", "--output", "-o", "--file"];
+  assertKnownFlags(parsed, ["--project", "--output", "-o", "--file", "--help", "-h"], valueFlags);
+  const fileFlag = flagValue(parsed, "--file");
+  const expected = fileFlag ? 1 : 2;
   const positionals = positionalArgs(parsed, valueFlags);
-  if (positionals.length < 2) {
+  if (positionals.length < expected) {
     fail({
       code: "BAD_USAGE",
       message: "Missing job_id and/or artifact filename.",
-      hint: "Use `run402 jobs artifacts get <job_id> <file> --output <path>`.",
+      hint: "Use `run402 jobs artifacts get <job_id> --file <name> --output <path>`.",
     });
   }
-  if (positionals.length > 2) {
+  if (positionals.length > expected) {
     fail({
       code: "BAD_USAGE",
-      message: `Unexpected argument: ${positionals[2]}`,
-      hint: "Use `run402 jobs artifacts get <job_id> <file> --output <path>`.",
+      message: `Unexpected argument: ${positionals[expected]}`,
+      hint: "Use `run402 jobs artifacts get <job_id> --file <name> --output <path>`.",
     });
   }
-  const [jobId, filename] = positionals;
+  const jobId = positionals[0];
+  const filename = fileFlag ?? positionals[1];
   const output = flagValue(parsed, "--output") ?? flagValue(parsed, "-o");
   if (!output) {
     fail({
@@ -421,7 +428,7 @@ async function artifacts(args = []) {
     await artifactsGet(args.slice(1));
     return;
   }
-  fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown jobs artifacts action: ${action}`, hint: "Run `run402 jobs artifacts --help` for usage.", details: { command: "jobs artifacts", subcommand: action } });
+  failUnknownSubcommand("jobs artifacts", action);
 }
 
 function splitJobIdArg(args = [], valueFlags = []) {
@@ -484,6 +491,6 @@ export async function run(sub, args = []) {
       await purge(args);
       break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown jobs subcommand: ${sub}`, hint: "Run `run402 jobs --help` for usage.", details: { command: "jobs", subcommand: sub } });
+      failUnknownSubcommand("jobs", sub);
   }
 }

package/lib/message.mjs

@@ -1,7 +1,7 @@
 import { allowanceAuthHeaders } from "./config.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, normalizeArgv } from "./argparse.mjs";
+import { assertKnownFlags, normalizeArgv, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 message — Send messages to Run402 developers
 
@@ -84,7 +84,7 @@ export async function run(sub, args) {
     process.exit(0);
   }
   if (sub !== "send") {
-    fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown message subcommand: ${sub}`, hint: "Run `run402 message --help` for usage.", details: { command: "message", subcommand: sub } });
+    failUnknownSubcommand("message", sub);
   }
   const parsedArgs = normalizeArgv(args);
   assertKnownFlags(parsedArgs, ["--help", "-h"]);

package/lib/notifications.mjs

@@ -40,6 +40,7 @@ import {
   normalizeArgv,
   positionalArgs,
   requirePositionalCount,
+  failUnknownSubcommand,
 } from "./argparse.mjs";
 
 const HELP = `run402 notifications — Operator health notifications + Telegram channel/rules
@@ -435,9 +436,8 @@ async function runChannels(args) {
     await channelsRevoke(rest);
     return;
   }
-  fail({
-    code: "BAD_USAGE",
-    message: `Unknown 'notifications channels' action: ${channelsAction}. Try connect | list | revoke.`,
+  failUnknownSubcommand("notifications channels", channelsAction, {
+    hint: "Run `run402 notifications channels --help` for usage.",
   });
 }
 
@@ -539,9 +539,8 @@ async function runRules(args) {
     await rulesRm(rest);
     return;
   }
-  fail({
-    code: "BAD_USAGE",
-    message: `Unknown 'notifications rules' action: ${rulesAction}. Try add | list | rm.`,
+  failUnknownSubcommand("notifications rules", rulesAction, {
+    hint: "Run `run402 notifications rules --help` for usage.",
   });
 }
 
@@ -586,12 +585,7 @@ export async function run(sub, args) {
       await test(args);
       return;
     default:
-      fail({
-        code: "UNKNOWN_SUBCOMMAND",
-        message: `Unknown notifications subcommand: ${sub}`,
-        hint: "Run `run402 notifications --help` for usage.",
-        details: { command: "notifications", subcommand: sub },
-      });
+      failUnknownSubcommand("notifications", sub);
   }
 }
 

package/lib/operator.mjs

@@ -24,7 +24,7 @@ import { randomBytes, createHash } from "node:crypto";
 import { fail, reportSdkError } from "./sdk-errors.mjs";
 import { getSdk } from "./sdk.mjs";
 import { claimWalletOrg, isStepUpRequired, isOperatorApprovalRequired } from "#sdk/node";
-import { normalizeArgv, hasHelp, assertKnownFlags, flagValue } from "./argparse.mjs";
+import { normalizeArgv, hasHelp, assertKnownFlags, flagValue, failUnknownSubcommand } from "./argparse.mjs";
 import {
   saveOperatorSession,
   clearOperatorSession,
@@ -766,11 +766,6 @@ export async function run(sub, args = []) {
       await status(args);
       break;
     default:
-      fail({
-        code: "UNKNOWN_SUBCOMMAND",
-        message: `Unknown operator subcommand: ${sub}`,
-        hint: "Run `run402 operator --help` for usage.",
-        details: { command: "operator", subcommand: sub },
-      });
+      failUnknownSubcommand("operator", sub, { extraSubcommands: ["status"] });
   }
 }

package/lib/org.mjs

@@ -6,6 +6,7 @@ import {
   flagValue,
   parseIntegerFlag,
   requirePositionalCount,
+  failUnknownSubcommand,
 } from "./argparse.mjs";
 
 const ROLE_LIST = "owner | admin | developer | billing | viewer";
@@ -16,17 +17,20 @@ Usage:
   run402 org create [--name <label>]
   run402 org list
   run402 org get    <org_id>
-  run402 org rename <org_id> <display_name>   (or: --clear to remove the label)
-  run402 org payout-wallet <org_id> <wallet_address>  (or: --clear to remove the explicit default)
+  run402 org rename <org_id> --name <display_name>   (or: --clear to remove the label)
+  run402 org payout-wallet <org_id> --wallet <wallet_address>  (or: --clear to remove the explicit default)
   run402 org whoami
   run402 org audit  <org_id> [--limit N] [--after <cursor>] [--before <cursor>]
   run402 org member list <org_id>
-  run402 org member add  <org_id> <wallet_address> [--role <role>]
-  run402 org member role <org_id> <principal_id> <role>
-  run402 org member rm   <org_id> <principal_id>
+  run402 org member add  <org_id> --wallet <wallet_address> [--role <role>]
+  run402 org member role <org_id> --principal <principal_id> --role <role>
+  run402 org member rm   <org_id> --principal <principal_id>
   run402 org invite list   <org_id>
-  run402 org invite create <org_id> <email> [--role <role>] [--ttl-hours N]
-  run402 org invite rm     <org_id> <principal_id>
+  run402 org invite create <org_id> --email <email> [--role <role>] [--ttl-hours N]
+  run402 org invite rm     <org_id> --principal <principal_id>
+
+Legacy (still supported): the second attribute may also be passed positionally,
+e.g. run402 org member add <org_id> <wallet_address>.
 
 Subcommands:
   create      Create an empty org on the prototype tier (you become owner)
@@ -87,18 +91,24 @@ non-revealing 403.
   rename: `run402 org rename — set or clear an org's display label (owner-only)
 
 Usage:
-  run402 org rename <org_id> <display_name>
+  run402 org rename <org_id> --name <display_name>
   run402 org rename <org_id> --clear
 
+Legacy (still supported):
+  run402 org rename <org_id> <display_name>
+
 Owner-only + step-up gated. Pass --clear (or an empty display_name) to remove
 the label. Output includes the updated tier and lease timestamps.
 `,
   "payout-wallet": `run402 org payout-wallet — set or clear the tenant route payout wallet
 
 Usage:
-  run402 org payout-wallet <org_id> <wallet_address>
+  run402 org payout-wallet <org_id> --wallet <wallet_address>
   run402 org payout-wallet <org_id> --clear
 
+Legacy (still supported):
+  run402 org payout-wallet <org_id> <wallet_address>
+
 Admin/owner-only + step-up gated. The wallet must already be active and linked
 to the same org. This wallet receives x402 settlement for function web routes
 that declare pricing.pay_to = "org_default_payout". Pass --clear to remove the
@@ -120,9 +130,9 @@ for local wallet/profile state use 'run402 status'.
 
 Usage:
   run402 org member list <org_id>
-  run402 org member add  <org_id> <wallet_address> [--role <role>]
-  run402 org member role <org_id> <principal_id> <role>
-  run402 org member rm   <org_id> <principal_id>
+  run402 org member add  <org_id> --wallet <wallet_address> [--role <role>]
+  run402 org member role <org_id> --principal <principal_id> --role <role>
+  run402 org member rm   <org_id> --principal <principal_id>
 
 Roles: ${ROLE_LIST} (add defaults to developer). Mutations require an active owner.
 Demoting/removing the org's only active owner fails with 409 LAST_OWNER.
@@ -131,8 +141,11 @@ Demoting/removing the org's only active owner fails with 409 LAST_OWNER.
 
 Usage:
   run402 org invite list   <org_id>
-  run402 org invite create <org_id> <email> [--role <role>] [--ttl-hours N]
-  run402 org invite rm     <org_id> <principal_id>
+  run402 org invite create <org_id> --email <email> [--role <role>] [--ttl-hours N]
+  run402 org invite rm     <org_id> --principal <principal_id>
+
+Legacy (still supported): the second attribute may also be passed positionally,
+e.g. run402 org member add <org_id> <wallet_address>.
 
 An invite is claimed at the recipient's first login. Mutations require an active owner
 (plus step-up when driven by a control-plane session).
@@ -200,16 +213,18 @@ async function get(args) {
 
 async function rename(args) {
   const a = normalizeArgv(args);
-  assertKnownFlags(a, ["--clear", "--help", "-h"]);
+  assertKnownFlags(a, ["--name", "--clear", "--help", "-h"], ["--name"]);
   const clear = a.includes("--clear");
-  const positionals = requirePositionalCount(a, [], {
-    min: clear ? 1 : 2,
-    max: clear ? 1 : 2,
-    command: "run402 org rename <org_id> <display_name>",
-    missing: clear ? "Missing <org_id>." : "Missing <org_id> and/or <display_name> (or pass --clear).",
+  const nameFlag = flagValue(a, "--name");
+  const single = clear || nameFlag !== null;
+  const positionals = requirePositionalCount(a, ["--name"], {
+    min: single ? 1 : 2,
+    max: single ? 1 : 2,
+    command: "run402 org rename <org_id> --name <display_name>",
+    missing: single ? "Missing <org_id>." : "Missing <org_id> and/or <display_name> (use --name, or pass --clear).",
   });
   const org = positionals[0];
-  const displayName = clear ? null : positionals[1];
+  const displayName = clear ? null : (nameFlag ?? positionals[1]);
   try {
     console.log(JSON.stringify(await getSdk().org(org).rename(displayName), null, 2));
   } catch (err) {
@@ -219,16 +234,18 @@ async function rename(args) {
 
 async function payoutWallet(args) {
   const a = normalizeArgv(args);
-  assertKnownFlags(a, ["--clear", "--help", "-h"]);
+  assertKnownFlags(a, ["--wallet", "--clear", "--help", "-h"], ["--wallet"]);
   const clear = a.includes("--clear");
-  const positionals = requirePositionalCount(a, [], {
-    min: clear ? 1 : 2,
-    max: clear ? 1 : 2,
-    command: "run402 org payout-wallet <org_id> <wallet_address>",
-    missing: clear ? "Missing <org_id>." : "Missing <org_id> and/or <wallet_address> (or pass --clear).",
+  const walletFlag = flagValue(a, "--wallet");
+  const single = clear || walletFlag !== null;
+  const positionals = requirePositionalCount(a, ["--wallet"], {
+    min: single ? 1 : 2,
+    max: single ? 1 : 2,
+    command: "run402 org payout-wallet <org_id> --wallet <wallet_address>",
+    missing: single ? "Missing <org_id>." : "Missing <org_id> and/or <wallet_address> (use --wallet, or pass --clear).",
   });
   const org = positionals[0];
-  const walletAddress = clear ? null : positionals[1];
+  const walletAddress = clear ? null : (walletFlag ?? positionals[1]);
   try {
     console.log(JSON.stringify(await getSdk().org(org).setPayoutWallet({ walletAddress }), null, 2));
   } catch (err) {
@@ -292,12 +309,16 @@ async function runMember(args) {
 
   if (memberAction === "add") {
     const a = normalizeArgv(rest);
-    assertKnownFlags(a, ["--role", "--help", "-h"], ["--role"]);
+    assertKnownFlags(a, ["--role", "--wallet", "--help", "-h"], ["--role", "--wallet"]);
     const role = flagValue(a, "--role");
-    const [org, wallet] = requirePositionalCount(a, ["--role"], {
-      min: 2, max: 2, command: "run402 org member add <org_id> <wallet_address> [--role <role>]",
-      missing: "Missing <org_id> and/or <wallet_address>.",
+    const walletFlag = flagValue(a, "--wallet");
+    const count = walletFlag ? 1 : 2;
+    const pos = requirePositionalCount(a, ["--role", "--wallet"], {
+      min: count, max: count, command: "run402 org member add <org_id> --wallet <wallet_address> [--role <role>]",
+      missing: walletFlag ? "Missing <org_id>." : "Missing <org_id> and/or <wallet_address> (use --wallet).",
     });
+    const org = pos[0];
+    const wallet = walletFlag ?? pos[1];
     try {
       const res = await getSdk().org(org).members.add({ wallet, role: role || undefined });
       console.log(JSON.stringify(res, null, 2));
@@ -309,11 +330,17 @@ async function runMember(args) {
 
   if (memberAction === "role") {
     const a = normalizeArgv(rest);
-    assertKnownFlags(a, ["--help", "-h"]);
-    const [org, principalId, role] = requirePositionalCount(a, [], {
-      min: 3, max: 3, command: "run402 org member role <org_id> <principal_id> <role>",
-      missing: "Missing <org_id>, <principal_id>, and/or <role>.",
+    assertKnownFlags(a, ["--principal", "--role", "--help", "-h"], ["--principal", "--role"]);
+    const principalFlag = flagValue(a, "--principal");
+    const roleFlag = flagValue(a, "--role");
+    const count = 3 - (principalFlag ? 1 : 0) - (roleFlag ? 1 : 0);
+    const pos = requirePositionalCount(a, ["--principal", "--role"], {
+      min: count, max: count, command: "run402 org member role <org_id> --principal <principal_id> --role <role>",
+      missing: "Missing <org_id>, <principal_id> (--principal), and/or <role> (--role).",
     });
+    const org = pos[0];
+    const principalId = principalFlag ?? pos[1];
+    const role = roleFlag ?? (principalFlag ? pos[1] : pos[2]);
     try {
       console.log(JSON.stringify(await getSdk().org(org).members.setRole(principalId, { role }), null, 2));
     } catch (err) {
@@ -324,11 +351,15 @@ async function runMember(args) {
 
   if (memberAction === "rm") {
     const a = normalizeArgv(rest);
-    assertKnownFlags(a, ["--help", "-h"]);
-    const [org, principalId] = requirePositionalCount(a, [], {
-      min: 2, max: 2, command: "run402 org member rm <org_id> <principal_id>",
-      missing: "Missing <org_id> and/or <principal_id>.",
+    assertKnownFlags(a, ["--principal", "--help", "-h"], ["--principal"]);
+    const principalFlag = flagValue(a, "--principal");
+    const count = principalFlag ? 1 : 2;
+    const pos = requirePositionalCount(a, ["--principal"], {
+      min: count, max: count, command: "run402 org member rm <org_id> --principal <principal_id>",
+      missing: principalFlag ? "Missing <org_id>." : "Missing <org_id> and/or <principal_id> (use --principal).",
     });
+    const org = pos[0];
+    const principalId = principalFlag ?? pos[1];
     try {
       console.log(JSON.stringify(await getSdk().org(org).members.revoke(principalId), null, 2));
     } catch (err) {
@@ -370,14 +401,18 @@ async function runInvite(args) {
 
   if (inviteAction === "create") {
     const a = normalizeArgv(rest);
-    const valueFlags = ["--role", "--ttl-hours"];
+    const valueFlags = ["--role", "--ttl-hours", "--email"];
     assertKnownFlags(a, [...valueFlags, "--help", "-h"], valueFlags);
     const role = flagValue(a, "--role");
     const ttlFlag = flagValue(a, "--ttl-hours");
-    const [org, email] = requirePositionalCount(a, valueFlags, {
-      min: 2, max: 2, command: "run402 org invite create <org_id> <email> [--role <role>]",
-      missing: "Missing <org_id> and/or <email>.",
+    const emailFlag = flagValue(a, "--email");
+    const count = emailFlag ? 1 : 2;
+    const pos = requirePositionalCount(a, valueFlags, {
+      min: count, max: count, command: "run402 org invite create <org_id> --email <email> [--role <role>]",
+      missing: emailFlag ? "Missing <org_id>." : "Missing <org_id> and/or <email> (use --email).",
     });
+    const org = pos[0];
+    const email = emailFlag ?? pos[1];
     const inviteTtlHours = ttlFlag === null ? undefined : parseIntegerFlag("--ttl-hours", ttlFlag, { min: 1, max: 8760 });
     try {
       const res = await getSdk().org(org).invites.create({ email, role: role || "developer", inviteTtlHours });
@@ -390,11 +425,15 @@ async function runInvite(args) {
 
   if (inviteAction === "rm") {
     const a = normalizeArgv(rest);
-    assertKnownFlags(a, ["--help", "-h"]);
-    const [org, principalId] = requirePositionalCount(a, [], {
-      min: 2, max: 2, command: "run402 org invite rm <org_id> <principal_id>",
-      missing: "Missing <org_id> and/or <principal_id>.",
+    assertKnownFlags(a, ["--principal", "--help", "-h"], ["--principal"]);
+    const principalFlag = flagValue(a, "--principal");
+    const count = principalFlag ? 1 : 2;
+    const pos = requirePositionalCount(a, ["--principal"], {
+      min: count, max: count, command: "run402 org invite rm <org_id> --principal <principal_id>",
+      missing: principalFlag ? "Missing <org_id>." : "Missing <org_id> and/or <principal_id> (use --principal).",
     });
+    const org = pos[0];
+    const principalId = principalFlag ?? pos[1];
     try {
       console.log(JSON.stringify(await getSdk().org(org).invites.revoke(principalId), null, 2));
     } catch (err) {
@@ -434,6 +473,6 @@ export async function run(sub, args) {
     case "whoami": await whoami(args); break;
     case "audit": await audit(args); break;
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown org subcommand: ${sub}`, hint: "Run `run402 org --help` for usage.", details: { command: "org", subcommand: sub } });
+      failUnknownSubcommand("org", sub);
   }
 }

package/lib/projects.mjs

@@ -5,7 +5,7 @@ import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.
 import { withAutoApprove } from "./operator.mjs";
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail, parseFlagJson } from "./sdk-errors.mjs";
-import { assertKnownFlags, failBadProjectId, flagValue, hasHelp, normalizeArgv, positionalArgs, resolvePositionalProject, validateRegularFile } from "./argparse.mjs";
+import { assertKnownFlags, failBadProjectId, flagValue, hasHelp, normalizeArgv, positionalArgs, resolveProjectSelector, validateRegularFile, failUnknownSubcommand } from "./argparse.mjs";
 
 const HELP = `run402 projects — Manage your deployed Run402 projects
 
@@ -21,8 +21,8 @@ Subcommands:
   tenant-payments [project_id] [--status <s>]  List redacted tenant x402 payments for priced routes
   get   [id]                              Authoritative server read: status, org, tier, active deploy, mailbox, usage vs limits (live; no keys)
   current                                 Show the active project pointer and validation status
-  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)
+  sql   "<query>" [--project <id>] [--file <path>] [--params '<json>']  Run a SQL query (supports parameterized queries)
+  rest  <table> [--query "<params>"] [--project <id>]  Query a table via the REST API (PostgREST)
   usage [id]                              Show compute/storage usage for a project
   costs [id] [--window <w>]               Show admin-only per-project revenue/cost/margin
   schema [id]                             Inspect the database schema
@@ -210,23 +210,25 @@ Examples:
   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]
+  run402 projects sql "<query>" [--project <id>] [options]
+  run402 projects sql --file <path> [--project <id>] [options]
+
+Legacy (still supported):
+  run402 projects sql <prj_id> "<query>" [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:
+  --project <id>      Project ID (defaults to the active project; a leading
+                      prj_... positional is also still accepted)
   --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 prj_abc123 "SELECT * FROM users LIMIT 5"
-  run402 projects sql prj_abc123 "SELECT * FROM users WHERE id = $1" --params '[42]'
-  run402 projects sql prj_abc123 --file setup.sql
+  run402 projects sql "SELECT * FROM users LIMIT 5" --project prj_abc123
+  run402 projects sql "SELECT * FROM users WHERE id = $1" --params '[42]'
+  run402 projects sql --file setup.sql --project prj_abc123
 `,
   costs: `run402 projects costs — Show admin-only per-project finance
 
@@ -411,6 +413,12 @@ async function applyExpose(projectId, args = []) {
 
 async function validateExpose(args = []) {
   let projectId = null;
+  let projectFlag = null;
+  if (args.includes("--project")) {
+    projectFlag = flagValue(args, "--project");
+    const idx = args.indexOf("--project");
+    args = [...args.slice(0, idx), ...args.slice(idx + 2)];
+  }
   let file = null;
   let inline = null;
   let migrationFile = null;
@@ -473,8 +481,15 @@ async function validateExpose(args = []) {
     });
   }
 
+  if (projectFlag !== null && projectId !== null && projectFlag !== projectId) {
+    fail({
+      code: "BAD_USAGE",
+      message: `Conflicting project ids: --project ${projectFlag} vs positional ${projectId}`,
+      details: { project_flag: projectFlag, positional: projectId },
+    });
+  }
   const activeProjectId = getActiveProjectId();
-  const project = projectId || activeProjectId || undefined;
+  const project = projectFlag || projectId || activeProjectId || undefined;
   if (!project) allowanceAuthHeaders("/projects/v1/expose/validate");
   const migration = migrationFile ? readFileSync(migrationFile, "utf-8") : migrationSql;
 
@@ -697,6 +712,10 @@ function toCliExposeValidationResult(data) {
   return { has_errors: hasErrors, ...rest };
 }
 
+// The SDK now returns the gateway SQL envelope verbatim (snake_case
+// row_count) — the wire shape is uniform end-to-end. This shim survives one
+// release as belt-and-braces against a stale local SDK build that still
+// camelCases, then can be deleted.
 function toCliSqlResult(data) {
   if (!data || typeof data !== "object" || Array.isArray(data)) return data;
   if ("row_count" in data) return data;
@@ -705,12 +724,15 @@ function toCliSqlResult(data) {
   return { ...rest, row_count: rowCount };
 }
 
-async function rest(projectId, table, queryParams) {
+async function rest(projectId, restArgs = []) {
+  const positionals = positionalArgs(restArgs, FLAGS_BY_SUB.rest.values);
+  const table = positionals[0];
+  const queryParams = flagValue(restArgs, "--query") ?? positionals[1];
   if (!table) {
     fail({
       code: "BAD_USAGE",
-      message: "Missing <table> argument. Usage: run402 projects rest [id] <table> [\"<query>\"]",
-      hint: "Run 'run402 projects schema <id>' to list tables.",
+      message: "Missing <table> argument. Usage: run402 projects rest <table> [--query \"<query>\"] [--project <id>]",
+      hint: "Run 'run402 projects schema' to list tables.",
     });
   }
   try {
@@ -841,19 +863,26 @@ const FLAGS_BY_SUB = {
     values: ["--tier", "--name", "--org", "--idempotency-key"],
   },
   list: { known: ["--org", "--all"], values: ["--org"] },
-  rename: { known: ["--name"], values: ["--name"] },
-  "tenant-payments": { known: ["--status", "--limit", "--after"], values: ["--status", "--limit", "--after"] },
-  sql: { known: ["--file", "--params"], values: ["--file", "--params"] },
-  costs: { known: ["--window"], values: ["--window"] },
-  "apply-expose": { known: ["--file"], values: ["--file"] },
+  rename: { known: ["--project", "--name"], values: ["--project", "--name"] },
+  "tenant-payments": { known: ["--project", "--status", "--limit", "--after"], values: ["--project", "--status", "--limit", "--after"] },
+  get: { known: ["--project"], values: ["--project"] },
+  rest: { known: ["--project", "--query"], values: ["--project", "--query"] },
+  usage: { known: ["--project"], values: ["--project"] },
+  schema: { known: ["--project"], values: ["--project"] },
+  "get-expose": { known: ["--project"], values: ["--project"] },
+  "promote-user": { known: ["--project"], values: ["--project"] },
+  "demote-user": { known: ["--project"], values: ["--project"] },
+  sql: { known: ["--project", "--file", "--params"], values: ["--project", "--file", "--params"] },
+  costs: { known: ["--project", "--window"], values: ["--project", "--window"] },
+  "apply-expose": { known: ["--project", "--file"], values: ["--project", "--file"] },
   "validate-expose": {
-    known: ["--file", "--migration-file", "--migration-sql"],
-    values: ["--file", "--migration-file", "--migration-sql"],
+    known: ["--project", "--file", "--migration-file", "--migration-sql"],
+    values: ["--project", "--file", "--migration-file", "--migration-sql"],
   },
-  delete: { known: ["--confirm"], values: [] },
+  delete: { known: ["--project", "--confirm"], values: ["--project"] },
   export: {
-    known: ["--scope", "--auth", "--consistency", "--idempotency-key", "--output", "--poll-interval", "--timeout", "--wait", "--json", "--json-stream"],
-    values: ["--scope", "--auth", "--consistency", "--idempotency-key", "--output", "--poll-interval", "--timeout"],
+    known: ["--project", "--scope", "--auth", "--consistency", "--idempotency-key", "--output", "--poll-interval", "--timeout", "--wait", "--json", "--json-stream"],
+    values: ["--project", "--scope", "--auth", "--consistency", "--idempotency-key", "--output", "--poll-interval", "--timeout"],
   },
 };
 
@@ -888,28 +917,28 @@ export async function run(sub, args) {
     case "use":       await use(args[0]); break;
     case "list":      await list(args); break;
     case "current":   await current(); break;
-    case "rename":    { const { projectId, rest } = resolvePositionalProject(args, { rejectBareFirst: true, valueFlags: FLAGS_BY_SUB.rename.values }); await rename(projectId, rest); break; }
-    case "tenant-payments": { const { projectId, rest } = resolvePositionalProject(args, { rejectBareFirst: true, valueFlags: FLAGS_BY_SUB["tenant-payments"].values }); await tenantPayments(projectId, rest); break; }
-    case "get":       { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await get(projectId); break; }
+    case "rename":    { const { projectId, rest } = resolveProjectSelector(args, { rejectBareFirst: true, valueFlags: FLAGS_BY_SUB.rename.values }); await rename(projectId, rest); break; }
+    case "tenant-payments": { const { projectId, rest } = resolveProjectSelector(args, { rejectBareFirst: true, valueFlags: FLAGS_BY_SUB["tenant-payments"].values }); await tenantPayments(projectId, rest); break; }
+    case "get":       { const { projectId } = resolveProjectSelector(args, { rejectBareFirst: true }); await get(projectId); break; }
     case "info":      commandMoved("info"); break;
     case "keys":      commandMoved("keys"); break;
-    case "sql":       { const { projectId, rest } = resolvePositionalProject(args, { maxBarePositionals: 1, valueFlags: FLAGS_BY_SUB.sql.values, rejectBareFirstWhenFlagPresent: ["--file"] }); 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, { rejectBareFirst: true }); await usage(projectId); break; }
-    case "costs":     { const { projectId, rest } = resolvePositionalProject(args, { rejectBareFirst: true, valueFlags: FLAGS_BY_SUB.costs.values }); await costs(projectId, rest); break; }
-    case "schema":    { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await schema(projectId); break; }
-    case "apply-expose": { const { projectId, rest } = resolvePositionalProject(args, { maxBarePositionals: 1, valueFlags: FLAGS_BY_SUB["apply-expose"].values, rejectBareFirstWhenFlagPresent: ["--file"] }); await applyExpose(projectId, rest); break; }
+    case "sql":       { const { projectId, rest } = resolveProjectSelector(args, { maxBarePositionals: 1, valueFlags: FLAGS_BY_SUB.sql.values, rejectBareFirstWhenFlagPresent: ["--file"] }); await sqlCmd(projectId, rest); break; }
+    case "rest":      { const { projectId, rest: restArgs } = resolveProjectSelector(args, { valueFlags: FLAGS_BY_SUB.rest.values }); await rest(projectId, restArgs); break; }
+    case "usage":     { const { projectId } = resolveProjectSelector(args, { rejectBareFirst: true }); await usage(projectId); break; }
+    case "costs":     { const { projectId, rest } = resolveProjectSelector(args, { rejectBareFirst: true, valueFlags: FLAGS_BY_SUB.costs.values }); await costs(projectId, rest); break; }
+    case "schema":    { const { projectId } = resolveProjectSelector(args, { rejectBareFirst: true }); await schema(projectId); break; }
+    case "apply-expose": { const { projectId, rest } = resolveProjectSelector(args, { maxBarePositionals: 1, valueFlags: FLAGS_BY_SUB["apply-expose"].values, rejectBareFirstWhenFlagPresent: ["--file"] }); await applyExpose(projectId, rest); break; }
     case "validate-expose": await validateExpose(args); break;
-    case "get-expose":   { const { projectId } = resolvePositionalProject(args, { rejectBareFirst: true }); await getExpose(projectId); break; }
-    case "delete":    { const { projectId, rest } = resolvePositionalProject(args, { rejectBareFirst: true }); await deleteProject(projectId, rest); break; }
+    case "get-expose":   { const { projectId } = resolveProjectSelector(args, { rejectBareFirst: true }); await getExpose(projectId); break; }
+    case "delete":    { const { projectId, rest } = resolveProjectSelector(args, { rejectBareFirst: true }); await deleteProject(projectId, rest); break; }
     case "export": {
       const { run } = await import("./cloud.mjs");
       await run("archives", ["create", ...args]);
       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; }
+    case "promote-user": { const { projectId, rest } = resolveProjectSelector(args); await promoteUser(projectId, rest[0]); break; }
+    case "demote-user":  { const { projectId, rest } = resolveProjectSelector(args); await demoteUser(projectId, rest[0]); break; }
     default:
-      fail({ code: "UNKNOWN_SUBCOMMAND", message: `Unknown projects subcommand: ${sub}`, hint: "Run `run402 projects --help` for usage.", details: { command: "projects", subcommand: sub } });
+      failUnknownSubcommand("projects", sub);
   }
 }