run402 4.8.0 → 4.9.0

package/cli.mjs

@@ -79,15 +79,15 @@ Examples:
   run402 allowance fund
   run402 deploy apply --manifest app.json
   run402 apply --manifest app.json --rehearse --json
-  run402 snapshots list prj_...
-  run402 branches create prj_... --ttl-days 7 --json
-  run402 cloud archives create prj_... --wait --output ./project.r402ar --json
+  run402 snapshots list --project prj_...
+  run402 branches create --project prj_... --ttl-days 7 --json
+  run402 cloud archives create --project prj_... --wait --output ./project.r402ar --json
   run402 core projects import ./project.r402ar --name imported-project --env-file ./required.env --json
   run402 jobs submit --file job.json
   run402 projects list
-  run402 projects sql <project_id> "SELECT * FROM users LIMIT 5"
-  run402 functions deploy <project_id> my-fn --file handler.ts
-  run402 secrets set <project_id> API_KEY sk-1234
+  run402 projects sql "SELECT * FROM users LIMIT 5" --project <project_id>
+  run402 functions deploy my-fn --file handler.ts --project <project_id>
+  run402 secrets set API_KEY --value sk-1234 --project <project_id>
   run402 image generate "a startup mascot, pixel art" --output logo.png
 
 Getting started:

package/lib/admin.mjs

@@ -1,6 +1,6 @@
 import { getSdk } from "./sdk.mjs";
 import { reportSdkError, fail } from "./sdk-errors.mjs";
-import { assertKnownFlags, hasHelp, normalizeArgv } from "./argparse.mjs";
+import { assertKnownFlags, hasHelp, normalizeArgv, resolveProjectSelector } from "./argparse.mjs";
 
 const HELP = `run402 admin — Platform-admin operations (v1.57+)
 
@@ -17,12 +17,12 @@ Subcommands:
                                          (\`reactivated: true\` in the response).
                                          Replaces the v1.56 per-project pin.
 
-  archive <project_id> [--reason "..."]  Moderate-archive a single project. Sets
+  archive [--project <id>] [--reason "..."]  Moderate-archive a single project. Sets
                                          projects.archived_at = NOW(). Independent
                                          of organization lifecycle; the rest of the
                                          organization's projects keep serving.
 
-  reactivate <project_id>                Un-archive a project (flips archived_at
+  reactivate [--project <id>]            Un-archive a project (flips archived_at
                                          back to NULL). In v1.57 this no longer
                                          touches organization-level lifecycle — to
                                          reactivate a grace-state account, use
@@ -65,6 +65,9 @@ Examples:
   archive: `run402 admin archive — Moderate-archive a single project
 
 Usage:
+  run402 admin archive [--project <id>] [--reason "..."]
+
+Legacy (still supported):
   run402 admin archive <project_id> [--reason "..."]
 
 Options:
@@ -84,6 +87,9 @@ Examples:
   reactivate: `run402 admin reactivate — Un-archive a project
 
 Usage:
+  run402 admin reactivate [--project <id>]
+
+Legacy (still supported):
   run402 admin reactivate <project_id>
 
 Notes:
@@ -100,8 +106,8 @@ Examples:
 
 const FLAGS_BY_SUB = {
   "lease-perpetual": { known: ["--enable", "--disable"], values: [] },
-  archive: { known: ["--reason"], values: ["--reason"] },
-  reactivate: { known: [], values: [] },
+  archive: { known: ["--project", "--reason"], values: ["--project", "--reason"] },
+  reactivate: { known: ["--project"], values: ["--project"] },
 };
 
 function validateFlags(sub, args) {
@@ -137,18 +143,12 @@ async function leasePerpetual(args) {
 }
 
 async function archive(args) {
-  const projectId = args.find((a) => typeof a === "string" && !a.startsWith("--"));
-  if (!projectId) {
-    fail({
-      code: "BAD_USAGE",
-      message: "Missing <project_id>.",
-      hint: "run402 admin archive <project_id> [--reason \"...\"]",
-    });
-  }
+  // Canonical: --project <id>; legacy leading prj_... positional kept.
+  const { projectId, rest } = resolveProjectSelector(args, { valueFlags: FLAGS_BY_SUB.archive.values });
   let reason;
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--reason" && args[i + 1] !== undefined) {
-      reason = args[++i];
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--reason" && rest[i + 1] !== undefined) {
+      reason = rest[++i];
     }
   }
   try {
@@ -160,14 +160,7 @@ async function archive(args) {
 }
 
 async function reactivate(args) {
-  const projectId = args.find((a) => typeof a === "string" && !a.startsWith("--"));
-  if (!projectId) {
-    fail({
-      code: "BAD_USAGE",
-      message: "Missing <project_id>.",
-      hint: "run402 admin reactivate <project_id>",
-    });
-  }
+  const { projectId } = resolveProjectSelector(args, { valueFlags: FLAGS_BY_SUB.reactivate.values });
   try {
     const data = await getSdk().admin.reactivateProject(projectId);
     console.log(JSON.stringify(data, null, 2));

package/lib/apps.mjs

@@ -1,7 +1,7 @@
 import { allowanceAuthHeaders, saveProject } from "./config.mjs";
 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, resolveProjectSelector } from "./argparse.mjs";
 
 const HELP = `run402 apps — Browse and manage the app marketplace
 
