@ricsam/r5dctl 0.0.22 → 0.0.23

package/README.md

@@ -67,8 +67,12 @@ r5dctl -s <session-id> prompt --mode plan --model max "..."
 r5dctl -s <session-id> answer-questions -a1 "Recipe Collection" -a2 "Both Manual & AI"
 r5dctl -s <session-id> apply-required-envs -e backend/KEY=value -e frontend/KEY=value
 
+r5dctl -p <project> -b <branch> shell
+r5dctl -p <project> -b <branch> shell -c "bun test"
 ```
 
+`shell` connects to the same live worker PTY as the web Shell tab. Without `-c` it attaches the local terminal interactively. With `-c`/`--command`, it runs the supplied shell expression, streams combined PTY output, and exits with the remote command's status. Because command output uses a PTY, stdout and stderr are combined and programs may emit colors or other terminal control sequences.
+
 `get envs` reports names and whether values are set, but never prints the values. Prefer `--from-env-file` for bulk imports so secret values do not appear in shell arguments or history. Dotenv imports target backend envs by default; use `--target frontend` when needed. Empty dotenv values are skipped unless `--include-empty` is passed, and `--only-missing` preserves values that are already set.
 
 Conversation output is human-readable by default and excludes both the system prompt and tool definitions. `--raw` keeps the transcript layout but renders structured message and tool parts as JSON, `--tools` includes the provider-shaped tool definitions, and `--system` includes system prompt messages. The global `--json` flag remains separate and prints the complete API response envelope.

package/dist/cjs/cli.cjs

@@ -37,6 +37,7 @@ __export(cli_exports, {
   parseGlobalArgs: () => parseGlobalArgs,
   parsePromptArgs: () => parsePromptArgs,
   parseSetEnvArgs: () => parseSetEnvArgs,
+  parseShellArgs: () => parseShellArgs,
   readDotenvFile: () => readDotenvFile,
   renderConversationResponse: () => renderConversationResponse,
   resolveCommandExecution: () => resolveCommandExecution,
@@ -51,6 +52,7 @@ var import_node_child_process = require("node:child_process");
 var import_promises = require("node:timers/promises");
 var import_dotenv = require("dotenv");
 var import_r5d_api = require("@ricsam/r5d-api");
+var import_shell = require("./shell.cjs");
 const CHAT_MODES = /* @__PURE__ */ new Set([
   "ask",
   "plan",
@@ -83,12 +85,21 @@ const CLI_ONLY_HELP_ENTRIES = [
     section: "auth",
     usage: "auth login [--no-open]",
     description: "Start the browser login flow."
+  },
+  {
+    section: "shell",
+    usage: "-p <project> -b <branch> shell [-c <command>]",
+    description: "Open an interactive worker shell or run one command through a PTY."
   }
 ];
 const CLI_ONLY_COMMAND_HELP = [
   {
     path: ["auth", "login"],
     usage: "auth login [--no-open]"
+  },
+  {
+    path: ["shell"],
+    usage: "-p <project> -b <branch> shell [-c <command>]"
   }
 ];
 const SHARED_HELP_ENTRIES = [
@@ -170,13 +181,14 @@ const SHARED_HELP_ENTRIES = [
   { section: "merges", usage: "-p <project> continue-merge <target-branch>", description: "Commit a resolved merge." },
   { section: "merges", usage: "-p <project> abort-merge <target-branch>", description: "Abort an in-progress merge." }
 ];
-const HELP_SECTION_ORDER = ["auth", "projects", "branches", "envs", "sessions", "agents", "merges"];
+const HELP_SECTION_ORDER = ["auth", "projects", "branches", "envs", "sessions", "shell", "agents", "merges"];
 const HELP_SECTION_TITLES = {
   auth: "Auth",
   projects: "Projects",
   branches: "Branches",
   envs: "Environment variables",
   sessions: "Sessions",
+  shell: "Shell",
   agents: "Agents",
   merges: "Merges"
 };
@@ -725,6 +737,33 @@ function parsePromptArgs(args) {
     message
   };
 }
+function parseShellArgs(args) {
+  let command;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) {
+      continue;
+    }
+    if (arg === "-c" || arg === "--command") {
+      if (command !== void 0) {
+        throw new Error("Use only one -c/--command value");
+      }
+      command = requireValue(args[index + 1], `Missing value for ${arg}`);
+      index += 1;
+      continue;
+    }
+    const inlineCommand = parseLongOptionWithEquals(arg, "--command");
+    if (inlineCommand !== void 0) {
+      if (command !== void 0) {
+        throw new Error("Use only one -c/--command value");
+      }
+      command = requireValue(inlineCommand, "Missing value for --command");
+      continue;
+    }
+    throw new Error(arg.startsWith("-") ? `Unknown shell flag: ${arg}` : `Unexpected shell value: ${arg}`);
+  }
+  return command === void 0 ? {} : { command };
+}
 async function openInBrowser(url) {
   if (process.platform === "darwin") {
     (0, import_node_child_process.spawn)("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -1573,6 +1612,21 @@ function resolveCommandExecution(options, rest) {
       pluginArgs: ["conversation", sessionId, ...commandArgs]
     };
   }
+  if (command === "shell") {
+    if (!options.project) {
+      throw new Error("--project/-p is required for `shell`");
+    }
+    if (!options.branch) {
+      throw new Error("--branch/-b is required for `shell`");
+    }
+    if (options.json) {
+      throw new Error("--json is not supported for `shell`");
+    }
+    return {
+      kind: "shell",
+      ...parseShellArgs(commandArgs)
+    };
+  }
   if (command === "prompt") {
     const sessionId = options.session;
     if (!sessionId) {
@@ -1696,31 +1750,43 @@ async function runCommand(argv) {
   const { options, rest } = parseGlobalArgs(argv);
   if (options.version) {
     printVersion();
-    return;
+    return 0;
   }
   if (options.help || rest.length === 0) {
     printHelp();
-    return;
+    return 0;
   }
   const config = parseConfig(options.configPath);
-  const client = new import_r5d_api.R5dctlClient(resolveClientOptions(options, config));
+  const clientOptions = resolveClientOptions(options, config);
+  const client = new import_r5d_api.R5dctlClient(clientOptions);
   const execution = resolveCommandExecution(options, rest);
   if (execution.kind === "auth-login") {
     await handleAuthLogin(client, options, execution.commandArgs, config);
-    return;
+    return 0;
   }
   if (execution.kind === "auth-api-key-create") {
     await handleAuthApiKeyCreate(client, options, config, execution.commandArgs);
-    return;
+    return 0;
   }
   if (execution.kind === "cli-help") {
     process.stdout.write(execution.text);
-    return;
+    return 0;
+  }
+  if (execution.kind === "shell") {
+    const project = await client.projects.describe(options.project);
+    return await (0, import_shell.runR5dctlShell)({
+      baseUrl: clientOptions.baseUrl ?? "https://r5d.dev",
+      credential: clientOptions.token ?? clientOptions.apiKey ?? "",
+      projectId: project.id,
+      branchName: options.branch,
+      command: execution.command
+    });
   }
   await executeR5dctlCommand(client, options.json, execution.pluginArgs);
   if (execution.clearAuthOnSuccess) {
     writeConfig(options.configPath, clearAuthFromConfig(config, options));
   }
+  return 0;
 }
 function extractApiErrorMessage(error) {
   if (typeof error.body === "object" && error.body !== null) {
@@ -1733,8 +1799,7 @@ function extractApiErrorMessage(error) {
 }
 async function runR5dctlCli(argv) {
   try {
-    await runCommand(argv);
-    return 0;
+    return await runCommand(argv);
   } catch (error) {
     if (error instanceof import_r5d_api.R5dctlApiError) {
       process.stderr.write(`${extractApiErrorMessage(error)}
