miravo 0.2.3 → 0.3.0

package/src/commands/adapter.ts

@@ -0,0 +1,76 @@
+import type { EngineCommand } from "@miravo/shared";
+import { CONTROL_CMD_TIMEOUT_MS } from "@miravo/shared";
+import type { Command } from "commander";
+import { executeAdminCommand, resolveAdminUrl } from "../lib/admin-client.ts";
+import { parsePositiveInt, parseTimeoutSeconds } from "../lib/parse.ts";
+import { handleCommandError, handleCommandResult } from "../logger.ts";
+
+interface AdapterOptions {
+  readonly port?: number;
+  readonly host?: string;
+  readonly json?: boolean;
+  readonly adminUrl?: string;
+  readonly timeout?: number;
+}
+
+export function registerAdapterCommand(program: Command): void {
+  const adapter = program.command("adapter").description("Manage protocol adapters (MQTT, OPC UA)");
+
+  adapter
+    .command("enable <name>")
+    .description("Enable a protocol adapter (mqtt, opcua)")
+    .option("-p, --port <number>", "Override adapter port", parsePositiveInt)
+    .option("--host <host>", "Override adapter bind host")
+    .option("--json", "Machine-readable JSON output")
+    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
+    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo adapter enable mqtt             Enable MQTT adapter
+  $ miravo adapter enable opcua -p 4841    Enable OPC UA on custom port`,
+    )
+    .action(async (name: string, options: AdapterOptions) => {
+      try {
+        const adminUrl = resolveAdminUrl(options.adminUrl);
+        const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
+        const config: Record<string, unknown> = {};
+        if (options.port !== undefined) config["port"] = options.port;
+        if (options.host !== undefined) config["host"] = options.host;
+        const command: EngineCommand = {
+          type: "enableAdapter",
+          adapter: name,
+          ...(Object.keys(config).length > 0 ? { config } : {}),
+        };
+        const result = await executeAdminCommand(adminUrl, command, timeoutMs);
+        handleCommandResult(result, options.json);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+
+  adapter
+    .command("disable <name>")
+    .description("Disable a running protocol adapter (mqtt, opcua)")
+    .option("--json", "Machine-readable JSON output")
+    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
+    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo adapter disable mqtt            Disable MQTT adapter`,
+    )
+    .action(async (name: string, options: AdapterOptions) => {
+      try {
+        const adminUrl = resolveAdminUrl(options.adminUrl);
+        const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
+        const command: EngineCommand = { type: "disableAdapter", adapter: name };
+        const result = await executeAdminCommand(adminUrl, command, timeoutMs);
+        handleCommandResult(result, options.json);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}

package/src/commands/cli-test-setup.ts

@@ -26,7 +26,7 @@ const allLoggers = [logger, engineLog, mqttLog, configLog, lifecycleLog, faultLo
 
 export function muteAllLoggers(): void {
   unlockLogger();
-  configureLogger({ silent: true });
+  configureLogger({ quiet: true });
   for (const l of allLoggers) {
     l.level = -999;
     l.setReporters([noopReporter]);

package/src/commands/fork.ts

@@ -17,6 +17,13 @@ export function registerForkCommand(program: Command): void {
     .command("model <name>")
     .description("Fork a model to ~/.miravo/registry/local/models/")
     .option("--force", "Overwrite if already exists in local")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo fork model centrifugal-pump     Fork a model for customization
+  $ miravo fork model centrifugal-pump --force  Overwrite existing fork`,
+    )
     .action(async (name: string, options: { readonly force?: boolean }) => {
       await forkModelAction(name, options);
     });
@@ -26,6 +33,13 @@ export function registerForkCommand(program: Command): void {
     .description("Fork a template and its referenced models to ~/.miravo/registry/local/")
     .option("--force", "Overwrite if already exists in local")
     .option("--models-only", "Only fork referenced models, skip the template itself")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo fork template water-treatment   Fork template + referenced models
+  $ miravo fork template water-treatment --models-only  Fork only models`,
+    )
     .action(
       async (
         idNameOrPath: string,

package/src/commands/inject.test.ts

@@ -8,7 +8,7 @@ describe("miravo inject", () => {
   test("command is registered with correct name and options", async () => {
     const { cmd: injectCmd } = await findCliCommand("inject");
     expect(injectCmd).toBeDefined();
-    expect(injectCmd?.description()).toBe("Inject or clear a fault on a running twin instance");
+    expect(injectCmd?.description()).toBe("Trigger or clear a fault on a running instance");
 
     const optionNames = injectCmd?.options.map((o) => o.long);
     expect(optionNames).toContain("--clear");

package/src/commands/inject.ts

@@ -3,11 +3,12 @@ import type { EngineCommand } from "@miravo/shared";
 import { CONTROL_CMD_TIMEOUT_MS, MiravoError } from "@miravo/shared";
 import type { Command } from "commander";
 import { executeAdminCommand, getAdminState, resolveAdminUrl } from "../lib/admin-client.ts";
-import { parseDurationMs } from "../lib/parse.ts";
+import { parseTimeoutSeconds } from "../lib/parse.ts";
 import { faultLog, handleCommandError } from "../logger.ts";
 
 interface InjectOptions {
   readonly clear?: boolean;
+  readonly json?: boolean;
   readonly name?: string;
   readonly adminUrl?: string;
   readonly timeout?: number;
@@ -20,14 +21,19 @@ interface InjectOptions {
 export function registerInjectCommand(program: Command): void {
   program
     .command("inject [instanceId] [fault]")
-    .description("Inject or clear a fault on a running twin instance")
+    .description("Trigger or clear a fault on a running instance")
     .option("--clear", "Clear the fault instead of triggering it")
+    .option("--json", "Machine-readable JSON output")
     .option("--name <name>", "Target simulation name")
     .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
-    .option(
-      "--timeout <ms>",
-      "Admin request timeout in milliseconds (default: 5000)",
-      parseDurationMs,
+    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo inject                          Interactive mode (pick instance + fault)
+  $ miravo inject pump-001 cavitation      Trigger fault directly
+  $ miravo inject pump-001 cavitation --clear  Clear an active fault`,
     )
     .action(
       async (instanceId: string | undefined, fault: string | undefined, options: InjectOptions) => {
@@ -83,15 +89,17 @@ async function injectAction(
 
     const result = await executeAdminCommand(adminUrl, command, timeoutMs);
 
-    if (result.success) {
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (result.success) {
       faultLog.success(result.message);
     } else {
       faultLog.error(result.message);
       if (result.error) {
         faultLog.error(`Fix: ${result.error}`);
       }
-      process.exitCode = 1;
     }
+    if (!result.success) process.exitCode = 1;
   } catch (error) {
     handleCommandError(error, faultLog);
   }

package/src/commands/load.ts

@@ -0,0 +1,167 @@
+import { basename } from "node:path";
+import { isCancel, select } from "@clack/prompts";
+import type { ContentCatalog } from "@miravo/core";
+import { discoverTemplates } from "@miravo/core";
+import type { DiscoveredTemplate, EngineCommand } from "@miravo/shared";
+import { CONTROL_CMD_TIMEOUT_MS, ConfigNotFoundError, MiravoError } from "@miravo/shared";
+import type { Command } from "commander";
+import { executeAdminCommand, resolveAdminUrl } from "../lib/admin-client.ts";
+import { parsePositiveInt, parseTimeoutSeconds } from "../lib/parse.ts";
+import { isStressBenchmarkTemplate } from "../lib/template-category.ts";
+import {
+  createCatalog,
+  discoverPreferredLocalTemplates,
+  resolveTemplateIdentifier,
+} from "../lib/template-locator.ts";
+import { configLog, handleCommandError, handleCommandResult } from "../logger.ts";
+
+interface LoadOptions {
+  readonly template?: string;
+  readonly count?: number;
+  readonly json?: boolean;
+  readonly adminUrl?: string;
+  readonly timeout?: number;
+}
+
+export function registerLoadCommand(program: Command): void {
+  program
+    .command("load")
+    .description("Add instances from a template to the running simulation")
+    .option(
+      "-t, --template <id|name|path,...>",
+      "Template id, name, path, or comma-separated list (env: MIRAVO_TEMPLATE)",
+    )
+    .option(
+      "-c, --count <n>",
+      "Number of template copies to load per template (default: 1)",
+      parsePositiveInt,
+    )
+    .option("--json", "Machine-readable JSON output")
+    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
+    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo load -t smart-factory                     Load built-in template by name
+  $ miravo load -t ./extra.miravo.yaml               Load template from file
+  $ miravo load -t smart-factory,water-treatment     Load two templates at once
+  $ miravo load -t smart-factory -c 3               Load 3 copies of a template
+  $ miravo load                                      Auto-discover and load`,
+    )
+    .action(async (options: LoadOptions) => {
+      try {
+        const catalog = createCatalog();
+        const templateIdentifier = options.template ?? Bun.env["MIRAVO_TEMPLATE"];
+
+        let templatePaths: string[];
+        if (templateIdentifier !== undefined) {
+          const identifiers = templateIdentifier
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+          templatePaths = await Promise.all(
+            identifiers.map((id) => resolveTemplateIdentifier(id, catalog)),
+          );
+        } else {
+          const path = await resolveLoadTemplatePath(catalog);
+          templatePaths = [path];
+        }
+
+        const adminUrl = resolveAdminUrl(options.adminUrl);
+        const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
+
+        for (const templatePath of templatePaths) {
+          const command: EngineCommand = {
+            type: "loadTemplate",
+            templatePath,
+            count: options.count ?? 1,
+          };
+          const result = await executeAdminCommand(adminUrl, command, timeoutMs);
+          handleCommandResult(result, options.json);
+        }
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}
+
+async function resolveLoadTemplatePath(catalog: ContentCatalog): Promise<string> {
+  // 1. Auto-discover local templates (CWD + local registry)
+  const discovered = await discoverPreferredLocalTemplates(catalog);
+  if (discovered.length === 1) {
+    const first = discovered[0];
+    if (first !== undefined) {
+      configLog.info(`Found template: ${first.name} (${first.path})`);
+      return first.path;
+    }
+  }
+  if (discovered.length > 1) {
+    if (!process.stdout.isTTY || !process.stdin.isTTY) {
+      const names = discovered.map((t) => t.name).join(", ");
+      throw new MiravoError(
+        `Found ${discovered.length} templates: ${names}.`,
+        "Use '--template <name|path>' to specify which template to use.",
+      );
+    }
+    const first = discovered[0];
+    if (first !== undefined) {
+      configLog.warn(
+        `Found ${discovered.length} templates: ${discovered.map((t) => t.name).join(", ")}. Using ${first.name}. Use '--template <name|path>' to specify.`,
+      );
+      return first.path;
+    }
+  }
+
+  // 2. Fall back to built-in templates
+  const builtinTemplateDir = catalog.getBuiltinTemplatesDir();
+  let builtinTemplates: readonly DiscoveredTemplate[] = [];
+  try {
+    const all = await discoverTemplates(builtinTemplateDir);
+    builtinTemplates = all.filter((t) => !isStressBenchmarkTemplate(t.id));
+  } catch {
+    // Builtin dir may not exist in edge cases
+  }
+  if (builtinTemplates.length > 0) {
+    if (process.stdout.isTTY && process.stdin.isTTY) {
+      return pickBuiltinTemplate(builtinTemplates);
+    }
+    const selected =
+      builtinTemplates.find((t) => basename(t.path) === "smart-factory.miravo.yaml") ??
+      builtinTemplates[0];
+    if (selected !== undefined) {
+      configLog.info(`No template specified. Using built-in "${selected.name}".`);
+      configLog.info(
+        "Run 'miravo templates list' to see all options, or use --template <name|path>.",
+      );
+      return selected.path;
+    }
+  }
+
+  // 3. Nothing available
+  throw new ConfigNotFoundError(
+    "No template found. Use 'miravo templates list' to find built-ins or pass 'miravo load --template <name|path>'.",
+  );
+}
+
+async function pickBuiltinTemplate(templates: readonly DiscoveredTemplate[]): Promise<string> {
+  configLog.info("No template found in current directory.\n");
+
+  const choice = await select({
+    message: "Choose a built-in template to load:",
+    options: templates.map((t) => ({
+      value: t.path,
+      label: t.name,
+      hint: t.description ?? t.id,
+    })),
+    maxItems: 9,
+  });
+
+  if (isCancel(choice)) {
+    process.exit(0);
+  }
+
+  configLog.info("Tip: use --template <id> to skip this prompt next time.");
+
+  return choice as string;
+}

package/src/commands/logs.ts

@@ -0,0 +1,175 @@
+import type { WSMessage } from "@miravo/shared";
+import type { Command } from "commander";
+import { colors } from "consola/utils";
+import { isPidAlive, readEntry } from "../lib/daemon-registry.ts";
+import { parseNonNegativeInt } from "../lib/parse.ts";
+import { handleCommandError, writeOutput } from "../logger.ts";
+
+interface LogsOptions {
+  readonly tail?: number;
+  readonly channels?: string;
+}
+
+export function registerLogsCommand(program: Command): void {
+  program
+    .command("logs <name>")
+    .description("Stream domain events from a background simulation")
+    .option("--tail <n>", "Fetch last N events before streaming", parseNonNegativeInt)
+    .option(
+      "--channels <list>",
+      "Comma-separated channels: faults,lifecycle,instances,adapters,engine (default: all except tick)",
+    )
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo logs my-sim                     Stream live events
+  $ miravo logs my-sim --tail 50           Show last 50 events first
+  $ miravo logs my-sim --channels faults   Only fault events`,
+    )
+    .action(async (name: string, options: LogsOptions) => {
+      try {
+        await logsAction(name, options);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}
+
+async function logsAction(name: string, options: LogsOptions): Promise<void> {
+  const entry = await readEntry(name);
+  if (!entry) {
+    writeOutput(`Simulation "${name}" not found. Use 'miravo ps' to list running simulations.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!isPidAlive(entry.pid)) {
+    writeOutput(`Simulation "${name}" is not running.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const adminUrl = `http://${entry.adminHost}:${entry.adminPort}`;
+
+  // Fetch historical events if --tail is set
+  if (options.tail !== undefined && options.tail > 0) {
+    try {
+      const response = await fetch(`${adminUrl}/events?limit=${options.tail}`, {
+        signal: AbortSignal.timeout(5_000),
+      });
+      if (response.ok) {
+        const result = (await response.json()) as { events: readonly Record<string, unknown>[] };
+        for (const event of result.events) {
+          const formatted = formatLoggedEvent(event);
+          if (formatted) writeOutput(formatted);
+        }
+      }
+    } catch {
+      writeOutput("Warning: could not fetch historical events.");
+    }
+  }
+
+  // Connect WebSocket for live streaming
+  const wsUrl = `ws://${entry.adminHost}:${entry.adminPort}/ws`;
+
+  const selectedChannels = options.channels
+    ? options.channels.split(",").map((c) => c.trim())
+    : ["faults", "lifecycle", "instances", "engine", "adapters"];
+
+  const ws = new WebSocket(wsUrl);
+  let connected = false;
+  let userInitiatedClose = false;
+
+  const cleanup = (): void => {
+    userInitiatedClose = true;
+    ws.close();
+    process.exit(0);
+  };
+  process.once("SIGINT", cleanup);
+  process.once("SIGTERM", cleanup);
+
+  ws.onopen = () => {
+    connected = true;
+    ws.send(JSON.stringify({ type: "subscribe", channels: selectedChannels }));
+    writeOutput(
+      `${colors.dim("Connected to")} ${name} ${colors.dim(`(channels: ${selectedChannels.join(", ")})`)}`,
+    );
+    writeOutput(colors.dim("Waiting for events... (Ctrl+C to stop)"));
+  };
+
+  ws.onmessage = (event) => {
+    try {
+      const msg = JSON.parse(String(event.data)) as WSMessage;
+      const formatted = formatWSEvent(msg);
+      if (formatted) writeOutput(formatted);
+    } catch {
+      // Ignore parse errors
+    }
+  };
+
+  ws.onerror = () => {
+    if (!connected) {
+      writeOutput(`Failed to connect to simulation "${name}". Is it still running?`);
+      process.exit(1);
+    }
+    writeOutput(`Connection lost to simulation "${name}".`);
+  };
+
+  // Keep alive until WebSocket closes
+  await new Promise<void>((resolve) => {
+    ws.onclose = () => resolve();
+  });
+
+  if (!connected || !userInitiatedClose) {
+    process.exit(1);
+  }
+}
+
+/** Format a WebSocket message for terminal output. Returns null for tick events. */
+export function formatWSEvent(msg: WSMessage): string | null {
+  switch (msg.type) {
+    case "fault:triggered":
+      return `${colors.red("[fault:triggered]")} ${msg.instanceId} · ${msg.fault}`;
+    case "fault:cleared":
+      return `${colors.green("[fault:cleared]")} ${msg.instanceId} · ${msg.fault}`;
+    case "lifecycle:changed":
+      return `${colors.blue("[lifecycle:changed]")} ${msg.instanceId} · ${msg.from} → ${msg.to}`;
+    case "instance:created":
+      return `${colors.cyan("[instance:created]")} ${msg.id} · ${msg.assetType}`;
+    case "instance:removed":
+      return `${colors.yellow("[instance:removed]")} ${msg.id}`;
+    case "engine:state":
+      return `${colors.magenta("[engine:state]")} ${msg.from} → ${msg.to}`;
+    case "adapter:enabled":
+      return `${colors.cyan("[adapter:enabled]")} ${msg.name}`;
+    case "adapter:disabled":
+      return `${colors.yellow("[adapter:disabled]")} ${msg.name}`;
+    case "tick":
+    case "snapshot":
+    case "resync-required":
+      return null;
+    default:
+      return null;
+  }
+}
+
+function formatLoggedEvent(event: Record<string, unknown>): string | null {
+  const type = event["type"];
+  if (typeof type !== "string") return null;
+
+  switch (type) {
+    case "fault:triggered":
+      return `${colors.red("[fault:triggered]")} ${event["instanceId"]} · ${event["fault"]}`;
+    case "fault:cleared":
+      return `${colors.green("[fault:cleared]")} ${event["instanceId"]} · ${event["fault"]}`;
+    case "lifecycle:changed":
+      return `${colors.blue("[lifecycle:changed]")} ${event["instanceId"]} · ${event["from"]} → ${event["to"]}`;
+    case "instance:created":
+      return `${colors.cyan("[instance:created]")} ${event["instanceId"]} · ${event["assetType"]}`;
+    case "instance:removed":
+      return `${colors.yellow("[instance:removed]")} ${event["instanceId"]}`;
+    default:
+      return null;
+  }
+}

package/src/commands/models.test.ts

@@ -6,7 +6,7 @@ import { stripAnsi } from "consola/utils";
 import { configureLogger } from "../logger.ts";
 import { formatGeneratorSummary, formatModelInspect } from "./models.ts";
 
-configureLogger({ silent: true });
+configureLogger({ quiet: true });
 
 const modelsDir = resolve(import.meta.dir, "..", "..", "..", "content", "models");
 
@@ -138,4 +138,25 @@ describe("miravo models", () => {
 
     expect(process.exitCode).toBe(1);
   });
+
+  test("models list --dir with nonexistent path sets exit code 1", async () => {
+    const { createProgram } = await import("../index.ts");
+    const program = createProgram();
+    program.exitOverride();
+
+    try {
+      await program.parseAsync([
+        "node",
+        "miravo",
+        "models",
+        "list",
+        "--dir",
+        "/definitely-nonexistent-miravo-test-path",
+      ]);
+    } catch {
+      // Commander may throw on exitOverride
+    }
+
+    expect(process.exitCode).toBe(1);
+  });
 });

package/src/commands/models.ts

@@ -20,6 +20,12 @@ export function registerModelsCommand(program: Command): void {
     .command("list")
     .description("Discover and list available models")
     .option("--dir <path>", "Additional directory to search for models")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo models list                     List all discoverable models`,
+    )
     .action(async (options: { readonly dir?: string }) => {
       await modelsListAction(options);
     });
@@ -28,6 +34,13 @@ export function registerModelsCommand(program: Command): void {
     .command("inspect <name>")
     .description("Show detailed information about a model")
     .option("--raw", "Dump the raw YAML file to stdout")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo models inspect centrifugal-pump        Show model details
+  $ miravo models inspect centrifugal-pump --raw  Dump raw YAML`,
+    )
     .action(async (name: string, options: { readonly raw?: boolean }) => {
       await modelsInspectAction(name, options);
     });
@@ -68,6 +81,7 @@ async function modelsListAction(options: { readonly dir?: string }): Promise<voi
       const resolvedDir = resolve(options.dir);
       if (!existsSync(resolvedDir)) {
         configLog.error(`Directory not found: ${resolvedDir}`);
+        process.exitCode = 1;
         return;
       }
       const { discoverModels } = await import("@miravo/core");

package/src/commands/pause.ts

@@ -0,0 +1,67 @@
+import type { EngineCommand } from "@miravo/shared";
+import { CONTROL_CMD_TIMEOUT_MS } from "@miravo/shared";
+import type { Command } from "commander";
+import { executeAdminCommand, resolveAdminUrl } from "../lib/admin-client.ts";
+import { parseTimeoutSeconds } from "../lib/parse.ts";
+import { handleCommandError, handleCommandResult } from "../logger.ts";
+
+interface PauseResumeOptions {
+  readonly json?: boolean;
+  readonly adminUrl?: string;
+  readonly timeout?: number;
+}
+
+export function registerPauseCommand(program: Command): void {
+  program
+    .command("pause")
+    .description("Pause the running simulation")
+    .option("--json", "Machine-readable JSON output")
+    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
+    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo pause                           Pause the simulation`,
+    )
+    .action(async (options: PauseResumeOptions) => {
+      try {
+        await sendSimpleCommand("pause", options);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}
+
+export function registerResumeCommand(program: Command): void {
+  program
+    .command("resume")
+    .description("Resume a paused simulation")
+    .option("--json", "Machine-readable JSON output")
+    .option("--admin-url <url>", "Miravo admin server URL (env: MIRAVO_ADMIN_URL)")
+    .option("--timeout <seconds>", "Timeout in seconds (default: 5)", parseTimeoutSeconds)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  $ miravo resume                          Resume a paused simulation`,
+    )
+    .action(async (options: PauseResumeOptions) => {
+      try {
+        await sendSimpleCommand("resume", options);
+      } catch (error) {
+        handleCommandError(error);
+      }
+    });
+}
+
+async function sendSimpleCommand(
+  type: "pause" | "resume",
+  options: PauseResumeOptions,
+): Promise<void> {
+  const adminUrl = resolveAdminUrl(options.adminUrl);
+  const timeoutMs = options.timeout ?? CONTROL_CMD_TIMEOUT_MS;
+  const command: EngineCommand = { type };
+  const result = await executeAdminCommand(adminUrl, command, timeoutMs);
+  handleCommandResult(result, options.json);
+}