@ricsam/r5dctl 0.0.22 → 0.0.24

package/README.md

@@ -51,7 +51,7 @@ r5dctl -p <project> get branches
 r5dctl -p <project> describe branch <branch>
 r5dctl -p <project> -b <branch> get envs
 r5dctl -p <project> -b <branch> set envs --from-env-file ~/.env --only-missing
-r5dctl -p <project> -b <branch> set envs -e backend/API_KEY=value --description "API credential"
+r5dctl -p <project> -b <branch> set envs -e API_KEY=value --description "API credential"
 r5dctl -p <project> get sessions --branch <branch>
 r5dctl -p <project> create session -b <branch> --name "Spec session"
 r5dctl describe session <session-id>
@@ -65,11 +65,22 @@ r5dctl -s <session-id> conversation --system           # include system prompt m
 r5dctl -s <session-id> conversation --raw --tools --system  # exact raw agent request transcript
 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 -s <session-id> apply-required-envs -e KEY=value
 
+r5dctl -p <project> -b <branch> shell
+r5dctl -p <project> -b <branch> shell -c "bun test"
+
+r5dctl ps list
+r5dctl -p <project> -b <branch> ps list --worker <label>
+r5dctl -s <session-id> ps list --json
+r5dctl ps stop <run-id>
 ```
 
-`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.
+`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.
+
+`ps list` shows active long-running commands managed by r5d. It does not expose the worker host's general OS process table or interactive PTYs. Global project, branch, and session options filter the list, while `--worker` selects a worker label. `ps stop` sends `SIGTERM` to the selected run. Inside an r5d-provided worker shell, the temporary credential can only list and stop runs on that shell's worker.
+
+`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. 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

