patchrelay 0.6.0 → 0.7.0

package/dist/build-info.js

@@ -7,10 +7,10 @@ const fallbackBuildInfo = {
     commit: "unknown",
     builtAt: "unknown",
 };
-export function getBuildInfo() {
-    const buildInfoPath = path.resolve(process.cwd(), "dist/build-info.json");
-    const fallbackPath = getBundledAssetPath("dist/build-info.json");
-    const resolvedPath = existsSync(buildInfoPath) ? buildInfoPath : fallbackPath;
+export function getBuildInfo(paths) {
+    const fallbackPath = paths?.bundledPath ?? getBundledAssetPath("dist/build-info.json");
+    const cwdBuildInfoPath = paths?.cwdPath ?? path.resolve(process.cwd(), "dist/build-info.json");
+    const resolvedPath = existsSync(fallbackPath) ? fallbackPath : cwdBuildInfoPath;
     if (!existsSync(resolvedPath)) {
         return fallbackBuildInfo;
     }

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.6.0",
-  "commit": "3dd80e1684b4",
-  "builtAt": "2026-03-13T13:20:38.482Z"
+  "version": "0.7.0",
+  "commit": "450840270db1",
+  "builtAt": "2026-03-13T18:08:50.316Z"
 }

package/dist/cli/args.js

@@ -1,3 +1,4 @@
+import { UnknownCommandError, UnknownFlagsError } from "./errors.js";
 export const KNOWN_COMMANDS = new Set([
     "version",
     "serve",
@@ -25,6 +26,10 @@ export function parseArgs(argv) {
     const flags = new Map();
     for (let index = 0; index < argv.length; index += 1) {
         const value = argv[index];
+        if (value === "-h" || value === "--help") {
+            flags.set("help", true);
+            continue;
+        }
         if (!value.startsWith("--")) {
             positionals.push(value);
             continue;
@@ -59,7 +64,10 @@ export function resolveCommand(parsed) {
     if (ISSUE_KEY_PATTERN.test(requestedCommand)) {
         return { command: "inspect", commandArgs: parsed.positionals };
     }
-    throw new Error(`Unknown command: ${requestedCommand}. Run \`patchrelay help\`.`);
+    throw new UnknownCommandError(requestedCommand);
+}
+export function hasHelpFlag(parsed) {
+    return parsed.flags.get("help") === true;
 }
 export function getStageFlag(value) {
     if (typeof value !== "string") {
@@ -78,12 +86,12 @@ export function parseCsvFlag(value) {
         .filter(Boolean);
 }
 export function assertKnownFlags(parsed, command, allowedFlags) {
-    const allowed = new Set(allowedFlags);
+    const allowed = new Set(["help", ...allowedFlags]);
     const unknownFlags = [...parsed.flags.keys()].filter((flag) => !allowed.has(flag)).sort();
     if (unknownFlags.length === 0) {
         return;
     }
-    throw new Error(`Unknown flag${unknownFlags.length === 1 ? "" : "s"} for ${command}: ${unknownFlags.map((flag) => `--${flag}`).join(", ")}`);
+    throw new UnknownFlagsError(unknownFlags, command === "project" || command === "project apply" ? "project" : "root");
 }
 export function parsePositiveIntegerFlag(value, flagName) {
     if (typeof value !== "string") {

package/dist/cli/commands/project.js

@@ -1,140 +1,146 @@
 import { loadConfig } from "../../config.js";
 import { installUserServiceUnits, upsertProjectInConfig } from "../../install.js";
-import { runPreflight } from "../../preflight.js";
-import { parseCsvFlag } from "../args.js";
+import { hasHelpFlag, parseCsvFlag } from "../args.js";
 import { runConnectFlow, parseTimeoutSeconds } from "../connect-flow.js";
-import { CliDataAccess } from "../data.js";
+import { CliUsageError } from "../errors.js";
 import { formatJson } from "../formatters/json.js";
+import { projectHelpText } from "../help.js";
 import { writeOutput } from "../output.js";
 import { installServiceCommands, tryManageService } from "../service-commands.js";
 export async function handleProjectCommand(params) {
+    if (hasHelpFlag(params.parsed)) {
+        writeOutput(params.stdout, `${projectHelpText()}\n`);
+        return 0;
+    }
+    if (params.commandArgs.length === 0) {
+        throw new CliUsageError("patchrelay project requires a subcommand.", "project");
+    }
+    const subcommand = params.commandArgs[0];
+    if (subcommand !== "apply") {
+        throw new CliUsageError(`Unknown project command: ${subcommand}`, "project");
+    }
+    const projectId = params.commandArgs[1];
+    const repoPath = params.commandArgs[2];
+    if (!projectId || !repoPath) {
+        throw new CliUsageError("patchrelay project apply requires <id> and <repo-path>.", "project");
+    }
+    const result = await upsertProjectInConfig({
+        id: projectId,
+        repoPath,
+        issueKeyPrefixes: parseCsvFlag(params.parsed.flags.get("issue-prefix")),
+        linearTeamIds: parseCsvFlag(params.parsed.flags.get("team-id")),
+    });
+    const serviceUnits = await installUserServiceUnits();
+    const noConnect = params.parsed.flags.get("no-connect") === true;
+    const lines = [
+        `Config file: ${result.configPath}`,
+        `${result.status === "created" ? "Created" : result.status === "updated" ? "Updated" : "Verified"} project ${result.project.id} for ${result.project.repoPath}`,
+        result.project.issueKeyPrefixes.length > 0 ? `Issue key prefixes: ${result.project.issueKeyPrefixes.join(", ")}` : undefined,
+        result.project.linearTeamIds.length > 0 ? `Linear team ids: ${result.project.linearTeamIds.join(", ")}` : undefined,
+        `Service unit: ${serviceUnits.unitPath} (${serviceUnits.serviceStatus})`,
+        `Watcher unit: ${serviceUnits.pathUnitPath} (${serviceUnits.pathStatus})`,
+    ].filter(Boolean);
+    let fullConfig;
     try {
-        const subcommand = params.commandArgs[0];
-        if (subcommand !== "apply") {
-            throw new Error("Usage: patchrelay project apply <id> <repo-path> [--issue-prefix <prefixes>] [--team-id <ids>] [--no-connect] [--timeout <seconds>]");
-        }
-        const projectId = params.commandArgs[1];
-        const repoPath = params.commandArgs[2];
-        if (!projectId || !repoPath) {
-            throw new Error("Usage: patchrelay project apply <id> <repo-path> [--issue-prefix <prefixes>] [--team-id <ids>] [--no-connect] [--timeout <seconds>]");
-        }
-        const result = await upsertProjectInConfig({
-            id: projectId,
-            repoPath,
-            issueKeyPrefixes: parseCsvFlag(params.parsed.flags.get("issue-prefix")),
-            linearTeamIds: parseCsvFlag(params.parsed.flags.get("team-id")),
-        });
-        const serviceUnits = await installUserServiceUnits();
-        const noConnect = params.parsed.flags.get("no-connect") === true;
-        const lines = [
-            `Config file: ${result.configPath}`,
-            `${result.status === "created" ? "Created" : result.status === "updated" ? "Updated" : "Verified"} project ${result.project.id} for ${result.project.repoPath}`,
-            result.project.issueKeyPrefixes.length > 0 ? `Issue key prefixes: ${result.project.issueKeyPrefixes.join(", ")}` : undefined,
-            result.project.linearTeamIds.length > 0 ? `Linear team ids: ${result.project.linearTeamIds.join(", ")}` : undefined,
-            `Service unit: ${serviceUnits.unitPath} (${serviceUnits.serviceStatus})`,
-            `Watcher unit: ${serviceUnits.pathUnitPath} (${serviceUnits.pathStatus})`,
-        ].filter(Boolean);
-        let fullConfig;
-        try {
-            fullConfig = loadConfig(undefined, { profile: "doctor" });
-        }
-        catch (error) {
-            if (params.json) {
-                writeOutput(params.stdout, formatJson({
-                    ...result,
-                    serviceUnits,
-                    readiness: {
-                        ok: false,
-                        error: error instanceof Error ? error.message : String(error),
-                    },
-                    connect: {
-                        attempted: false,
-                        skipped: "missing_env",
-                    },
-                }));
-                return 0;
-            }
-            lines.push(`Linear connect was skipped: ${error instanceof Error ? error.message : String(error)}`);
-            lines.push("Finish the required env vars and rerun `patchrelay project apply`.");
-            writeOutput(params.stdout, `${lines.join("\n")}\n`);
+        fullConfig = loadConfig(undefined, { profile: "doctor" });
+    }
+    catch (error) {
+        if (params.json) {
+            writeOutput(params.stdout, formatJson({
+                ...result,
+                serviceUnits,
+                readiness: {
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                },
+                connect: {
+                    attempted: false,
+                    skipped: "missing_env",
+                },
+            }));
             return 0;
         }
-        const report = await runPreflight(fullConfig);
-        const failedChecks = report.checks.filter((check) => check.status === "fail");
-        if (failedChecks.length > 0) {
-            if (params.json) {
-                writeOutput(params.stdout, formatJson({
-                    ...result,
-                    serviceUnits,
-                    readiness: report,
-                    connect: {
-                        attempted: false,
-                        skipped: "preflight_failed",
-                    },
-                }));
-                return 0;
-            }
-            lines.push("Linear connect was skipped because PatchRelay is not ready yet:");
-            lines.push(...failedChecks.map((check) => `- [${check.scope}] ${check.message}`));
-            lines.push("Fix the failures above and rerun `patchrelay project apply`.");
-            writeOutput(params.stdout, `${lines.join("\n")}\n`);
+        lines.push(`Linear connect was skipped: ${error instanceof Error ? error.message : String(error)}`);
+        lines.push("Finish the required env vars and rerun `patchrelay project apply`.");
+        writeOutput(params.stdout, `${lines.join("\n")}\n`);
+        return 0;
+    }
+    const { runPreflight } = await import("../../preflight.js");
+    const report = await runPreflight(fullConfig);
+    const failedChecks = report.checks.filter((check) => check.status === "fail");
+    if (failedChecks.length > 0) {
+        if (params.json) {
+            writeOutput(params.stdout, formatJson({
+                ...result,
+                serviceUnits,
+                readiness: report,
+                connect: {
+                    attempted: false,
+                    skipped: "preflight_failed",
+                },
+            }));
             return 0;
         }
-        const serviceState = await tryManageService(params.runInteractive, installServiceCommands());
-        if (!serviceState.ok) {
-            throw new Error(`Project was saved, but PatchRelay could not be reloaded: ${serviceState.error}`);
+        lines.push("Linear connect was skipped because PatchRelay is not ready yet:");
+        lines.push(...failedChecks.map((check) => `- [${check.scope}] ${check.message}`));
+        lines.push("Fix the failures above and rerun `patchrelay project apply`.");
+        writeOutput(params.stdout, `${lines.join("\n")}\n`);
+        return 0;
+    }
+    const serviceState = await tryManageService(params.runInteractive, installServiceCommands());
+    if (!serviceState.ok) {
+        throw new Error(`Project was saved, but PatchRelay could not be reloaded: ${serviceState.error}`);
+    }
+    const cliData = params.options?.data ?? (await createCliDataAccess(fullConfig));
+    try {
+        if (params.json) {
+            const connectResult = noConnect ? undefined : await cliData.connect(projectId);
+            writeOutput(params.stdout, formatJson({
+                ...result,
+                serviceUnits,
+                readiness: report,
+                serviceReloaded: true,
+                ...(noConnect
+                    ? {
+                        connect: {
+                            attempted: false,
+                            skipped: "no_connect",
+                        },
+                    }
+                    : {
+                        connect: {
+                            attempted: true,
+                            result: connectResult,
+                        },
+                    }),
+            }));
+            return 0;
         }
-        const cliData = params.options?.data ?? new CliDataAccess(fullConfig);
-        try {
-            if (params.json) {
-                const connectResult = noConnect ? undefined : await cliData.connect(projectId);
-                writeOutput(params.stdout, formatJson({
-                    ...result,
-                    serviceUnits,
-                    readiness: report,
-                    serviceReloaded: true,
-                    ...(noConnect
-                        ? {
-                            connect: {
-                                attempted: false,
-                                skipped: "no_connect",
-                            },
-                        }
-                        : {
-                            connect: {
-                                attempted: true,
-                                result: connectResult,
-                            },
-                        }),
-                }));
-                return 0;
-            }
-            if (noConnect) {
-                lines.push("Project saved and PatchRelay was reloaded.");
-                lines.push(`Next: patchrelay connect --project ${result.project.id}`);
-                writeOutput(params.stdout, `${lines.join("\n")}\n`);
-                return 0;
-            }
+        if (noConnect) {
+            lines.push("Project saved and PatchRelay was reloaded.");
+            lines.push(`Next: patchrelay connect --project ${result.project.id}`);
             writeOutput(params.stdout, `${lines.join("\n")}\n`);
-            return await runConnectFlow({
-                config: fullConfig,
-                data: cliData,
-                stdout: params.stdout,
-                noOpen: params.parsed.flags.get("no-open") === true,
-                timeoutSeconds: parseTimeoutSeconds(params.parsed.flags.get("timeout"), "project apply"),
-                projectId,
-                ...(params.options?.openExternal ? { openExternal: params.options.openExternal } : {}),
-                ...(params.options?.connectPollIntervalMs !== undefined ? { connectPollIntervalMs: params.options.connectPollIntervalMs } : {}),
-            });
-        }
-        finally {
-            if (!params.options?.data) {
-                cliData.close();
-            }
+            return 0;
         }
+        writeOutput(params.stdout, `${lines.join("\n")}\n`);
+        return await runConnectFlow({
+            config: fullConfig,
+            data: cliData,
+            stdout: params.stdout,
+            noOpen: params.parsed.flags.get("no-open") === true,
+            timeoutSeconds: parseTimeoutSeconds(params.parsed.flags.get("timeout"), "project apply"),
+            projectId,
+            ...(params.options?.openExternal ? { openExternal: params.options.openExternal } : {}),
+            ...(params.options?.connectPollIntervalMs !== undefined ? { connectPollIntervalMs: params.options.connectPollIntervalMs } : {}),
+        });
     }
-    catch (error) {
-        writeOutput(params.stderr, `${error instanceof Error ? error.message : String(error)}\n`);
-        return 1;
+    finally {
+        if (!params.options?.data) {
+            cliData.close();
+        }
     }
 }
+async function createCliDataAccess(config) {
+    const { CliDataAccess } = await import("../data.js");
+    return new CliDataAccess(config);
+}

package/dist/cli/errors.js

@@ -0,0 +1,20 @@
+export class CliUsageError extends Error {
+    helpTopic;
+    constructor(message, helpTopic = "root") {
+        super(message);
+        this.helpTopic = helpTopic;
+        this.name = "CliUsageError";
+    }
+}
+export class UnknownCommandError extends CliUsageError {
+    constructor(command) {
+        super(`Unknown command: ${command}`);
+        this.name = "UnknownCommandError";
+    }
+}
+export class UnknownFlagsError extends CliUsageError {
+    constructor(flags, helpTopic = "root") {
+        super(`Unknown flag${flags.length === 1 ? "" : "s"}: ${flags.map((flag) => `--${flag}`).join(", ")}`, helpTopic);
+        this.name = "UnknownFlagsError";
+    }
+}

package/dist/cli/help.js

@@ -0,0 +1,108 @@
+export function rootHelpText() {
+    return [
+        "PatchRelay",
+        "",
+        "patchrelay is a local service and CLI that connects Linear issue delegation to Codex worktrees on your machine.",
+        "",
+        "Usage:",
+        "  patchrelay <command> [args] [flags]",
+        "  patchrelay <issueKey>                 # shorthand for `patchrelay inspect <issueKey>`",
+        "",
+        "First-time setup:",
+        "  1. patchrelay init <public-https-url>",
+        "  2. Fill in ~/.config/patchrelay/service.env",
+        "  3. patchrelay project apply <id> <repo-path>",
+        "  4. Edit the generated project workflows if needed, then add those workflow files to the repo",
+        "  5. patchrelay doctor",
+        "",
+        "Why init needs the public URL:",
+        "  Linear must reach PatchRelay at a public HTTPS origin for both the webhook endpoint",
+        "  and the OAuth callback. `patchrelay init` writes that origin to `server.public_base_url`.",
+        "",
+        "Default behavior:",
+        "  PatchRelay already defaults the local bind address, database path, log path, worktree",
+        "  root, and Codex runner settings. In the normal",
+        "  case you only need the public URL, the required secrets, and at least one project.",
+        "  `patchrelay init` installs the user service and config watcher, and `project apply`",
+        "  upserts the repo config and reuses or starts the Linear connection flow.",
+        "",
+        "Commands:",
+        "  version [--json]                                        Show the installed PatchRelay build version",
+        "  init <public-base-url> [--force] [--json]               Bootstrap the machine-level PatchRelay home",
+        "  project apply <id> <repo-path> [--issue-prefix <prefixes>] [--team-id <ids>] [--no-connect] [--no-open] [--timeout <seconds>] [--json]",
+        "                                                          Upsert one local repository and connect it to Linear when ready",
+        "  doctor [--json]                                         Check secrets, paths, configured workflow files, git, and codex",
+        "  install-service [--force] [--write-only] [--json]      Reinstall the systemd user service and watcher",
+        "  restart-service [--json]                               Reload-or-restart the systemd user service",
+        "  connect [--project <projectId>] [--no-open] [--timeout <seconds>] [--json]",
+        "                                                          Advanced: start or reuse a Linear installation directly",
+        "  installations [--json]                                 Show connected Linear installations",
+        "  feed [--follow] [--limit <count>] [--issue <issueKey>] [--project <projectId>] [--json]",
+        "                                                          Show a live operator feed from the daemon",
+        "  serve                                                  Run the local PatchRelay service",
+        "  inspect <issueKey>                                     Show the latest known issue state",
+        "  live <issueKey> [--watch] [--json]                     Show the active run status",
+        "  report <issueKey> [--stage <workflow>] [--stage-run <id>] [--json]",
+        "                                                          Show finished workflow reports",
+        "  events <issueKey> [--stage-run <id>] [--method <name>] [--follow] [--json]",
+        "                                                          Show raw thread events",
+        "  worktree <issueKey> [--cd] [--json]                    Print the issue worktree path",
+        "  open <issueKey> [--print] [--json]                     Open Codex in the issue worktree",
+        "  retry <issueKey> [--stage <workflow>] [--reason <text>] [--json]",
+        "                                                          Requeue a workflow",
+        "  list [--active] [--failed] [--project <projectId>] [--json]",
+        "                                                          List tracked issues",
+        "",
+        "Environment options:",
+        "  --help, -h              Show help for the root command or current command group",
+        "",
+        "Automation env vars:",
+        "  PATCHRELAY_CONFIG       Override the config file path",
+        "  PATCHRELAY_DB_PATH      Override the SQLite database path",
+        "  PATCHRELAY_LOG_FILE     Override the log file path",
+        "  PATCHRELAY_LOG_LEVEL    Override the log level",
+        "",
+        "Examples:",
+        "  patchrelay init https://patchrelay.example.com",
+        "  patchrelay project apply app /absolute/path/to/repo",
+        "  patchrelay doctor",
+        "  patchrelay USE-54",
+        "  patchrelay version --json",
+        "",
+        "Command help:",
+        "  patchrelay help",
+        "  patchrelay help project",
+        "  patchrelay project --help",
+    ].join("\n");
+}
+export function projectHelpText() {
+    return [
+        "Usage:",
+        "  patchrelay project apply <id> <repo-path> [options]",
+        "",
+        "Commands:",
+        "  apply <id> <repo-path>   Create or update a repository entry in the local PatchRelay config",
+        "",
+        "Options:",
+        "  --issue-prefix <prefixes>  Comma-separated issue key prefixes for routing",
+        "  --team-id <ids>            Comma-separated Linear team ids for routing",
+        "  --no-connect               Save the project without starting or reusing Linear OAuth",
+        "  --no-open                  Do not open the browser during connect",
+        "  --timeout <seconds>        Override the connect wait timeout",
+        "  --json                     Emit structured JSON output",
+        "  --help, -h                 Show this help",
+        "",
+        "Behavior:",
+        "  `patchrelay project apply` is the idempotent happy-path command. It updates",
+        "  the local config, reruns readiness checks, reloads the service when ready,",
+        "  and reuses or starts the Linear connect flow unless `--no-connect` is set.",
+        "",
+        "Examples:",
+        "  patchrelay project apply app /absolute/path/to/repo",
+        "  patchrelay project apply app /absolute/path/to/repo --issue-prefix APP",
+        "  patchrelay project apply app /absolute/path/to/repo --team-id team-123 --no-connect",
+    ].join("\n");
+}
+export function helpTextFor(topic) {
+    return topic === "project" ? projectHelpText() : rootHelpText();
+}

package/dist/cli/index.js

@@ -1,72 +1,16 @@
 import { loadConfig } from "../config.js";
 import { getBuildInfo } from "../build-info.js";
-import { runPreflight } from "../preflight.js";
-import { assertKnownFlags, parseArgs, resolveCommand } from "./args.js";
+import { assertKnownFlags, hasHelpFlag, parseArgs, resolveCommand } from "./args.js";
 import { handleConnectCommand, handleInstallationsCommand } from "./commands/connect.js";
 import { handleFeedCommand } from "./commands/feed.js";
 import { handleEventsCommand, handleInspectCommand, handleListCommand, handleLiveCommand, handleOpenCommand, handleReportCommand, handleRetryCommand, handleWorktreeCommand, } from "./commands/issues.js";
 import { handleProjectCommand } from "./commands/project.js";
 import { handleInitCommand, handleInstallServiceCommand, handleRestartServiceCommand } from "./commands/setup.js";
-import { CliDataAccess } from "./data.js";
+import { CliUsageError } from "./errors.js";
 import { formatJson } from "./formatters/json.js";
+import { helpTextFor, rootHelpText } from "./help.js";
 import { runInteractiveCommand } from "./interactive.js";
-import { formatDoctor, writeOutput } from "./output.js";
-function helpText() {
-    return [
-        "PatchRelay",
-        "",
-        "patchrelay is a local service and CLI that connects Linear issue delegation to Codex worktrees on your machine.",
-        "",
-        "Usage:",
-        "  patchrelay <command> [args] [flags]",
-        "  patchrelay <issueKey>                 # shorthand for `patchrelay inspect <issueKey>`",
-        "",
-        "First-time setup:",
-        "  1. patchrelay init <public-https-url>",
-        "  2. Fill in ~/.config/patchrelay/service.env",
-        "  3. patchrelay project apply <id> <repo-path>",
-        "  4. Edit the generated project workflows if needed, then add those workflow files to the repo",
-        "  5. patchrelay doctor",
-        "",
-        "Why init needs the public URL:",
-        "  Linear must reach PatchRelay at a public HTTPS origin for both the webhook endpoint",
-        "  and the OAuth callback. `patchrelay init` writes that origin to `server.public_base_url`.",
-        "",
-        "Default behavior:",
-        "  PatchRelay already defaults the local bind address, database path, log path, worktree",
-        "  root, and Codex runner settings. In the normal",
-        "  case you only need the public URL, the required secrets, and at least one project.",
-        "  `patchrelay init` installs the user service and config watcher, and `project apply`",
-        "  upserts the repo config and reuses or starts the Linear connection flow.",
-        "",
-        "Commands:",
-        "  version [--json]                                        Show the installed PatchRelay build version",
-        "  init <public-base-url> [--force] [--json]                Bootstrap the machine-level PatchRelay home",
-        "  project apply <id> <repo-path> [--issue-prefix <prefixes>] [--team-id <ids>] [--no-connect] [--no-open] [--timeout <seconds>] [--json]",
-        "                                                           Upsert one local repository and connect it to Linear when ready",
-        "  doctor [--json]                                          Check secrets, paths, configured workflow files, git, and codex",
-        "  install-service [--force] [--write-only] [--json]       Reinstall the systemd user service and watcher",
-        "  restart-service [--json]                                Reload-or-restart the systemd user service",
-        "  connect [--project <projectId>] [--no-open] [--timeout <seconds>] [--json]",
-        "                                                           Advanced: start or reuse a Linear installation directly",
-        "  installations [--json]                                  Show connected Linear installations",
-        "  feed [--follow] [--limit <count>] [--issue <issueKey>] [--project <projectId>] [--json]",
-        "                                                           Show a live operator feed from the daemon",
-        "  serve                                                   Run the local PatchRelay service",
-        "  inspect <issueKey>                                      Show the latest known issue state",
-        "  live <issueKey> [--watch] [--json]                      Show the active run status",
-        "  report <issueKey> [--stage <workflow>] [--stage-run <id>] [--json]",
-        "                                                           Show finished workflow reports",
-        "  events <issueKey> [--stage-run <id>] [--method <name>] [--follow] [--json]",
-        "                                                           Show raw thread events",
-        "  worktree <issueKey> [--cd] [--json]                     Print the issue worktree path",
-        "  open <issueKey> [--print] [--json]                      Open Codex in the issue worktree",
-        "  retry <issueKey> [--stage <workflow>] [--reason <text>] [--json]",
-        "                                                           Requeue a workflow",
-        "  list [--active] [--failed] [--project <projectId>] [--json]",
-        "                                                           List tracked issues",
-    ].join("\n");
-}
+import { formatDoctor, writeOutput, writeUsageError } from "./output.js";
 function getCommandConfigProfile(command) {
     switch (command) {
         case "version":
@@ -168,12 +112,25 @@ export async function runCli(argv, options) {
         validateFlags(command, commandArgs, parsed);
     }
     catch (error) {
+        if (error instanceof CliUsageError) {
+            writeUsageError(stderr, error);
+            return 1;
+        }
         writeOutput(stderr, `${error instanceof Error ? error.message : String(error)}\n`);
         return 1;
     }
     const json = parsed.flags.get("json") === true;
     if (command === "help") {
-        writeOutput(stdout, `${helpText()}\n`);
+        const topic = commandArgs[0];
+        if (topic === "project") {
+            writeOutput(stdout, `${helpTextFor("project")}\n`);
+            return 0;
+        }
+        if (topic) {
+            writeUsageError(stderr, new CliUsageError(`Unknown help topic: ${topic}`));
+            return 1;
+        }
+        writeOutput(stdout, `${rootHelpText()}\n`);
         return 0;
     }
     if (command === "version") {
@@ -181,6 +138,10 @@ export async function runCli(argv, options) {
         writeOutput(stdout, json ? formatJson(buildInfo) : `${buildInfo.version}\n`);
         return 0;
     }
+    if (hasHelpFlag(parsed)) {
+        writeOutput(stdout, `${helpTextFor(command === "project" ? "project" : "root")}\n`);
+        return 0;
+    }
     if (command === "serve") {
         return -1;
     }
@@ -216,15 +177,25 @@ export async function runCli(argv, options) {
         });
     }
     if (command === "project") {
-        return await handleProjectCommand({
-            commandArgs,
-            parsed,
-            json,
-            stdout,
-            stderr,
-            runInteractive,
-            ...(options ? { options } : {}),
-        });
+        try {
+            return await handleProjectCommand({
+                commandArgs,
+                parsed,
+                json,
+                stdout,
+                stderr,
+                runInteractive,
+                ...(options ? { options } : {}),
+            });
+        }
+        catch (error) {
+            if (error instanceof CliUsageError) {
+                writeUsageError(stderr, error);
+                return 1;
+            }
+            writeOutput(stderr, `${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
     }
     const config = options?.config ??
         loadConfig(undefined, {
@@ -233,11 +204,12 @@ export async function runCli(argv, options) {
     let data = options?.data;
     try {
         if (command === "doctor") {
+            const { runPreflight } = await import("../preflight.js");
             const report = await runPreflight(config);
             writeOutput(stdout, json ? formatJson(report) : formatDoctor(report));
             return report.ok ? 0 : 1;
         }
-        data ??= new CliDataAccess(config);
+        data ??= await createCliDataAccess(config);
         if (command === "inspect") {
             return await handleInspectCommand({ commandArgs, parsed, json, stdout, data, config, runInteractive });
         }
@@ -290,6 +262,10 @@ export async function runCli(argv, options) {
         throw new Error(`Unknown command: ${command}`);
     }
     catch (error) {
+        if (error instanceof CliUsageError) {
+            writeUsageError(stderr, error);
+            return 1;
+        }
         writeOutput(stderr, `${error instanceof Error ? error.message : String(error)}\n`);
         return 1;
     }
@@ -299,3 +275,7 @@ export async function runCli(argv, options) {
         }
     }
 }
+async function createCliDataAccess(config) {
+    const { CliDataAccess } = await import("./data.js");
+    return new CliDataAccess(config);
+}

package/dist/cli/output.js

@@ -1,6 +1,10 @@
+import { helpTextFor } from "./help.js";
 export function writeOutput(stream, text) {
     stream.write(text);
 }
+export function writeUsageError(stream, error) {
+    writeOutput(stream, `${helpTextFor(error.helpTopic)}\n\nError: ${error.message}\n`);
+}
 export function formatDoctor(report) {
     const lines = ["PatchRelay doctor", ""];
     for (const check of report.checks) {

package/dist/index.js

@@ -1,22 +1,24 @@
 #!/usr/bin/env node
 import { dirname } from "node:path";
 import { runCli } from "./cli/index.js";
-import { CodexAppServerClient } from "./codex-app-server.js";
-import { getAdjacentEnvFilePaths, loadConfig } from "./config.js";
-import { PatchRelayDatabase } from "./db.js";
-import { enforceRuntimeFilePermissions, enforceServiceEnvPermissions } from "./file-permissions.js";
-import { buildHttpServer } from "./http.js";
-import { DatabaseBackedLinearClientProvider } from "./linear-client.js";
-import { createLogger } from "./logging.js";
-import { runPreflight } from "./preflight.js";
-import { PatchRelayService } from "./service.js";
-import { ensureDir } from "./utils.js";
 async function main() {
     const cliExitCode = await runCli(process.argv.slice(2));
     if (cliExitCode !== -1) {
         process.exitCode = cliExitCode;
         return;
     }
+    const [{ CodexAppServerClient }, { getAdjacentEnvFilePaths, loadConfig }, { PatchRelayDatabase }, { enforceRuntimeFilePermissions, enforceServiceEnvPermissions }, { buildHttpServer }, { DatabaseBackedLinearClientProvider }, { createLogger }, { runPreflight }, { PatchRelayService }, { ensureDir },] = await Promise.all([
+        import("./codex-app-server.js"),
+        import("./config.js"),
+        import("./db.js"),
+        import("./file-permissions.js"),
+        import("./http.js"),
+        import("./linear-client.js"),
+        import("./logging.js"),
+        import("./preflight.js"),
+        import("./service.js"),
+        import("./utils.js"),
+    ]);
     const configPath = process.env.PATCHRELAY_CONFIG;
     const config = loadConfig(configPath);
     await enforceServiceEnvPermissions(getAdjacentEnvFilePaths(configPath).serviceEnvPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchrelay",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "license": "MIT",
   "type": "module",
   "repository": {