@@ -1749,7 +1814,7 @@ async function runR5dctlCli(argv) {
 async function main(argv = process.argv.slice(2)) {
   const exitCode = await runR5dctlCli(argv);
   if (exitCode !== 0) {
-    process.exit(exitCode);
+    process.exitCode = exitCode;
   }
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -1763,6 +1828,7 @@ async function main(argv = process.argv.slice(2)) {
   parseGlobalArgs,
   parsePromptArgs,
   parseSetEnvArgs,
+  parseShellArgs,
   readDotenvFile,
   renderConversationResponse,
   resolveCommandExecution,

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "type": "commonjs"
 }

package/dist/cjs/shell.cjs

@@ -0,0 +1,245 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var shell_exports = {};
+__export(shell_exports, {
+  createShellWebSocketUrl: () => createShellWebSocketUrl,
+  runR5dctlShell: () => runR5dctlShell
+});
+module.exports = __toCommonJS(shell_exports);
+var import_ws = __toESM(require("ws"), 1);
+function clampTerminalSize(value, fallback) {
+  if (!Number.isFinite(value) || (value ?? 0) <= 0) {
+    return fallback;
+  }
+  return Math.max(1, Math.min(Math.floor(value), 500));
+}
+function createShellWebSocketUrl(baseUrl) {
+  const url = new URL("/ws", baseUrl);
+  if (url.protocol === "https:") {
+    url.protocol = "wss:";
+  } else if (url.protocol === "http:") {
+    url.protocol = "ws:";
+  } else {
+    throw new Error(`Unsupported r5d base URL protocol: ${url.protocol}`);
+  }
+  return url.toString();
+}
+function decodeMessage(data) {
+  if (typeof data === "string") {
+    return data;
+  }
+  if (Buffer.isBuffer(data)) {
+    return data.toString("utf8");
+  }
+  if (data instanceof ArrayBuffer) {
+    return Buffer.from(data).toString("utf8");
+  }
+  if (ArrayBuffer.isView(data)) {
+    return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("utf8");
+  }
+  if (Array.isArray(data)) {
+    return Buffer.concat(data).toString("utf8");
+  }
+  return String(data);
+}
+async function runR5dctlShell(options) {
+  const stdin = options.stdin ?? process.stdin;
+  const stdout = options.stdout ?? process.stdout;
+  const signalTarget = options.signalTarget ?? process;
+  const interactive = options.command === void 0;
+  if (interactive && !stdin.isTTY) {
+    throw new Error("Interactive shell requires a TTY. Use `shell -c <command>` for non-interactive use.");
+  }
+  if (!options.credential) {
+    throw new Error("Authentication required. Run `r5dctl auth login` or provide a token or API key.");
+  }
+  const createWebSocket = options.createWebSocket ?? ((url, clientOptions) => new import_ws.default(url, clientOptions));
+  const socket = createWebSocket(createShellWebSocketUrl(options.baseUrl), {
+    headers: {
+      Authorization: `Bearer ${options.credential}`
+    }
+  });
+  return await new Promise((resolve, reject) => {
+    let ptyId;
+    let openRequested = false;
+    let settled = false;
+    let inputAttached = false;
+    const priorRawMode = stdin.isRaw ?? false;
+    const send = (message) => {
+      if (socket.readyState !== import_ws.default.OPEN) {
+        return;
+      }
+      socket.send(JSON.stringify(message));
+    };
+    const sendResize = () => {
+      if (!ptyId) {
+        return;
+      }
+      send({
+        type: "shell_pty_resize",
+        ptyId,
+        cols: clampTerminalSize(stdout.columns, 80),
+        rows: clampTerminalSize(stdout.rows, 24)
+      });
+    };
+    const onInput = (chunk) => {
+      if (ptyId) {
+        send({ type: "shell_pty_input", ptyId, data: Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk });
+      }
+    };
+    const onInputEnd = () => {
+      if (!interactive && ptyId) {
+        send({ type: "shell_pty_input", ptyId, data: "" });
+      }
+    };
+    const onSigint = () => {
+      if (ptyId) {
+        send({ type: "shell_pty_input", ptyId, data: "" });
+      }
+    };
+    const onSigterm = () => {
+      if (ptyId) {
+        send({ type: "shell_pty_close", ptyId });
+        ptyId = void 0;
+      }
+      finish({ exitCode: 143 });
+    };
+    const cleanup = () => {
+      socket.off("message", onMessage);
+      socket.off("error", onSocketError);
+      socket.off("close", onSocketClose);
+      if (inputAttached) {
+        stdin.off("data", onInput);
+        stdin.off("end", onInputEnd);
+      }
+      signalTarget.off("SIGWINCH", sendResize);
+      signalTarget.off("SIGINT", onSigint);
+      signalTarget.off("SIGTERM", onSigterm);
+      if (stdin.isTTY && stdin.setRawMode) {
+        stdin.setRawMode(priorRawMode);
+      }
+    };
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      if (socket.readyState === import_ws.default.OPEN || socket.readyState === import_ws.default.CONNECTING) {
+        socket.close(1e3, "r5dctl shell finished");
+      }
+      if ("error" in result) {
+        reject(result.error);
+      } else {
+        resolve(result.exitCode);
+      }
+    };
+    function attachInput() {
+      if (inputAttached) {
+        return;
+      }
+      inputAttached = true;
+      if (stdin.isTTY && stdin.setRawMode) {
+        stdin.setRawMode(true);
+      }
+      stdin.on("data", onInput);
+      stdin.on("end", onInputEnd);
+      signalTarget.on("SIGWINCH", sendResize);
+      signalTarget.on("SIGTERM", onSigterm);
+      if (!stdin.isTTY) {
+        signalTarget.on("SIGINT", onSigint);
+      }
+    }
+    function onMessage(data) {
+      let message;
+      try {
+        const parsed = JSON.parse(decodeMessage(data));
+        if (!parsed || typeof parsed !== "object" || !("type" in parsed)) {
+          throw new Error("Invalid message");
+        }
+        message = parsed;
+      } catch {
+        finish({ error: new Error("Received an invalid response from r5d.dev") });
+        return;
+      }
+      if (message.type === "connected") {
+        if (!openRequested) {
+          openRequested = true;
+          send({
+            type: "shell_pty_open",
+            projectId: options.projectId,
+            branchName: options.branchName,
+            cols: clampTerminalSize(stdout.columns, 80),
+            rows: clampTerminalSize(stdout.rows, 24),
+            ...options.command === void 0 ? {} : { command: options.command }
+          });
+        }
+        return;
+      }
+      if (message.type === "shell_pty_opened") {
+        ptyId = message.ptyId;
+        attachInput();
+        return;
+      }
+      if (message.type === "shell_pty_output") {
+        if (message.ptyId === ptyId) {
+          stdout.write(message.data);
+        }
+        return;
+      }
+      if (message.type === "shell_pty_exit") {
+        if (message.ptyId === ptyId) {
+          ptyId = void 0;
+          finish({ exitCode: message.exitCode });
+        }
+        return;
+      }
+      if (message.type === "shell_pty_error" && (!message.ptyId || message.ptyId === ptyId)) {
+        finish({ error: new Error(message.message) });
+      }
+    }
+    function onSocketError(error) {
+      finish({ error: new Error(`r5d.dev shell connection failed: ${error.message}`) });
+    }
+    function onSocketClose(code, reason) {
+      if (!settled) {
+        const suffix = reason.length > 0 ? `: ${reason.toString("utf8")}` : "";
+        finish({ error: new Error(`r5d.dev shell connection closed (${code})${suffix}`) });
+      }
+    }
+    socket.on("message", onMessage);
+    socket.on("error", onSocketError);
+    socket.on("close", onSocketClose);
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createShellWebSocketUrl,
+  runR5dctlShell
+});

package/dist/mjs/cli.mjs

@@ -8,6 +8,7 @@ import {
   R5dctlApiError,
   R5dctlClient
 } from "@ricsam/r5d-api";
+import { runR5dctlShell } from "./shell.mjs";
 const CHAT_MODES = /* @__PURE__ */ new Set([
   "ask",
   "plan",
@@ -40,12 +41,21 @@ const CLI_ONLY_HELP_ENTRIES = [
     section: "auth",
     usage: "auth login [--no-open]",
     description: "Start the browser login flow."
+  },
+  {
+    section: "shell",
+    usage: "-p <project> -b <branch> shell [-c <command>]",
+    description: "Open an interactive worker shell or run one command through a PTY."
   }
 ];
 const CLI_ONLY_COMMAND_HELP = [
   {
     path: ["auth", "login"],
     usage: "auth login [--no-open]"
+  },
+  {
+    path: ["shell"],
+    usage: "-p <project> -b <branch> shell [-c <command>]"
   }
 ];
 const SHARED_HELP_ENTRIES = [
@@ -127,13 +137,14 @@ const SHARED_HELP_ENTRIES = [
   { section: "merges", usage: "-p <project> continue-merge <target-branch>", description: "Commit a resolved merge." },
   { section: "merges", usage: "-p <project> abort-merge <target-branch>", description: "Abort an in-progress merge." }
 ];
-const HELP_SECTION_ORDER = ["auth", "projects", "branches", "envs", "sessions", "agents", "merges"];
+const HELP_SECTION_ORDER = ["auth", "projects", "branches", "envs", "sessions", "shell", "agents", "merges"];
 const HELP_SECTION_TITLES = {
   auth: "Auth",
   projects: "Projects",
   branches: "Branches",
   envs: "Environment variables",
   sessions: "Sessions",
+  shell: "Shell",
   agents: "Agents",
   merges: "Merges"
 };
@@ -682,6 +693,33 @@ function parsePromptArgs(args) {
     message
   };
 }
+function parseShellArgs(args) {
+  let command;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) {
+      continue;
+    }
+    if (arg === "-c" || arg === "--command") {
+      if (command !== void 0) {
+        throw new Error("Use only one -c/--command value");
+      }
+      command = requireValue(args[index + 1], `Missing value for ${arg}`);
+      index += 1;
+      continue;
+    }
+    const inlineCommand = parseLongOptionWithEquals(arg, "--command");
+    if (inlineCommand !== void 0) {
+      if (command !== void 0) {
+        throw new Error("Use only one -c/--command value");
+      }
+      command = requireValue(inlineCommand, "Missing value for --command");
+      continue;
+    }
+    throw new Error(arg.startsWith("-") ? `Unknown shell flag: ${arg}` : `Unexpected shell value: ${arg}`);
+  }
+  return command === void 0 ? {} : { command };
+}
 async function openInBrowser(url) {
   if (process.platform === "darwin") {
     spawn("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -1530,6 +1568,21 @@ function resolveCommandExecution(options, rest) {
       pluginArgs: ["conversation", sessionId, ...commandArgs]
     };
   }
+  if (command === "shell") {
+    if (!options.project) {
+      throw new Error("--project/-p is required for `shell`");
+    }
+    if (!options.branch) {
+      throw new Error("--branch/-b is required for `shell`");
+    }
+    if (options.json) {
+      throw new Error("--json is not supported for `shell`");
+    }
+    return {
+      kind: "shell",
+      ...parseShellArgs(commandArgs)
+    };
+  }
   if (command === "prompt") {
     const sessionId = options.session;
     if (!sessionId) {
@@ -1653,31 +1706,43 @@ async function runCommand(argv) {
   const { options, rest } = parseGlobalArgs(argv);
   if (options.version) {
     printVersion();
-    return;
+    return 0;
   }
   if (options.help || rest.length === 0) {
     printHelp();
-    return;
+    return 0;
   }
   const config = parseConfig(options.configPath);
-  const client = new R5dctlClient(resolveClientOptions(options, config));
+  const clientOptions = resolveClientOptions(options, config);
+  const client = new R5dctlClient(clientOptions);
   const execution = resolveCommandExecution(options, rest);
   if (execution.kind === "auth-login") {
     await handleAuthLogin(client, options, execution.commandArgs, config);
-    return;
+    return 0;
   }
   if (execution.kind === "auth-api-key-create") {
     await handleAuthApiKeyCreate(client, options, config, execution.commandArgs);
-    return;
+    return 0;
   }
   if (execution.kind === "cli-help") {
     process.stdout.write(execution.text);
-    return;
+    return 0;
+  }
+  if (execution.kind === "shell") {
+    const project = await client.projects.describe(options.project);
+    return await runR5dctlShell({
+      baseUrl: clientOptions.baseUrl ?? "https://r5d.dev",
+      credential: clientOptions.token ?? clientOptions.apiKey ?? "",
+      projectId: project.id,
+      branchName: options.branch,
+      command: execution.command
+    });
   }
   await executeR5dctlCommand(client, options.json, execution.pluginArgs);
   if (execution.clearAuthOnSuccess) {
     writeConfig(options.configPath, clearAuthFromConfig(config, options));
   }
+  return 0;
 }
 function extractApiErrorMessage(error) {
   if (typeof error.body === "object" && error.body !== null) {
@@ -1690,8 +1755,7 @@ function extractApiErrorMessage(error) {
 }
 async function runR5dctlCli(argv) {
   try {
-    await runCommand(argv);
-    return 0;
+    return await runCommand(argv);
   } catch (error) {
     if (error instanceof R5dctlApiError) {
       process.stderr.write(`${extractApiErrorMessage(error)}
@@ -1706,7 +1770,7 @@ async function runR5dctlCli(argv) {
 async function main(argv = process.argv.slice(2)) {
   const exitCode = await runR5dctlCli(argv);
   if (exitCode !== 0) {
-    process.exit(exitCode);
+    process.exitCode = exitCode;
   }
 }
 export {
@@ -1719,6 +1783,7 @@ export {
   parseGlobalArgs,
   parsePromptArgs,
   parseSetEnvArgs,
+  parseShellArgs,
   readDotenvFile,
   renderConversationResponse,
   resolveCommandExecution,

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "type": "module"
 }

package/dist/mjs/shell.mjs

@@ -0,0 +1,210 @@
+import WebSocket, {} from "ws";
+function clampTerminalSize(value, fallback) {
+  if (!Number.isFinite(value) || (value ?? 0) <= 0) {
+    return fallback;
+  }
+  return Math.max(1, Math.min(Math.floor(value), 500));
+}
+function createShellWebSocketUrl(baseUrl) {
+  const url = new URL("/ws", baseUrl);
+  if (url.protocol === "https:") {
+    url.protocol = "wss:";
+  } else if (url.protocol === "http:") {
+    url.protocol = "ws:";
+  } else {
+    throw new Error(`Unsupported r5d base URL protocol: ${url.protocol}`);
+  }
+  return url.toString();
+}
+function decodeMessage(data) {
+  if (typeof data === "string") {
+    return data;
+  }
+  if (Buffer.isBuffer(data)) {
+    return data.toString("utf8");
+  }
+  if (data instanceof ArrayBuffer) {
+    return Buffer.from(data).toString("utf8");
+  }
+  if (ArrayBuffer.isView(data)) {
+    return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("utf8");
+  }
+  if (Array.isArray(data)) {
+    return Buffer.concat(data).toString("utf8");
+  }
+  return String(data);
+}
+async function runR5dctlShell(options) {
+  const stdin = options.stdin ?? process.stdin;
+  const stdout = options.stdout ?? process.stdout;
+  const signalTarget = options.signalTarget ?? process;
+  const interactive = options.command === void 0;
+  if (interactive && !stdin.isTTY) {
+    throw new Error("Interactive shell requires a TTY. Use `shell -c <command>` for non-interactive use.");
+  }
+  if (!options.credential) {
+    throw new Error("Authentication required. Run `r5dctl auth login` or provide a token or API key.");
+  }
+  const createWebSocket = options.createWebSocket ?? ((url, clientOptions) => new WebSocket(url, clientOptions));
+  const socket = createWebSocket(createShellWebSocketUrl(options.baseUrl), {
+    headers: {
+      Authorization: `Bearer ${options.credential}`
+    }
+  });
+  return await new Promise((resolve, reject) => {
+    let ptyId;
+    let openRequested = false;
+    let settled = false;
+    let inputAttached = false;
+    const priorRawMode = stdin.isRaw ?? false;
+    const send = (message) => {
+      if (socket.readyState !== WebSocket.OPEN) {
+        return;
+      }
+      socket.send(JSON.stringify(message));
+    };
+    const sendResize = () => {
+      if (!ptyId) {
+        return;
+      }
+      send({
+        type: "shell_pty_resize",
+        ptyId,
+        cols: clampTerminalSize(stdout.columns, 80),
+        rows: clampTerminalSize(stdout.rows, 24)
+      });
+    };
+    const onInput = (chunk) => {
+      if (ptyId) {
+        send({ type: "shell_pty_input", ptyId, data: Buffer.isBuffer(chunk) ? chunk.toString("utf8") : chunk });
+      }
+    };
+    const onInputEnd = () => {
+      if (!interactive && ptyId) {
+        send({ type: "shell_pty_input", ptyId, data: "" });
+      }
+    };
+    const onSigint = () => {
+      if (ptyId) {
+        send({ type: "shell_pty_input", ptyId, data: "" });
+      }
+    };
+    const onSigterm = () => {
+      if (ptyId) {
+        send({ type: "shell_pty_close", ptyId });
+        ptyId = void 0;
+      }
+      finish({ exitCode: 143 });
+    };
+    const cleanup = () => {
+      socket.off("message", onMessage);
+      socket.off("error", onSocketError);
+      socket.off("close", onSocketClose);
+      if (inputAttached) {
+        stdin.off("data", onInput);
+        stdin.off("end", onInputEnd);
+      }
+      signalTarget.off("SIGWINCH", sendResize);
+      signalTarget.off("SIGINT", onSigint);
+      signalTarget.off("SIGTERM", onSigterm);
+      if (stdin.isTTY && stdin.setRawMode) {
+        stdin.setRawMode(priorRawMode);
+      }
+    };
+    const finish = (result) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+        socket.close(1e3, "r5dctl shell finished");
+      }
+      if ("error" in result) {
+        reject(result.error);
+      } else {
+        resolve(result.exitCode);
+      }
+    };
+    function attachInput() {
+      if (inputAttached) {
+        return;
+      }
+      inputAttached = true;
+      if (stdin.isTTY && stdin.setRawMode) {
+        stdin.setRawMode(true);
+      }
+      stdin.on("data", onInput);
+      stdin.on("end", onInputEnd);
+      signalTarget.on("SIGWINCH", sendResize);
+      signalTarget.on("SIGTERM", onSigterm);
+      if (!stdin.isTTY) {
+        signalTarget.on("SIGINT", onSigint);
+      }
+    }
+    function onMessage(data) {
+      let message;
+      try {
+        const parsed = JSON.parse(decodeMessage(data));
+        if (!parsed || typeof parsed !== "object" || !("type" in parsed)) {
+          throw new Error("Invalid message");
+        }
+        message = parsed;
+      } catch {
+        finish({ error: new Error("Received an invalid response from r5d.dev") });
+        return;
+      }
+      if (message.type === "connected") {
+        if (!openRequested) {
+          openRequested = true;
+          send({
+            type: "shell_pty_open",
+            projectId: options.projectId,
+            branchName: options.branchName,
+            cols: clampTerminalSize(stdout.columns, 80),
+            rows: clampTerminalSize(stdout.rows, 24),
+            ...options.command === void 0 ? {} : { command: options.command }
+          });
+        }
+        return;
+      }
+      if (message.type === "shell_pty_opened") {
+        ptyId = message.ptyId;
+        attachInput();
+        return;
+      }
+      if (message.type === "shell_pty_output") {
+        if (message.ptyId === ptyId) {
+          stdout.write(message.data);
+        }
+        return;
+      }
+      if (message.type === "shell_pty_exit") {
+        if (message.ptyId === ptyId) {
+          ptyId = void 0;
+          finish({ exitCode: message.exitCode });
+        }
+        return;
+      }
+      if (message.type === "shell_pty_error" && (!message.ptyId || message.ptyId === ptyId)) {
+        finish({ error: new Error(message.message) });
+      }
+    }
+    function onSocketError(error) {
+      finish({ error: new Error(`r5d.dev shell connection failed: ${error.message}`) });
+    }
+    function onSocketClose(code, reason) {
+      if (!settled) {
+        const suffix = reason.length > 0 ? `: ${reason.toString("utf8")}` : "";
+        finish({ error: new Error(`r5d.dev shell connection closed (${code})${suffix}`) });
+      }
+    }
+    socket.on("message", onMessage);
+    socket.on("error", onSocketError);
+    socket.on("close", onSocketClose);
+  });
+}
+export {
+  createShellWebSocketUrl,
+  runR5dctlShell
+};

package/dist/types/cli.d.ts

@@ -26,6 +26,9 @@ type CommandExecutionPlan = {
 } | {
     kind: "auth-api-key-create";
     commandArgs: string[];
+} | {
+    kind: "shell";
+    command?: string;
 } | {
     kind: "cli-help";
     text: string;
@@ -55,6 +58,9 @@ export declare function parsePromptArgs(args: string[]): {
     model: ModelTier;
     message: string;
 };
+export declare function parseShellArgs(args: string[]): {
+    command?: string;
+};
 export type EnvSummaryData = Partial<Record<R5dctlEnvTarget, Record<string, {
     optional: boolean;
     description: string;

package/dist/types/shell.d.ts

@@ -0,0 +1,26 @@
+import type { Readable, Writable } from "node:stream";
+import WebSocket, { type ClientOptions } from "ws";
+type ShellInput = Readable & {
+    isTTY?: boolean;
+    isRaw?: boolean;
+    setRawMode?: (mode: boolean) => unknown;
+};
+type ShellOutput = Writable & {
+    columns?: number;
+    rows?: number;
+};
+export type ShellWebSocket = Pick<WebSocket, "readyState" | "send" | "close" | "on" | "off">;
+export type RunR5dctlShellOptions = {
+    baseUrl: string;
+    credential: string;
+    projectId: string;
+    branchName: string;
+    command?: string;
+    stdin?: ShellInput;
+    stdout?: ShellOutput;
+    signalTarget?: Pick<NodeJS.Process, "on" | "off">;
+    createWebSocket?: (url: string, options: ClientOptions) => ShellWebSocket;
+};
+export declare function createShellWebSocketUrl(baseUrl: string): string;
+export declare function runR5dctlShell(options: RunR5dctlShellOptions): Promise<number>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5dctl",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "type": "module",
   "main": "./dist/cjs/cli.cjs",
   "module": "./dist/mjs/cli.mjs",
@@ -26,8 +26,9 @@
     "r5dctl": "dist/cjs/main.cjs"
   },
   "dependencies": {
-    "@ricsam/r5d-api": "^0.0.22",
-    "dotenv": "^17"
+    "@ricsam/r5d-api": "^0.0.23",
+    "dotenv": "^17",
+    "ws": "^8.18.3"
   },
   "files": [
     "dist",