@@ -10,15 +10,20 @@ Usage:
 
 Subcommands:
   browse  [--tag <tag>]                   Browse public apps
-  fork    <version_id> <name> [--subdomain <name>]
+  fork    <version_id> --name <name> [--subdomain <name>]
                                            Fork a published app into your own project
-  publish <id> [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed]
+  publish [--project <id>] [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed]
                                            Publish a project as an app
-  versions <id>                            List published versions of a project
+  versions [--project <id>]                List published versions of a project
   inspect <version_id>                     Inspect a published app version
-  update  <project_id> <version_id> [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed] [--no-fork]
+  update  <version_id> [--project <id>] [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed] [--no-fork]
                                            Update a published version
-  delete  <project_id> <version_id>        Delete a published version
+  delete  <version_id> [--project <id>]    Delete a published version
+
+Legacy (still supported): the old positional forms keep working, e.g.
+  run402 apps fork <version_id> <name>
+  run402 apps publish <project_id> / versions <project_id>
+  run402 apps update <project_id> <version_id> / delete <project_id> <version_id>
 
 Examples:
   run402 apps browse
@@ -48,13 +53,16 @@ Examples:
   fork: `run402 apps fork — Fork a published app into your own project
 
 Usage:
+  run402 apps fork <version_id> --name <name> [options]
+
+Legacy (still supported):
   run402 apps fork <version_id> <name> [options]
 
 Arguments:
   <version_id>        Published version ID (e.g. ver_abc123)
-  <name>              Name for the forked project
 
 Options:
+  --name <name>       Name for the forked project (alternative to the legacy positional)
   --subdomain <name>  Claim a subdomain for the forked project
 
 Examples:
@@ -64,10 +72,13 @@ Examples:
   publish: `run402 apps publish — Publish a project as an app
 
 Usage:
-  run402 apps publish <id> [options]
+  run402 apps publish [--project <id>] [options]
 
-Arguments:
-  <id>                Project ID to publish
+Legacy (still supported):
+  run402 apps publish <project_id> [options]
+
+Options (project):
+  --project <id>      Project ID to publish (defaults to the active project)
 
 Options:
   --description <d>   Human-readable description of the app
@@ -82,10 +93,12 @@ Examples:
   update: `run402 apps update — Update a published version's metadata
 
 Usage:
+  run402 apps update <version_id> [--project <id>] [options]
+
+Legacy (still supported):
   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:
@@ -114,10 +127,10 @@ Examples:
   versions: `run402 apps versions — List published versions of a project
 
 Usage:
-  run402 apps versions <id>
+  run402 apps versions [--project <id>]
 
-Arguments:
-  <id>                Project ID (e.g. prj_abc123)
+Legacy (still supported):
+  run402 apps versions <project_id>
 
 Examples:
   run402 apps versions prj_abc123