@@ -28,6 +28,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var cli_exports = {};
 __export(cli_exports, {
+  formatProcessAge: () => formatProcessAge,
   getCliHelpText: () => getCliHelpText,
   getR5dctlVersion: () => getR5dctlVersion,
   main: () => main,
@@ -36,9 +37,12 @@ __export(cli_exports, {
   parseEnvFlags: () => parseEnvFlags,
   parseGlobalArgs: () => parseGlobalArgs,
   parsePromptArgs: () => parsePromptArgs,
+  parsePsListArgs: () => parsePsListArgs,
   parseSetEnvArgs: () => parseSetEnvArgs,
+  parseShellArgs: () => parseShellArgs,
   readDotenvFile: () => readDotenvFile,
   renderConversationResponse: () => renderConversationResponse,
+  renderProcessList: () => renderProcessList,
   resolveCommandExecution: () => resolveCommandExecution,
   runR5dctlCli: () => runR5dctlCli,
   summarizeEnvData: () => summarizeEnvData
@@ -51,6 +55,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,14 +88,32 @@ 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 PS_HELP_TEXT = [
+  "Usage:",
+  "  r5dctl ps list [--worker <label>]",
+  "  r5dctl ps stop <run-id>",
+  "",
+  "List or gracefully stop active r5d-managed worker processes.",
+  "Use -p/--project, -b/--branch, or -s/--session to filter ps list.",
+  ""
+].join("\n");
 const SHARED_HELP_ENTRIES = [
   { section: "auth", usage: "auth status", description: "Show the current authenticated user and credential source." },
   { section: "auth", usage: "auth logout", description: "Revoke the current credential and clear saved auth." },
@@ -114,12 +137,12 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "envs",
-    usage: "-p <project> -b <branch> set envs --from-env-file <path> [--target <backend|frontend>] [--only-missing]",
+    usage: "-p <project> -b <branch> set envs --from-env-file <path> [--only-missing]",
     description: "Securely import branch envs from a dotenv file without putting values in command arguments."
   },
   {
     section: "envs",
-    usage: "-p <project> -b <branch> set envs -e backend/KEY=value [--description <text>] [--only-missing]",
+    usage: "-p <project> -b <branch> set envs -e KEY=value [--description <text>] [--only-missing]",
     description: "Set one or more branch envs directly."
   },
   {
@@ -152,9 +175,15 @@ const SHARED_HELP_ENTRIES = [
   },
   {
     section: "sessions",
-    usage: "-s <session-id> apply-required-envs -e backend/KEY=value -e frontend/KEY=value",
-    description: "Apply required backend or frontend env values."
+    usage: "-s <session-id> apply-required-envs -e KEY=value",
+    description: "Apply required environment variable values."
+  },
+  {
+    section: "processes",
+    usage: "ps list [--worker <label>]",
+    description: "List active r5d-managed worker processes; global project, branch, and session filters apply."
   },
+  { section: "processes", usage: "ps stop <run-id>", description: "Gracefully stop an active process with SIGTERM." },
   {
     section: "agents",
     usage: '-p <project> start-agent <src-branch> <agent-type> "<prompt>"',
@@ -170,13 +199,25 @@ 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",
+  "processes",
+  "shell",
+  "agents",
+  "merges"
+];
 const HELP_SECTION_TITLES = {
   auth: "Auth",
   projects: "Projects",
   branches: "Branches",
   envs: "Environment variables",
   sessions: "Sessions",
+  processes: "Processes",
+  shell: "Shell",
   agents: "Agents",
   merges: "Merges"
 };
@@ -276,7 +317,7 @@ function renderCliOnlyCommandHelp(entry) {
 }
 function renderSharedCommandHelp(pathSegments) {
   const entry = SHARED_HELP_ENTRIES.find((candidate) => {
-    const usageSegments = candidate.usage.split(" ").filter((segment) => !segment.startsWith("-") && !segment.startsWith("<") && !segment.startsWith("["));
+    const usageSegments = candidate.usage.split(" ").map((segment) => segment.replace(/^\[/, "").replace(/\]$/, "")).filter((segment) => !segment.startsWith("-") && !segment.startsWith("<") && !segment.startsWith("["));
     return usageSegments.length <= pathSegments.length && usageSegments.every((segment, index) => segment === pathSegments[index]);
   });
   if (!entry) {
@@ -512,33 +553,24 @@ function parseAnswerFlags(args) {
 function validateEnvAssignment(value) {
   const equalsIndex = value.indexOf("=");
   if (equalsIndex <= 0) {
-    throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
-  }
-  const assignment = value.slice(0, equalsIndex);
-  const slashIndex = assignment.indexOf("/");
-  if (slashIndex <= 0) {
-    throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
+    throw new Error(`Invalid env assignment '${value}'. Expected KEY=value`);
   }
-  const target = assignment.slice(0, slashIndex);
-  const key = assignment.slice(slashIndex + 1);
-  if (target !== "backend" && target !== "frontend" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
-    throw new Error(`Invalid env assignment '${value}'. Expected backend/KEY=value or frontend/KEY=value`);
+  const key = value.slice(0, equalsIndex);
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+    throw new Error(`Invalid env assignment '${value}'. Expected KEY=value`);
   }
 }
 function parseEnvAssignment(value) {
   validateEnvAssignment(value);
   const equalsIndex = value.indexOf("=");
-  const slashIndex = value.indexOf("/");
   return {
-    target: value.slice(0, slashIndex),
-    name: value.slice(slashIndex + 1, equalsIndex),
+    name: value.slice(0, equalsIndex),
     value: value.slice(equalsIndex + 1)
   };
 }
 function parseSetEnvArgs(args) {
   const parsed = {
     assignments: [],
-    target: "backend",
     onlyMissing: false,
     includeEmpty: false
   };
@@ -568,23 +600,6 @@ function parseSetEnvArgs(args) {
       parsed.fromEnvFile = requireValue(inlineFile, "Missing value for --from-env-file");
       continue;
     }
-    if (arg === "--target") {
-      const target = requireValue(args[index + 1], "Missing value for --target");
-      if (target !== "backend" && target !== "frontend") {
-        throw new Error("Invalid --target. Expected backend or frontend");
-      }
-      parsed.target = target;
-      index += 1;
-      continue;
-    }
-    const inlineTarget = parseLongOptionWithEquals(arg, "--target");
-    if (inlineTarget !== void 0) {
-      if (inlineTarget !== "backend" && inlineTarget !== "frontend") {
-        throw new Error("Invalid --target. Expected backend or frontend");
-      }
-      parsed.target = inlineTarget;
-      continue;
-    }
     if (arg === "--description") {
       parsed.description = requireValue(args[index + 1], "Missing value for --description");
       index += 1;
@@ -658,7 +673,7 @@ function parseEnvFlags(args) {
     if (arg.startsWith("-")) {
       throw new Error(`Unknown env flag: ${arg}`);
     }
-    throw new Error(`Unexpected value '${arg}'. Use -e backend/KEY=value.`);
+    throw new Error(`Unexpected value '${arg}'. Use -e KEY=value.`);
   }
   if (envs.length === 0) {
     throw new Error("At least one -e/--env value is required.");
@@ -725,6 +740,67 @@ 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 };
+}
+function parsePsListArgs(args) {
+  const input = {};
+  const definitions = [
+    { flag: "--project", key: "project" },
+    { flag: "--branch", key: "branch" },
+    { flag: "--session", key: "session" },
+    { flag: "--worker", key: "worker" }
+  ];
+  const assign = (key, value, flag) => {
+    if (input[key] !== void 0) {
+      throw new Error(`Use only one ${flag} value`);
+    }
+    input[key] = requireValue(value, `Missing value for ${flag}`);
+  };
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) continue;
+    const definition = definitions.find(({ flag }) => arg === flag || arg.startsWith(`${flag}=`));
+    if (!definition) {
+      throw new Error(arg.startsWith("-") ? `Unknown ps list flag: ${arg}` : `Unexpected ps list value: ${arg}`);
+    }
+    if (arg === definition.flag) {
+      assign(definition.key, requireValue(args[index + 1], `Missing value for ${definition.flag}`), definition.flag);
+      index += 1;
+      continue;
+    }
+    assign(
+      definition.key,
+      requireValue(parseLongOptionWithEquals(arg, definition.flag), `Missing value for ${definition.flag}`),
+      definition.flag
+    );
+  }
+  return input;
+}
 async function openInBrowser(url) {
   if (process.platform === "darwin") {
     (0, import_node_child_process.spawn)("open", [url], { stdio: "ignore", detached: true }).unref();
@@ -866,34 +942,66 @@ function renderSessionList(sessions) {
 function renderSessionDescription(session) {
   return [`Session: ${session.id}`, `Project: ${session.projectPath}`, `Branch: ${session.branchName}`].join("\n") + "\n";
 }
+function formatProcessAge(startedAt, nowMs = Date.now()) {
+  const startedAtMs = Date.parse(startedAt);
+  if (!Number.isFinite(startedAtMs)) {
+    return "unknown";
+  }
+  const totalSeconds = Math.max(0, Math.floor((nowMs - startedAtMs) / 1e3));
+  if (totalSeconds < 60) {
+    return `${totalSeconds}s`;
+  }
+  if (totalSeconds < 60 * 60) {
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+  }
+  if (totalSeconds < 24 * 60 * 60) {
+    const hours2 = Math.floor(totalSeconds / (60 * 60));
+    const minutes = Math.floor(totalSeconds % (60 * 60) / 60);
+    return `${hours2}h ${String(minutes).padStart(2, "0")}m`;
+  }
+  const days = Math.floor(totalSeconds / (24 * 60 * 60));
+  const hours = Math.floor(totalSeconds % (24 * 60 * 60) / (60 * 60));
+  return `${days}d ${hours}h`;
+}
+function renderProcessList(processes, nowMs = Date.now()) {
+  if (processes.length === 0) {
+    return "No active processes.\n";
+  }
+  const headers = ["RUN ID", "STATUS", "AGE", "WORKER", "PROJECT", "BRANCH", "SESSION", "COMMAND"];
+  const rows = processes.map((process2) => [
+    process2.runId,
+    process2.status,
+    formatProcessAge(process2.startedAt, nowMs),
+    process2.workerLabel,
+    process2.projectPath,
+    process2.branchName,
+    process2.sessionId,
+    process2.command
+  ]);
+  const widths = headers.map((header, column) => Math.max(header.length, ...rows.map((row) => row[column]?.length ?? 0)));
+  const formatRow = (row) => row.map((value, column) => column === row.length - 1 ? value : value.padEnd(widths[column] ?? value.length)).join("  ");
+  const separator = widths.map((width) => "-".repeat(width)).join("  ");
+  return `${[formatRow(headers), separator, ...rows.map(formatRow)].join("\n")}
+`;
+}
 function summarizeEnvData(data) {
-  const summary = {};
-  for (const target of ["backend", "frontend"]) {
-    const entries = data[target];
-    if (!entries) continue;
-    summary[target] = Object.fromEntries(
-      Object.entries(entries).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => [
-        name,
-        {
-          optional: env.optional ?? false,
-          description: env.description,
-          hasValue: env.value !== null
-        }
-      ])
-    );
-  }
-  return summary;
+  return Object.fromEntries(
+    Object.entries(data).sort(([left], [right]) => left.localeCompare(right)).map(([name, env]) => [
+      name,
+      {
+        optional: env.optional ?? false,
+        description: env.description,
+        hasValue: env.value !== null
+      }
+    ])
+  );
 }
 function renderEnvSummary(data) {
   const lines = [];
-  for (const target of ["backend", "frontend"]) {
-    const entries = Object.entries(data[target] ?? {});
-    if (entries.length === 0) continue;
-    if (lines.length > 0) lines.push("");
-    lines.push(`${target}:`);
-    for (const [name, env] of entries) {
-      lines.push(`  ${name}  ${env.hasValue ? "set" : "missing"}  ${env.optional ? "optional" : "required"}  ${env.description}`);
-    }
+  for (const [name, env] of Object.entries(data)) {
+    lines.push(`${name}  ${env.hasValue ? "set" : "missing"}  ${env.optional ? "optional" : "required"}  ${env.description}`);
   }
   return lines.length > 0 ? `${lines.join("\n")}
 ` : "No environment variables declared.\n";
@@ -905,7 +1013,7 @@ function renderEnvSetResult(result) {
   if (result.skippedExisting.length > 0) lines.push(`Skipped ${result.skippedExisting.length} existing value(s).`);
   if (result.skippedEmpty.length > 0) lines.push(`Skipped ${result.skippedEmpty.length} empty value(s).`);
   if (result.updated.length > 0) {
-    lines.push(...result.updated.map(({ target, name }) => `  ${target}/${name}`));
+    lines.push(...result.updated.map(({ name }) => `  ${name}`));
   }
   return `${lines.join("\n")}
 `;
@@ -918,10 +1026,10 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
       throw new Error(`Invalid environment variable name in dotenv file: ${name}`);
     }
-    return { target: options.target, name, value };
+    return { name, value };
   }) : options.assignments.map(parseEnvAssignment);
   const uniqueAssignments = /* @__PURE__ */ new Map();
-  for (const assignment of assignments) uniqueAssignments.set(`${assignment.target}/${assignment.name}`, assignment);
+  for (const assignment of assignments) uniqueAssignments.set(assignment.name, assignment);
   const update = {};
   const result = {
     success: true,
@@ -934,12 +1042,12 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
   const missingDescriptions = [];
   const importedDescription = options.fromEnvFile ? `Imported from ${import_node_path.default.basename(options.fromEnvFile)}.` : void 0;
   for (const assignment of uniqueAssignments.values()) {
-    const identity = { target: assignment.target, name: assignment.name };
+    const identity = { name: assignment.name };
     if (!options.includeEmpty && assignment.value.length === 0) {
       result.skippedEmpty.push(identity);
       continue;
     }
-    const existing = current[assignment.target]?.[assignment.name];
+    const existing = current[assignment.name];
     if (options.onlyMissing && existing?.value !== null && existing?.value !== void 0) {
       result.skippedExisting.push(identity);
       continue;
@@ -949,9 +1057,8 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
       missingDescriptions.push(identity);
       continue;
     }
-    const targetUpdate = update[assignment.target] ??= {};
     const optional = options.optional ?? existing?.optional;
-    targetUpdate[assignment.name] = {
+    update[assignment.name] = {
       description,
       value: assignment.value,
       ...optional === void 0 ? {} : { optional }
@@ -959,9 +1066,7 @@ async function setBranchEnvs(client, projectRef, branchName, args) {
     result.updated.push(identity);
   }
   if (missingDescriptions.length > 0) {
-    throw new Error(
-      `--description is required when declaring new envs with -e: ${missingDescriptions.map(({ target, name }) => `${target}/${name}`).join(", ")}`
-    );
+    throw new Error(`--description is required when declaring new envs with -e: ${missingDescriptions.map(({ name }) => name).join(", ")}`);
   }
   if (result.updated.length > 0) {
     await client.projects.env.update(project.id, branchName, update);
@@ -1126,6 +1231,17 @@ async function executeR5dctlCommand(client, json, args) {
     write(result, "API key revoked.\n");
     return;
   }
+  if (first === "ps" && second === "list") {
+    const processes = await client.processes.list(parsePsListArgs(args.slice(2)));
+    write(processes, renderProcessList(processes));
+    return;
+  }
+  if (first === "ps" && second === "stop") {
+    const process2 = await client.processes.stop(requireValue(args[2], "Missing process run id"));
+    write(process2, `Stopped process ${process2.runId}: ${process2.command}
+`);
+    return;
+  }
   if (first === "projects" && second === "list" || first === "get" && second === "projects") {
     const projects = await client.projects.list();
     write(projects, renderProjectList(projects));
@@ -1321,6 +1437,12 @@ function resolveCommandExecution(options, rest) {
     throw new Error("Missing command");
   }
   const commandArgs = normalizedRest.slice(1);
+  if (command === "ps" && commandArgs.length === 0) {
+    return {
+      kind: "cli-help",
+      text: PS_HELP_TEXT
+    };
+  }
   if (trailingHelp) {
     const cliOnlyHelp = findCliOnlyCommandHelp(normalizedRest);
     if (cliOnlyHelp) {
@@ -1394,6 +1516,36 @@ function resolveCommandExecution(options, rest) {
     }
     throw new Error("Unknown auth command");
   }
+  if (command === "ps") {
+    const subcommand = commandArgs[0];
+    if (subcommand === "list") {
+      const commandFilters = parsePsListArgs(commandArgs.slice(1));
+      const filters = {
+        ...commandFilters,
+        ...options.project ? { project: options.project } : {},
+        ...options.branch ? { branch: options.branch } : {},
+        ...options.session ? { session: options.session } : {}
+      };
+      const pluginArgs = ["ps", "list"];
+      for (const [flag, value] of [
+        ["--project", filters.project],
+        ["--branch", filters.branch],
+        ["--session", filters.session],
+        ["--worker", filters.worker]
+      ]) {
+        if (value) pluginArgs.push(flag, value);
+      }
+      return { kind: "plugin", pluginArgs };
+    }
+    if (subcommand === "stop") {
+      const runId = requireValue(commandArgs[1], "Missing process run id");
+      if (commandArgs.length > 2) {
+        throw new Error(`Unexpected ps stop value: ${commandArgs[2]}`);
+      }
+      return { kind: "plugin", pluginArgs: ["ps", "stop", runId] };
+    }
+    throw new Error(`Unknown ps command: ${subcommand ?? ""}`.trim());
+  }
   if (command === "get") {
     const target = commandArgs[0];
     if (target === "projects") {
@@ -1573,6 +1725,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 +1863,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 +1912,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,11 +1927,12 @@ 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:
 0 && (module.exports = {
+  formatProcessAge,
   getCliHelpText,
   getR5dctlVersion,
   main,
@@ -1762,9 +1941,12 @@ async function main(argv = process.argv.slice(2)) {
   parseEnvFlags,
   parseGlobalArgs,
   parsePromptArgs,
+  parsePsListArgs,
   parseSetEnvArgs,
+  parseShellArgs,
   readDotenvFile,
   renderConversationResponse,
+  renderProcessList,
   resolveCommandExecution,
   runR5dctlCli,
   summarizeEnvData

package/dist/cjs/package.json

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