@irtio/cli 0.5.0 → 0.5.2

package/dist/index.js

@@ -8,8 +8,10 @@ usage: irtio <command>
 
 commands:
   init [dir] [--tick|--event]                     scaffold irtio/schema.ts, rpc.ts, room.ts,
-                                                  room.test.ts and irtio.json (--tick/--event
-                                                  skip the one question it otherwise asks)
+       [--name <name>]                            room.test.ts and irtio.json (--tick/--event
+                                                  skip the one question it otherwise asks;
+                                                  --name is the project name a first deploy
+                                                  registers, default the directory)
   dev [--room <file>] [--port <n>] [--no-watch]   bundle the room file and run it locally
   simulate [--bots <n>] [--seconds <n>]           drive N real clients at a running room and
           [--room <code>] [--url <ws://\u2026>]        check the built-in invariants
@@ -18,7 +20,9 @@ commands:
           [--misprediction-max <units>]           fail the run if one correction snaps a
           [--snaps-max <n>]                       prediction further than this, if more than
           [--corrections-max <perSec>]            <n> corrections fall outside the resim
-                                                  window, or above this correction rate/bot
+          [--overruns-max <n>]                    window, above this correction rate/bot, or
+                                                  above this many server tick overruns.
+                                                  exits 0 clean, 1 violation, 2 not performed
 
   login [--url <control>]                         sign in to a control plane via the browser
   whoami [--url <control>]                         print the identity the stored credential
@@ -26,11 +30,17 @@ commands:
   deploy [--allow-breaking] [--project <id>]      bundle, classify the schema change against the
          [--url <control>] [--room <file>]        last deployment, and upload \u2014 refuses breaking
          [--strategy drain|migrate]               changes unless a migration covers them;
-                                                  migrate moves LIVE rooms onto the new version
-                                                  now (drain, the default, lets them finish)
-  deploy --static <dir> [--project <id>]          upload a BUILT client directory to the project's
-         [--label <label>] [--url <control>]      static site and print the playable link
-                                                  (<label>.irt-serve.com; no build step)
+         [--name <name>] [--no-static]            migrate moves LIVE rooms onto the new version
+                                                  now (drain, the default, lets them finish).
+                                                  A project that does not exist yet is created
+                                                  as --name, else irtio.json's "name".
+                                                  With "static" in the project file the client
+                                                  directory ships too; --no-static skips it
+  deploy --static [<dir>] [--project <id>]        upload a BUILT client directory to the project's
+         [--label <label>] [--url <control>]      static site and print the playable link, and
+         [--name <name>]                          nothing else (<label>.irt-serve.com; no build
+                                                  step). Directory and label default to the
+                                                  project file's "static"
   migrate create <name>                           scaffold irtio/migrations/<n>_<name>.ts with the
                                                   live breaking changes quoted in its header
   rollback <version> [--project <id>]             re-promote deployment <version> and bring rooms
@@ -50,6 +60,13 @@ commands:
   rooms saves <room>                              list a room's save generations, newest first
   rooms restore <room> --save <id>                bring a room back from a save \u2014 DISCARDS its
                                                   current state; stops the tenant if it is live
+
+every command takes --help (or -h) and prints its own usage, which is the authority: the lines
+above are a map, and the command's own help is generated next to the code that parses it.
+
+every command that reads the project file takes -c/--config <file> to read a different one
+(dev, deploy, deploy --static, migrate create, rollback, logs, rooms, keys). Default irtio.json;
+the named file must exist. That is the test.irtio.json / prod.irtio.json pattern.
 `;
 switch (command) {
   case "init": {
@@ -58,7 +75,7 @@ switch (command) {
     break;
   }
   case "dev": {
-    const { dev } = await import("./dev-7UZZGE4U.js");
+    const { dev } = await import("./dev-QJOGXLKM.js");
     await dev(args);
     break;
   }
@@ -68,47 +85,47 @@ switch (command) {
     break;
   }
   case "login": {
-    const { login } = await import("./login-OV2EFNTJ.js");
+    const { login } = await import("./login-3EXB4CGX.js");
     await login(args);
     break;
   }
   case "whoami": {
-    const { whoami } = await import("./whoami-S73O6KJF.js");
+    const { whoami } = await import("./whoami-CI5D5RCC.js");
     await whoami(args);
     break;
   }
   case "deploy": {
     if (args.includes("--static")) {
-      const { staticDeploy } = await import("./static-deploy-LZXTDYNY.js");
+      const { staticDeploy } = await import("./static-deploy-5TBH4VNA.js");
       await staticDeploy(args);
       break;
     }
-    const { deploy } = await import("./deploy-6OM3UYNL.js");
+    const { deploy } = await import("./deploy-3SABPL3T.js");
     await deploy(args);
     break;
   }
   case "migrate": {
-    const { migrate } = await import("./migrate-3R6VRW4J.js");
+    const { migrate } = await import("./migrate-WUO2GBMX.js");
     await migrate(args);
     break;
   }
   case "rollback": {
-    const { rollback } = await import("./rollback-CLQVYFHW.js");
+    const { rollback } = await import("./rollback-GA6UY772.js");
     await rollback(args);
     break;
   }
   case "keys": {
-    const { keys } = await import("./keys-KEKO3EJ6.js");
+    const { keys } = await import("./keys-XBORZAPI.js");
     await keys(args);
     break;
   }
   case "logs": {
-    const { logs } = await import("./logs-5OUDPAIX.js");
+    const { logs } = await import("./logs-2EOXLNWF.js");
     await logs(args);
     break;
   }
   case "rooms": {
-    const { rooms } = await import("./rooms-OJ3JLYHD.js");
+    const { rooms } = await import("./rooms-B66LQIIF.js");
     await rooms(args);
     break;
   }

package/dist/init.d.ts

@@ -21,6 +21,8 @@ interface InitArgs {
     readonly mode?: RoomMode;
     /** `--physics`: a Rapier room with a shared world-builder and client prediction (D22). */
     readonly physics?: boolean;
+    /** `--name`: the project's display name. Defaults to the directory name. */
+    readonly name?: string;
 }
 interface RunInitOptions {
     /** Where the project lives. Defaults to `process.cwd()`. */
@@ -28,6 +30,8 @@ interface RunInitOptions {
     readonly dir?: string;
     readonly mode?: RoomMode;
     readonly physics?: boolean;
+    /** The project's display name, written to `irtio.json`. Defaults to the directory name. */
+    readonly name?: string;
     /**
      * Asks the one question. Injected so tests never touch a TTY; the default reads stdin when it
      * is a TTY and otherwise takes the default answer rather than hanging in a pipeline.
@@ -41,6 +45,8 @@ interface InitResult {
     /** Absolute path of the scaffolded project. */
     readonly dir: string;
     readonly project: string;
+    /** The name written to `irtio.json`; what the first deploy registers the project as. */
+    readonly name: string;
     readonly mode: RoomMode;
     /** Files written, relative to `dir`, in emit order. */
     readonly created: readonly string[];
@@ -53,6 +59,7 @@ interface InitResult {
  * `irtio init [dir] [--tick|--event]`. Hand-rolled like `parseDevArgs`: the CLI has no
  * argument-parsing dependency and four flags do not earn one.
  */
+declare const USAGE = "usage: irtio init [dir] [options]\n\nScaffolds irtio/schema.ts, irtio/rpc.ts, irtio/room.ts, irtio/room.test.ts and irtio.json.\nNothing that already exists is ever overwritten.\n\noptions:\n  [dir]              where to scaffold (default: here)\n  --tick             a tick room, without asking\n  --event            an event room, without asking\n  --physics          scaffold a physics room and its shared world builder\n  --name <name>      the project name a first deploy registers (default: the directory)\n  -h, --help         print this\n";
 declare function parseInitArgs(args: readonly string[]): InitArgs;
 /** `p_` + 16 hex characters: the project id *is* the public key, so it is not a secret. */
 declare function generateProjectId(): string;
@@ -64,4 +71,4 @@ declare function runInit(options?: RunInitOptions): Promise<InitResult>;
 /** Thin on purpose: parse, run, and turn a thrown message into an exit code. */
 declare function init(args: readonly string[]): Promise<void>;
 
-export { INIT_DEPENDENCIES, type InitArgs, type InitResult, type RoomMode, type RunInitOptions, generateProjectId, init, parseInitArgs, runInit };
+export { INIT_DEPENDENCIES, type InitArgs, type InitResult, type RoomMode, type RunInitOptions, USAGE, generateProjectId, init, parseInitArgs, runInit };

package/dist/init.js

@@ -1,3 +1,9 @@
+import {
+  HelpRequested,
+  helpFor,
+  helpRequested
+} from "./chunk-TV66QHFP.js";
+
 // src/init.ts
 import { randomBytes } from "crypto";
 import { existsSync } from "fs";
@@ -13,10 +19,33 @@ var INIT_DEPENDENCIES = [
 ];
 var DEFAULT_TICK_RATE = 20;
 var DEFAULT_IDLE_MS = 3e4;
+var USAGE = `usage: irtio init [dir] [options]
+
+Scaffolds irtio/schema.ts, irtio/rpc.ts, irtio/room.ts, irtio/room.test.ts and irtio.json.
+Nothing that already exists is ever overwritten.
+
+options:
+  [dir]              where to scaffold (default: here)
+  --tick             a tick room, without asking
+  --event            an event room, without asking
+  --physics          scaffold a physics room and its shared world builder
+  --name <name>      the project name a first deploy registers (default: the directory)
+  -h, --help         print this
+`;
 function parseInitArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
   const parsed = {};
-  for (const arg of args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
     switch (arg) {
+      case "--name": {
+        const value = args[++i];
+        if (value === void 0 || value === "") {
+          throw new Error("irtio init: --name needs a value");
+        }
+        parsed.name = value;
+        break;
+      }
       case "--physics":
         parsed.physics = true;
         break;
@@ -455,11 +484,13 @@ async function runInit(options = {}) {
   }
   const configFile = path.join(dir, "irtio.json");
   let project = options.projectId ?? generateProjectId();
+  let name = options.name ?? (path.basename(dir) || "project");
   if (existsSync(configFile)) {
     try {
       const existing = JSON.parse(await readFile(configFile, "utf8"));
       if (typeof existing.project === "string" && existing.project !== "")
         project = existing.project;
+      if (typeof existing.name === "string" && existing.name !== "") name = existing.name;
     } catch {
     }
   }
@@ -469,14 +500,14 @@ async function runInit(options = {}) {
     ["irtio/world.ts", WORLD_TEMPLATE],
     ["irtio/room.ts", physicsRoomTemplate()],
     ["irtio/room.test.ts", PHYSICS_ROOM_TEST_TEMPLATE],
-    ["irtio.json", `${JSON.stringify({ project }, null, 2)}
+    ["irtio.json", `${JSON.stringify({ project, name }, null, 2)}
 `]
   ] : [
     ["irtio/schema.ts", schemaTemplate(project)],
     ["irtio/rpc.ts", RPC_TEMPLATE],
     ["irtio/room.ts", roomTemplate(mode)],
     ["irtio/room.test.ts", ROOM_TEST_TEMPLATE],
-    ["irtio.json", `${JSON.stringify({ project }, null, 2)}
+    ["irtio.json", `${JSON.stringify({ project, name }, null, 2)}
 `]
   ];
   const created = [];
@@ -498,7 +529,7 @@ async function runInit(options = {}) {
   if (skipped.length > 0) {
     log(pc.yellow(`kept ${skipped.join(", ")} (already there \u2014 nothing was overwritten)`));
   }
-  log(pc.dim(`project ${project} \xB7 ${mode} mode${physics ? " \xB7 physics" : ""}`));
+  log(pc.dim(`project ${project} (${name}) \xB7 ${mode} mode${physics ? " \xB7 physics" : ""}`));
   const installCommand = packageJson === "absent" ? `npm i ${wantedDeps.join(" ")}` : "npm install   # the irtio packages were added to your package.json";
   for (const line of nextSteps(installCommand)) log(line);
   if (physics) {
@@ -511,7 +542,7 @@ async function runInit(options = {}) {
     log("  draw from room.render (predicted + interpolated), write intents via room.state.");
     log("");
   }
-  return { dir, project, mode, created, skipped, packageJson };
+  return { dir, project, name, mode, created, skipped, packageJson };
 }
 async function init(args) {
   try {
@@ -519,15 +550,21 @@ async function init(args) {
     await runInit({
       ...parsed.dir !== void 0 ? { dir: parsed.dir } : {},
       ...parsed.mode !== void 0 ? { mode: parsed.mode } : {},
-      ...parsed.physics !== void 0 ? { physics: parsed.physics } : {}
+      ...parsed.physics !== void 0 ? { physics: parsed.physics } : {},
+      ...parsed.name !== void 0 ? { name: parsed.name } : {}
     });
   } catch (err) {
+    if (err instanceof HelpRequested) {
+      console.log(err.usage);
+      return;
+    }
     console.error(pc.red(err instanceof Error ? err.message : String(err)));
     process.exitCode = 1;
   }
 }
 export {
   INIT_DEPENDENCIES,
+  USAGE,
   generateProjectId,
   init,
   parseInitArgs,

package/dist/{keys-KEKO3EJ6.js → keys-XBORZAPI.js}

@@ -1,14 +1,16 @@
 import {
-  createApiClient,
-  isLoginRequired
-} from "./chunk-I37DLT7K.js";
+  readProjectConfig
+} from "./chunk-32QTPKVT.js";
 import {
+  createApiClient,
+  helpRequested,
+  isLoginRequired,
   resolveControlUrlForUser
-} from "./chunk-NVUKSP5U.js";
+} from "./chunk-TV66QHFP.js";
 
 // src/keys.ts
-import { existsSync } from "fs";
-import { readFile } from "fs/promises";
+import "fs";
+import "fs/promises";
 import * as path from "path";
 import pc from "picocolors";
 
@@ -22,17 +24,6 @@ function signJwt(secret, claims) {
 }
 
 // src/keys.ts
-async function readIrtioJsonProject(cwd) {
-  const file = path.join(cwd, "irtio.json");
-  if (!existsSync(file)) return void 0;
-  let parsed;
-  try {
-    parsed = JSON.parse(await readFile(file, "utf8"));
-  } catch {
-    throw new Error(`irtio keys: ${file} is not valid JSON`);
-  }
-  return typeof parsed.project === "string" && parsed.project.length > 0 ? parsed.project : void 0;
-}
 function flagValue(args, flag) {
   const i = args.indexOf(flag);
   if (i === -1) return void 0;
@@ -40,11 +31,15 @@ function flagValue(args, flag) {
   if (value === void 0) throw new Error(`irtio keys: ${flag} needs a value`);
   return value;
 }
+function configFlag(args) {
+  return flagValue(args, "--config") ?? flagValue(args, "-c");
+}
 async function resolveProject(args) {
-  const project = flagValue(args, "--project") ?? await readIrtioJsonProject(process.cwd());
+  const config = await readProjectConfig(process.cwd(), "irtio keys", configFlag(args));
+  const project = flagValue(args, "--project") ?? config.project;
   if (project === void 0) {
     throw new Error(
-      "irtio keys: no project id \u2014 pass --project or run this from a project with irtio.json"
+      `irtio keys: no project id \u2014 pass --project or run this from a project with ${path.basename(config.file)}`
     );
   }
   return project;
@@ -88,9 +83,40 @@ async function runJwtSecretRetire(options) {
   log(pc.green(`retired the oldest active secret; ${result.active} remain(s) active`));
   log(pc.dim("tokens signed with the retired secret stop verifying at the next placement"));
 }
+var USAGE = `usage: irtio keys jwt-secret [retire] [options]
+       irtio keys jwt-mint --secret <s> --sub <playerId> [options]
+
+jwt-secret mints a signing secret for the project. It is printed ONCE and never again. Running it
+a second time starts a rotation, where both secrets verify; retire finishes one by dropping the
+oldest.
+
+jwt-mint signs a test token locally, with the documented recipe. The secret you pass never leaves
+this machine.
+
+jwt-secret options:
+  retire             retire the oldest active secret for this issuer
+  --issuer <label>   the issuer to mint or retire under
+  --project <id>     project id (default: the project file)
+  -c, --config <f>   the project file to read (default irtio.json)
+  --url <control>    control plane (default: your stored login)
+
+jwt-mint options:
+  --secret <s>       the signing secret (required)
+  --sub <playerId>   the player the token is for (required)
+  --iss <label>      the issuer claim
+  --room <id>        restrict the token to one room
+  --role <r>         the role to join as
+  --ttl <sec>        lifetime in seconds (default 3600)
+
+  -h, --help         print this
+`;
 async function keys(args, deps = {}) {
   const log = deps.log ?? ((line) => console.log(line));
   const errorLog = deps.errorLog ?? ((line) => console.error(line));
+  if (helpRequested(args)) {
+    log(USAGE);
+    return;
+  }
   try {
     const sub = args[0];
     const rest = args.slice(1);
@@ -133,7 +159,7 @@ async function keys(args, deps = {}) {
       const room = flagValue(rest, "--room");
       const role = flagValue(rest, "--role");
       const iss = flagValue(rest, "--iss") ?? DEFAULT_ISSUER;
-      const project = flagValue(rest, "--project") ?? await readIrtioJsonProject(process.cwd());
+      const project = flagValue(rest, "--project") ?? (await readProjectConfig(process.cwd(), "irtio keys", configFlag(rest))).project;
       if (project === void 0) {
         throw new Error(
           "irtio keys jwt-mint: --project is required (aud must name the project the token is for)"
@@ -168,6 +194,7 @@ async function keys(args, deps = {}) {
 }
 export {
   DEFAULT_ISSUER,
+  USAGE,
   keys,
   runJwtSecret,
   runJwtSecretRetire

package/dist/{login-OV2EFNTJ.js → login-3EXB4CGX.js}

@@ -1,8 +1,11 @@
 import {
+  HelpRequested,
   credentialsPath,
+  helpFor,
+  helpRequested,
   resolveControlUrl,
   writeCredential
-} from "./chunk-NVUKSP5U.js";
+} from "./chunk-TV66QHFP.js";
 
 // src/login.ts
 import { spawn } from "child_process";
@@ -10,7 +13,16 @@ import { randomBytes } from "crypto";
 import { createServer } from "http";
 import pc from "picocolors";
 var LOGIN_TIMEOUT_MS = 3 * 60 * 1e3;
+var USAGE = `usage: irtio login [--url <control>]
+
+Signs in to a control plane through your browser and stores the credential it hands back.
+
+options:
+  --url <control>    the control plane to sign in to (default: the last one you used)
+  -h, --help         print this
+`;
 function parseLoginArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
   const parsed = {};
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -145,11 +157,16 @@ async function login(args) {
     console.log(pc.dim(`control plane: ${result.controlUrl}`));
     console.log(pc.dim(`credentials stored at ${result.file ?? credentialsPath()}`));
   } catch (err) {
+    if (err instanceof HelpRequested) {
+      console.log(err.usage);
+      return;
+    }
     console.error(pc.red(err instanceof Error ? err.message : String(err)));
     process.exitCode = 1;
   }
 }
 export {
+  USAGE,
   defaultOpenBrowser,
   login,
   parseLoginArgs,

package/dist/{logs-5OUDPAIX.js → logs-2EOXLNWF.js}

@@ -1,18 +1,36 @@
 import {
-  createApiClient,
-  isLoginRequired
-} from "./chunk-I37DLT7K.js";
+  readProjectConfig
+} from "./chunk-32QTPKVT.js";
 import {
+  HelpRequested,
+  createApiClient,
+  helpFor,
+  helpRequested,
+  isLoginRequired,
   resolveControlUrlForUser
-} from "./chunk-NVUKSP5U.js";
+} from "./chunk-TV66QHFP.js";
 
 // src/logs.ts
-import { existsSync } from "fs";
-import { readFile } from "fs/promises";
-import * as path from "path";
+import "fs";
+import "fs/promises";
+import "path";
 import pc from "picocolors";
 var POLL_MS = 2e3;
+var USAGE = `usage: irtio logs [options]
+
+Tails a project's logs, oldest line first.
+
+options:
+  --follow           poll every 2s, threading the cursor so nothing repeats
+  --since <cursor>   start after this cursor (a previous row's timestamp)
+  --room <id>        narrow to one room's stream. __tenant is the tenant's own events
+  --project <id>     project id (default: the project file)
+  -c, --config <f>   the project file to read (default irtio.json)
+  --url <control>    control plane (default: your stored login)
+  -h, --help         print this
+`;
 function parseLogsArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
   const parsed = {
     follow: false
   };
@@ -40,6 +58,14 @@ function parseLogsArgs(args) {
         parsed.project = value;
         break;
       }
+      case "-c":
+      case "--config": {
+        const value = args[++i];
+        if (value === void 0 || value === "")
+          throw new Error("irtio logs: --config needs a value");
+        parsed.config = value;
+        break;
+      }
       case "--url": {
         const value = args[++i];
         if (value === void 0) throw new Error("irtio logs: --url needs a value");
@@ -81,23 +107,13 @@ async function runLogs(options) {
     await new Promise((resolve) => setTimeout(resolve, options.pollMs ?? POLL_MS));
   }
 }
-async function readIrtioJsonProject(cwd) {
-  const file = path.join(cwd, "irtio.json");
-  if (!existsSync(file)) return void 0;
-  let parsed;
-  try {
-    parsed = JSON.parse(await readFile(file, "utf8"));
-  } catch {
-    throw new Error(`irtio logs: ${file} is not valid JSON`);
-  }
-  return typeof parsed.project === "string" && parsed.project.length > 0 ? parsed.project : void 0;
-}
 async function logs(args, deps = {}) {
   const log = deps.log ?? ((line) => console.log(line));
   const errorLog = deps.errorLog ?? ((line) => console.error(line));
   try {
     const parsed = parseLogsArgs(args);
-    const project = parsed.project ?? await readIrtioJsonProject(process.cwd());
+    const config = await readProjectConfig(process.cwd(), "irtio logs", parsed.config);
+    const project = parsed.project ?? config.project;
     if (project === void 0) {
       throw new Error(
         "irtio logs: no project id \u2014 pass --project or run this from a project with irtio.json"
@@ -113,6 +129,10 @@ async function logs(args, deps = {}) {
       ...deps.client !== void 0 ? { client: deps.client } : {}
     });
   } catch (err) {
+    if (err instanceof HelpRequested) {
+      log(err.usage);
+      return;
+    }
     if (isLoginRequired(err)) {
       errorLog(pc.red("not logged in"));
       errorLog("run: irtio login");
@@ -124,6 +144,7 @@ async function logs(args, deps = {}) {
   }
 }
 export {
+  USAGE,
   logs,
   parseLogsArgs,
   runLogs

package/dist/{migrate-3R6VRW4J.js → migrate-WUO2GBMX.js}

@@ -2,16 +2,20 @@ import {
   bundleRoom
 } from "./chunk-KRQUAEN2.js";
 import {
-  createApiClient,
-  isLoginRequired
-} from "./chunk-I37DLT7K.js";
+  readProjectConfig
+} from "./chunk-32QTPKVT.js";
 import {
+  HelpRequested,
+  createApiClient,
+  helpFor,
+  helpRequested,
+  isLoginRequired,
   resolveControlUrlForUser
-} from "./chunk-NVUKSP5U.js";
+} from "./chunk-TV66QHFP.js";
 
 // src/migrate.ts
 import { existsSync } from "fs";
-import { mkdir, mkdtemp, readFile, readdir, writeFile } from "fs/promises";
+import { mkdir, mkdtemp, readdir, writeFile } from "fs/promises";
 import { tmpdir } from "os";
 import * as path from "path";
 import { pathToFileURL } from "url";
@@ -23,7 +27,18 @@ import {
 import pc from "picocolors";
 var MIGRATIONS_DIR = "irtio/migrations";
 var ROOM_CANDIDATES = ["irtio/room.ts", "irtio/room.js", "room.ts"];
+var USAGE = `usage: irtio migrate create <name> [-c <file>]
+
+Scaffolds irtio/migrations/<n>_<name>.ts, with the breaking changes against the live deployment
+quoted in its header so the transform has something to answer.
+
+options:
+  <name>             a short name for the migration, e.g. rename-hp
+  -c, --config <f>   the project file to read (default irtio.json)
+  -h, --help         print this
+`;
 function parseMigrateArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
   const [sub, name, ...rest] = args;
   if (sub !== "create") {
     throw new Error(
@@ -35,9 +50,20 @@ function parseMigrateArgs(args) {
       "irtio migrate create: a name is required, e.g. irtio migrate create rename-hp"
     );
   }
-  if (rest.length > 0)
-    throw new Error(`irtio migrate create: unexpected extra argument ${JSON.stringify(rest[0])}`);
-  return { command: "create", args: { name } };
+  let config;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "-c" || arg === "--config") {
+      const value = rest[++i];
+      if (value === void 0 || value === "") {
+        throw new Error("irtio migrate create: --config needs a value");
+      }
+      config = value;
+      continue;
+    }
+    throw new Error(`irtio migrate create: unexpected extra argument ${JSON.stringify(arg)}`);
+  }
+  return { command: "create", args: config === void 0 ? { name } : { name, config } };
 }
 function resolveEntry(cwd, room) {
   if (room !== void 0) {
@@ -53,12 +79,6 @@ function resolveEntry(cwd, room) {
     `irtio migrate create: no room file found in ${cwd} (looked for: ${ROOM_CANDIDATES.join(", ")})`
   );
 }
-async function readIrtioJsonProject(cwd) {
-  const file = path.join(cwd, "irtio.json");
-  if (!existsSync(file)) return void 0;
-  const parsed = JSON.parse(await readFile(file, "utf8"));
-  return typeof parsed.project === "string" && parsed.project.length > 0 ? parsed.project : void 0;
-}
 async function scanDirectoryVersion(cwd) {
   const dir = path.join(cwd, MIGRATIONS_DIR);
   if (!existsSync(dir)) return 1;
@@ -115,7 +135,8 @@ async function runMigrateCreate(options) {
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const log = options.log ?? ((line) => console.log(line));
   const controlUrl = await resolveControlUrlForUser(options.controlUrl);
-  const projectId = options.project ?? await readIrtioJsonProject(cwd);
+  const config = await readProjectConfig(cwd, "irtio migrate", options.config);
+  const projectId = options.project ?? config.project;
   let version;
   let versionSource;
   let previousSchemaJson;
@@ -191,6 +212,10 @@ async function migrate(args, deps = {}) {
       ...deps.client !== void 0 ? { client: deps.client } : {}
     });
   } catch (err) {
+    if (err instanceof HelpRequested) {
+      log(err.usage);
+      return;
+    }
     if (isLoginRequired(err)) {
       errorLog(pc.red("not logged in"));
       errorLog("run: irtio login");
@@ -202,6 +227,7 @@ async function migrate(args, deps = {}) {
   }
 }
 export {
+  USAGE,
   migrate,
   parseMigrateArgs,
   runMigrateCreate