@@ -125,10 +138,12 @@ Examples:
   delete: `run402 apps delete — Delete a published version
 
 Usage:
+  run402 apps delete <version_id> [--project <id>]
+
+Legacy (still supported):
   run402 apps delete <project_id> <version_id>
 
 Arguments:
-  <project_id>        Project ID that owns the version
   <version_id>        Published version ID to delete
 
 Examples:
@@ -158,14 +173,16 @@ async function browse(args) {
 
 async function fork(versionId, name, args) {
   const parsedArgs = normalizeArgv([versionId, name, ...args].filter((arg) => arg !== undefined));
-  const valueFlags = ["--subdomain"];
+  const valueFlags = ["--subdomain", "--name"];
   assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  const nameFlag = flagValue(parsedArgs, "--name");
+  const expected = nameFlag ? 1 : 2;
   const positionals = positionalArgs(parsedArgs, valueFlags);
-  if (positionals.length < 2) {
-    fail({ code: "BAD_USAGE", message: "Missing <version_id> and/or <name>." });
+  if (positionals.length < expected) {
+    fail({ code: "BAD_USAGE", message: nameFlag ? "Missing <version_id>." : "Missing <version_id> and/or <name>." });
   }
-  if (positionals.length > 2) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps fork: ${positionals[2]}` });
+  if (positionals.length > expected) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps fork: ${positionals[expected]}` });
   }
   const opts = { subdomain: flagValue(parsedArgs, "--subdomain") ?? undefined };
   // Preserve the aggressive early exit when no allowance is configured.
@@ -174,7 +191,7 @@ async function fork(versionId, name, args) {
   try {
     const data = await getSdk().apps.fork({
       versionId: positionals[0],
-      name: positionals[1],
+      name: nameFlag ?? positionals[1],
       subdomain: opts.subdomain,
     });
 
@@ -195,14 +212,12 @@ async function fork(versionId, name, args) {
 
 async function publish(projectId, args) {
   const parsedArgs = normalizeArgv([projectId, ...args].filter((arg) => arg !== undefined));
-  const valueFlags = ["--description", "--tags", "--visibility"];
+  const valueFlags = ["--project", "--description", "--tags", "--visibility"];
   assertKnownFlags(parsedArgs, [...valueFlags, "--fork-allowed", "--help", "-h"], valueFlags);
-  const positionals = positionalArgs(parsedArgs, valueFlags);
-  if (positionals.length < 1) {
-    fail({ code: "BAD_USAGE", message: "Missing <id>." });
-  }
-  if (positionals.length > 1) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps publish: ${positionals[1]}` });
+  const { projectId: resolvedProject, rest } = resolveProjectSelector(parsedArgs, { valueFlags });
+  const positionals = positionalArgs(rest, valueFlags);
+  if (positionals.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps publish: ${positionals[0]}` });
   }
   const opts = { description: undefined, tags: undefined, visibility: undefined, forkAllowed: undefined };
   opts.description = flagValue(parsedArgs, "--description") ?? undefined;
@@ -211,7 +226,7 @@ async function publish(projectId, args) {
   if (opts.visibility) assertAllowedValue(opts.visibility, ["public", "unlisted", "private"], "--visibility");
   if (parsedArgs.includes("--fork-allowed")) opts.forkAllowed = true;
   try {
-    const data = await getSdk().apps.publish(positionals[0], {
+    const data = await getSdk().apps.publish(resolvedProject, {
       description: opts.description,
       tags: opts.tags,
       visibility: opts.visibility,
@@ -225,13 +240,14 @@ async function publish(projectId, args) {
 
 async function versions(projectId, args = []) {
   const parsedArgs = normalizeArgv([projectId, ...args].filter((arg) => arg !== undefined));
-  assertKnownFlags(parsedArgs, ["--help", "-h"]);
-  const positionals = positionalArgs(parsedArgs);
-  if (positionals.length !== 1) {
-    fail({ code: "BAD_USAGE", message: positionals.length === 0 ? "Missing <id>." : `Unexpected argument for apps versions: ${positionals[1]}` });
+  assertKnownFlags(parsedArgs, ["--project", "--help", "-h"], ["--project"]);
+  const { projectId: resolvedProject, rest } = resolveProjectSelector(parsedArgs, { valueFlags: ["--project"] });
+  const positionals = positionalArgs(rest, ["--project"]);
+  if (positionals.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps versions: ${positionals[0]}` });
   }
   try {
-    const data = await getSdk().apps.listVersions(positionals[0]);
+    const data = await getSdk().apps.listVersions(resolvedProject);
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -255,14 +271,15 @@ async function inspect(versionId, args = []) {
 
 async function update(projectId, versionId, args) {
   const parsedArgs = normalizeArgv([projectId, versionId, ...args].filter((arg) => arg !== undefined));
-  const valueFlags = ["--description", "--tags", "--visibility"];
+  const valueFlags = ["--project", "--description", "--tags", "--visibility"];
   assertKnownFlags(parsedArgs, [...valueFlags, "--fork-allowed", "--no-fork", "--help", "-h"], valueFlags);
-  const positionals = positionalArgs(parsedArgs, valueFlags);
-  if (positionals.length < 2) {
-    fail({ code: "BAD_USAGE", message: "Missing <project_id> and/or <version_id>." });
+  const { projectId: resolvedProject, rest } = resolveProjectSelector(parsedArgs, { valueFlags });
+  const positionals = positionalArgs(rest, valueFlags);
+  if (positionals.length < 1) {
+    fail({ code: "BAD_USAGE", message: "Missing <version_id>." });
   }
-  if (positionals.length > 2) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps update: ${positionals[2]}` });
+  if (positionals.length > 1) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps update: ${positionals[1]}` });
   }
   if (parsedArgs.includes("--fork-allowed") && parsedArgs.includes("--no-fork")) {
     fail({ code: "BAD_USAGE", message: "Provide either --fork-allowed or --no-fork, not both." });
@@ -275,8 +292,8 @@ async function update(projectId, versionId, args) {
   if (parsedArgs.includes("--fork-allowed")) opts.fork_allowed = true;
   if (parsedArgs.includes("--no-fork")) opts.fork_allowed = false;
   try {
-    await getSdk().apps.updateVersion(positionals[0], positionals[1], opts);
-    console.log(JSON.stringify({ project_id: positionals[0], version_id: positionals[1], updated: true }));
+    await getSdk().apps.updateVersion(resolvedProject, positionals[0], opts);
+    console.log(JSON.stringify({ project_id: resolvedProject, version_id: positionals[0], updated: true }));
   } catch (err) {
     reportSdkError(err);
   }
@@ -284,17 +301,18 @@ async function update(projectId, versionId, args) {
 
 async function deleteVersion(projectId, versionId, args = []) {
   const parsedArgs = normalizeArgv([projectId, versionId, ...args].filter((arg) => arg !== undefined));
-  assertKnownFlags(parsedArgs, ["--help", "-h"]);
-  const positionals = positionalArgs(parsedArgs);
-  if (positionals.length < 2) {
-    fail({ code: "BAD_USAGE", message: "Missing <project_id> and/or <version_id>." });
+  assertKnownFlags(parsedArgs, ["--project", "--help", "-h"], ["--project"]);
+  const { projectId: resolvedProject, rest } = resolveProjectSelector(parsedArgs, { valueFlags: ["--project"] });
+  const positionals = positionalArgs(rest, ["--project"]);
+  if (positionals.length < 1) {
+    fail({ code: "BAD_USAGE", message: "Missing <version_id>." });
   }
-  if (positionals.length > 2) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps delete: ${positionals[2]}` });
+  if (positionals.length > 1) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for apps delete: ${positionals[1]}` });
   }
   try {
-    await getSdk().apps.deleteVersion(positionals[0], positionals[1]);
-    console.log(JSON.stringify({ project_id: positionals[0], version_id: positionals[1], deleted: true }));
+    await getSdk().apps.deleteVersion(resolvedProject, positionals[0]);
+    console.log(JSON.stringify({ project_id: resolvedProject, version_id: positionals[0], deleted: true }));
   } catch (err) {
     reportSdkError(err);
   }

package/lib/argparse.mjs

@@ -19,8 +19,14 @@ export function hasHelp(args = []) {
   return args.includes("--help") || args.includes("-h");
 }
 
+// CLI-wide convention: every command accepts `--json`. Where stdout is already
+// JSON (the vast majority of commands) it is a no-op; commands with a human
+// default switch on it explicitly. Baking it into the baseline known set here
+// makes the convention self-maintaining for future commands.
+const ALWAYS_KNOWN_FLAGS = ["--json"];
+
 export function assertKnownFlags(args = [], knownFlags = [], flagsWithValues = []) {
-  const known = new Set(knownFlags);
+  const known = new Set([...knownFlags, ...ALWAYS_KNOWN_FLAGS]);
   const valueFlags = new Set(flagsWithValues);
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -301,6 +307,67 @@ export function resolvePositionalProject(args, opts = {}) {
   return { projectId: resolveProjectId(null), rest: Array.isArray(args) ? args : [] };
 }
 
+// Resolve the project id for a project-scoped command from BOTH accepted
+// forms — the canonical `--project <id>` flag and the legacy leading
+// positional `prj_...` — with active-project fallback (CLI-wide convention).
+//
+// Precedence:
+//   1. explicit `--project <id>` (canonical)
+//   2. a leading positional starting with "prj_" (legacy compat, no warning)
+//   3. the active project (`resolveProjectId(null)`)
+//
+// If BOTH a `--project` flag and a leading `prj_` positional are present and
+// they DIFFER, fail with BAD_USAGE ("Conflicting project ids"). If they agree,
+// the duplicate positional is consumed silently.
+//
+// Returns { projectId, rest } where `rest` is args with the project selector
+// tokens (the flag+value pair and/or the leading positional) removed.
+//
+// Options (in addition to every `resolvePositionalProject` option, which this
+// helper delegates to for the no-flag path):
+//   requireRestPositional: only treat a leading `prj_` positional as the
+//     project selector when at least one more bare positional follows (counted
+//     with opts.valueFlags). Needed by commands whose OWN attribute is itself a
+//     project id (e.g. `branches renew <branch-project-id>`).
+export function resolveProjectSelector(args, opts = {}) {
+  const list = Array.isArray(args) ? [...args] : [];
+  let flagProject = null;
+  const flagIdx = list.indexOf("--project");
+  if (flagIdx !== -1) {
+    flagProject = flagValue(list, "--project");
+    list.splice(flagIdx, 2);
+  }
+
+  const first = list[0];
+  let leadingIsProject = typeof first === "string" && first.startsWith("prj_");
+  if (leadingIsProject && opts.requireRestPositional) {
+    const remainder = positionalArgs(list.slice(1), opts.valueFlags ?? []);
+    if (remainder.length === 0) leadingIsProject = false;
+  }
+
+  if (flagProject !== null) {
+    if (leadingIsProject) {
+      if (first !== flagProject) {
+        fail({
+          code: "BAD_USAGE",
+          message: `Conflicting project ids: --project ${flagProject} vs positional ${first}`,
+          hint: "Pass the project once — prefer --project <id>.",
+          details: { project_flag: flagProject, positional: first },
+        });
+      }
+      list.shift();
+    }
+    return { projectId: flagProject, rest: list };
+  }
+
+  if (!leadingIsProject && typeof first === "string" && first.startsWith("prj_")) {
+    // A lone prj_ positional deliberately NOT consumed as the selector
+    // (requireRestPositional): it is the command's own attribute.
+    return { projectId: resolveProjectId(null), rest: list };
+  }
+  return resolvePositionalProject(list, opts);
+}
+
 function closestFlag(flag, candidates) {
   let best = null;
   let bestDistance = Number.POSITIVE_INFINITY;

package/lib/assets.mjs

@@ -54,7 +54,7 @@ Options:
   --exif-policy keep|strip  v1.50: EXIF retention policy for image uploads (default keep).
   --stream            NDJSON per-file progress events (for agent consumption).
                       Without --stream, only the final results array is
-                      printed. --json is a deprecated alias for --stream.
+                      printed. --json is an accepted alias for --stream.
   --prefix <p>        Prefix filter (ls only)
   --limit <n>         Max results (ls only; default 100, max 1000)
   --sort <key>        v1.50 ls only: key:asc | createdAt:asc | createdAt:desc (default key:asc).
@@ -103,7 +103,7 @@ Options:
                       from the stored bytes and the image_exif response field.
   --stream            Emit NDJSON per-file progress events on stdout (for
                       agent consumption). Default: emit only the final
-                      results array (also JSON). --json is a deprecated
+                      results array (also JSON). --json is an accepted
                       alias for --stream.
 
 Examples:
@@ -256,12 +256,10 @@ function parseArgs(rawArgs) {
     else if (a === "--concurrency") out.concurrency = parseIntegerFlag("--concurrency", args[++i], { min: 1 });
     else if (a === "--no-resume") out.resume = false;
     else if (a === "--stream") out.stream = true;
-    else if (a === "--json") {
-      out.stream = true;
-      process.stderr.write(
-        "# warning: `--json` on `assets put` is deprecated and will be removed in a future release. Use `--stream` (alias means the same thing — NDJSON progress events on stdout).\n",
-      );
-    }
+    // `--json` and `--stream` are permanent aliases on `assets put` (both mean
+    // NDJSON progress events on stdout); elsewhere `--json` is a no-op since
+    // stdout is already JSON.
+    else if (a === "--json") { out.stream = true; }
     else if (a === "--prefix") out.prefix = args[++i];
     else if (a === "--limit") out.limit = parseIntegerFlag("--limit", args[++i], { min: 1, max: 1000 });
     else if (a === "--output" || a === "-o") out.output = args[++i];

package/lib/billing.mjs

@@ -232,18 +232,20 @@ async function createEmail(args) {
 
 async function linkWallet(args) {
   const parsedArgs = normalizeArgv(args);
-  assertKnownFlags(parsedArgs, ["--help", "-h"]);
-  const positionals = positionalArgs(parsedArgs);
+  assertKnownFlags(parsedArgs, ["--wallet", "--help", "-h"], ["--wallet"]);
+  const walletFlag = flagValue(parsedArgs, "--wallet");
+  const positionals = positionalArgs(parsedArgs, ["--wallet"]);
   const organizationId = positionals[0];
-  const wallet = positionals[1];
-  if (positionals.length > 2) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing link-wallet: ${positionals[2]}` });
+  const wallet = walletFlag ?? positionals[1];
+  const max = walletFlag ? 1 : 2;
+  if (positionals.length > max) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing link-wallet: ${positionals[max]}` });
   }
   if (!organizationId || !wallet) {
     fail({
       code: "BAD_USAGE",
       message: "Missing <org_id> and/or <wallet_address>.",
-      hint: "run402 billing link-wallet <org_id> <wallet_address>",
+      hint: "run402 billing link-wallet <org_id> --wallet <wallet_address>",
     });
   }
   try {
@@ -262,19 +264,21 @@ async function linkWallet(args) {
 
 async function autoRecharge(args) {
   const parsedArgs = normalizeArgv(args);
-  const valueFlags = ["--threshold"];
+  const valueFlags = ["--threshold", "--state"];
   assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  const stateFlag = flagValue(parsedArgs, "--state");
   const positionals = positionalArgs(parsedArgs, valueFlags);
   const organizationId = positionals[0];
-  const state = positionals[1];
-  if (positionals.length > 2) {
-    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing auto-recharge: ${positionals[2]}` });
+  const state = stateFlag ?? positionals[1];
+  const max = stateFlag ? 1 : 2;
+  if (positionals.length > max) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for billing auto-recharge: ${positionals[max]}` });
   }
   if (!organizationId || !state || !["on", "off"].includes(state)) {
     fail({
       code: "BAD_USAGE",
       message: "Missing <org_id> and/or <on|off>.",
-      hint: "run402 billing auto-recharge <org_id> <on|off> [--threshold <n>]",
+      hint: "run402 billing auto-recharge <org_id> --state <on|off> [--threshold <n>]",
     });
   }
   const thresholdStr = flagValue(parsedArgs, "--threshold");

package/lib/branches.mjs

@@ -8,19 +8,23 @@ import {
   normalizeArgv,
   parseIntegerFlag,
   positionalArgs,
+  resolveProjectSelector,
 } from "./argparse.mjs";
-import { resolveProjectId } from "./config.mjs";
 
 const HELP = `run402 branches — Contained project data branches
 
 Usage:
-  run402 branches create [project-id] [--from-snapshot <snapshot-id>] [--name <label>] [--email-mode sandbox|off] [--enable-cron] [--ttl-days <n>] [--json]
-  run402 branches list [project-id] [--json]
-  run402 branches renew [project-id] <branch-project-id> [--ttl-days <n>] [--json]
-  run402 branches delete [project-id] <branch-project-id> [--json]
+  run402 branches create [--project <id>] [--from-snapshot <snapshot-id>] [--name <label>] [--email-mode sandbox|off] [--enable-cron] [--ttl-days <n>] [--json]
+  run402 branches list [--project <id>] [--json]
+  run402 branches renew <branch-project-id> [--project <id>] [--ttl-days <n>] [--json]
+  run402 branches delete <branch-project-id> [--project <id>] [--json]
+
+Legacy (still supported): a leading prj_... parent-project positional,
+e.g. run402 branches renew prj_parent prj_branch. --project defaults to the
+active project.
 `;
 
-const FLAG_VALUES = ["--from-snapshot", "--name", "--email-mode", "--ttl-days"];
+const FLAG_VALUES = ["--project", "--from-snapshot", "--name", "--email-mode", "--ttl-days"];
 const FLAGS = new Set([...FLAG_VALUES, "--enable-cron", "--json", "--help", "-h"]);
 
 export async function run(sub, args = []) {
@@ -47,7 +51,7 @@ export async function run(sub, args = []) {
 }
 
 async function create(args) {
-  const projectId = resolveOptionalProject(positionalArgs(args, FLAG_VALUES)[0]);
+  const { projectId } = resolveProjectSelector(args, { valueFlags: FLAG_VALUES });
   const emailMode = flagValue(args, "--email-mode") ?? undefined;
   if (emailMode !== undefined) assertAllowedValue(emailMode, ["sandbox", "off"], "--email-mode");
   const ttlDaysFlag = flagValue(args, "--ttl-days");
@@ -67,7 +71,7 @@ async function create(args) {
 }
 
 async function list(args) {
-  const projectId = resolveOptionalProject(positionalArgs(args, FLAG_VALUES)[0]);
+  const { projectId } = resolveProjectSelector(args, { valueFlags: FLAG_VALUES });
   try {
     const result = await getSdk().branches.list(projectId);
     console.log(JSON.stringify({ project_id: projectId, ...result }, null, 2));
@@ -100,14 +104,13 @@ async function deleteBranch(args) {
   }
 }
 
-function resolveOptionalProject(value) {
-  if (value && String(value).startsWith("prj_")) return value;
-  return resolveProjectId(null);
-}
-
 function resolveProjectAndBranch(args, usage) {
-  const pos = positionalArgs(args, FLAG_VALUES);
-  if (pos.length === 1) return { projectId: resolveProjectId(null), branchProjectId: pos[0] };
-  if (pos.length === 2 && pos[0].startsWith("prj_")) return { projectId: pos[0], branchProjectId: pos[1] };
-  fail({ code: "BAD_USAGE", message: `Usage: ${usage}` });
+  // Canonical: `<branch-project-id> [--project <parent-id>]`. Branch ids are
+  // themselves prj_..., so a leading prj_ positional is only treated as the
+  // PARENT project when a second positional follows (requireRestPositional) —
+  // the legacy `renew prj_parent prj_branch` form.
+  const { projectId, rest } = resolveProjectSelector(args, { valueFlags: FLAG_VALUES, requireRestPositional: true });
+  const pos = positionalArgs(rest, FLAG_VALUES);
+  if (pos.length !== 1) fail({ code: "BAD_USAGE", message: `Usage: ${usage}` });
+  return { projectId, branchProjectId: pos[0] };
 }

package/lib/ci.mjs

@@ -96,6 +96,8 @@ function parseFlags(args, allowed, { repeatable = new Set() } = {}) {
       positional.push(arg);
       continue;
     }
+    // CLI-wide convention: --json is accepted everywhere (stdout is already JSON).
+    if (arg === "--json") continue;
     if (!allowed.has(arg)) {
       fail({
         code: "BAD_USAGE",