inthhq · BurnedChris · May 31, 2026 · May 31, 2026 · May 31, 2026 · May 31, 2026
diff --git a/.changeset/green-buses-log.md b/.changeset/green-buses-log.md
@@ -0,0 +1,5 @@
+---
+"hexbus": patch
+---
+
+Add `--log-file` and `--log-format` transcript capture for CLI output.
diff --git a/packages/hexbus/src/__tests__/spawned-cli.e2e.test.ts b/packages/hexbus/src/__tests__/spawned-cli.e2e.test.ts
@@ -19,6 +19,7 @@ const versionCachePath = path.join(
   versionCacheDir,
   `${FIXTURE_PACKAGE_NAME}.json`
 );
+const transcriptDir = path.join(os.tmpdir(), "hexbus-transcripts");
 
 interface FixtureCliResult {
   code: number | null;
@@ -47,6 +48,14 @@ async function writeVersionCache(): Promise<void> {
   );
 }
 
+async function makeTranscriptPath(name: string): Promise<string> {
+  await fs.mkdir(transcriptDir, { recursive: true });
+  return path.join(
+    transcriptDir,
+    `${name}-${Date.now()}-${Math.random().toString(16).slice(2)}.log`
+  );
+}
+
 function runFixtureCli(args: string[]): Promise<FixtureCliResult> {
   return new Promise((resolve, reject) => {
     const child = spawn("bun", [fixturePath, ...args], {
@@ -102,6 +111,7 @@ beforeEach(async () => {
 
 afterAll(async () => {
   await fs.rm(versionCachePath, { force: true });
+  await fs.rm(transcriptDir, { force: true, recursive: true });
 });
 
 describe("spawned fixture CLI", () => {
@@ -195,4 +205,57 @@ describe("spawned fixture CLI", () => {
     expectCleanExit(result);
     expect(result.stdout).toContain("telemetry disabled: true");
   });
+
+  it("writes a plain text output transcript with --log-file", async () => {
+    const transcriptPath = await makeTranscriptPath("plain");
+    const result = await runFixtureCli([
+      "--log-file",
+      transcriptPath,
+      "hello",
+      "transcript",
+    ]);
+
+    expectCleanExit(result);
+    const transcript = await fs.readFile(transcriptPath, "utf-8");
+    expect(transcript).toContain("hello args: transcript");
+  });
+
+  it("writes structured JSONL output with --log-format jsonl", async () => {
+    const transcriptPath = await makeTranscriptPath("jsonl");
+    const result = await runFixtureCli([
+      "--log-file",
+      transcriptPath,
+      "--log-format",
+      "jsonl",
+      "hello",
+      "agent",
+    ]);
+
+    expectCleanExit(result);
+    const transcript = await fs.readFile(transcriptPath, "utf-8");
+    const lines = transcript
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line) as Record<string, unknown>);
+    expect(lines[0]).toMatchObject({
+      appName: "fixture-cli",
+      format: "jsonl",
+      type: "start",
+    });
+    expect(lines).toContainEqual(
+      expect.objectContaining({
+        stream: "stdout",
+        type: "output",
+      })
+    );
+    expect(
+      lines.some(
+        (line) =>
+          line.type === "output" &&
+          typeof line.text === "string" &&
+          line.text.includes("hello args: agent")
+      )
+    ).toBe(true);
+    expect(lines.at(-1)).toMatchObject({ type: "end" });
+  });
 });
diff --git a/packages/hexbus/src/__tests__/transcript.test.ts b/packages/hexbus/src/__tests__/transcript.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+
+import { parseTranscriptFlags } from "../transcript";
+
+describe(parseTranscriptFlags, () => {
+  it("parses spaced and equals-form transcript flags", () => {
+    expect(
+      parseTranscriptFlags(["--log-file", "run.log", "--log-format=jsonl"])
+    ).toStrictEqual({
+      filePath: "run.log",
+      format: "jsonl",
+    });
+  });
+
+  it("does not consume another flag as a missing transcript value", () => {
+    expect(parseTranscriptFlags(["--log-file", "--help"])).toBeNull();
+    expect(
+      parseTranscriptFlags(["--log-file=run.log", "--log-format", "--help"])
+    ).toStrictEqual({
+      filePath: "run.log",
+      format: "text",
+    });
+  });
+});
diff --git a/packages/hexbus/src/index.ts b/packages/hexbus/src/index.ts
@@ -172,6 +172,14 @@ export {
   type TelemetryEventNameType,
   type TelemetryOptions,
 } from "./telemetry";
+export {
+  type OutputTranscript,
+  parseTranscriptFlags,
+  type StartTranscriptOptions,
+  startOutputTranscript,
+  type TranscriptFlagOptions,
+  type TranscriptFormat,
+} from "./transcript";
 export type {
   CliCommandAlias,
   CliCommandCategory,

diff --git a/packages/hexbus/src/parser.ts b/packages/hexbus/src/parser.ts
@@ -30,6 +30,19 @@ export const globalFlags: CliFlag[] = [
     names: ["--logger"],
     type: "string",
   },
+  {
+    description: "Write stdout and stderr to a transcript file",
+    expectsValue: true,
+    names: ["--log-file"],
+    type: "string",
+  },
+  {
+    defaultValue: "text",
+    description: "Set transcript format (text, jsonl)",
+    expectsValue: true,
+    names: ["--log-format"],
+    type: "string",
+  },
   {
     defaultValue: false,
     description: "Force color output",

diff --git a/packages/hexbus/src/runner.ts b/packages/hexbus/src/runner.ts
@@ -19,6 +19,7 @@ import { displayIntro } from "./intro";
 import type { DisplayIntroOptions } from "./intro";
 import { globalFlags } from "./parser";
 import { TelemetryEventName } from "./telemetry";
+import { parseTranscriptFlags, startOutputTranscript } from "./transcript";
 import type { CliCommand, CliContext, CliFlag, PackageInfo } from "./types";
 import {
   isVersionRequest,
@@ -796,14 +797,23 @@ export async function runCli<
   TContext extends CliContext<TPackage> = CliContext<TPackage>,
 >(options: RunCliOptions<TPackage, TContext>): Promise<void> {
   const rawArgs = options.rawArgs ?? process.argv.slice(2);
-
-  if (await handleVersionRequest(options, rawArgs)) {
-    return;
-  }
-
   const state: RunCliState<TPackage, TContext> = { outcome: "completed" };
+  const transcriptFlags = parseTranscriptFlags(rawArgs);
+  const transcript =
+    transcriptFlags === null
+      ? null
+      : startOutputTranscript({
+          ...transcriptFlags,
+          appName: options.appName,
+          cwd: options.context?.cwd ?? process.cwd(),
+          rawArgs,
+        });
 
   try {
+    if (await handleVersionRequest(options, rawArgs)) {
+      return;
+    }
+
     state.context = await createRunnerContext(options, rawArgs);
     state.context.telemetry.trackEvent(TelemetryEventName.CLI_INVOKED, {
       command: state.context.commandName ?? "none",
@@ -833,5 +843,9 @@ export async function runCli<
     await shutdownRunnerTelemetry(state);
   }
 
-  handleRunnerError(state);
+  try {
+    handleRunnerError(state);
+  } finally {
+    await transcript?.close(state.errorToHandle === undefined ? 0 : 1);
+  }
 }