jiradc-cli 1.0.21 → 2.0.0-g0cec505.11

package/dist/index.js

@@ -1,16 +1,25 @@
 #!/usr/bin/env node
 
-// src/index.ts
-import { readFileSync } from "fs";
-import { dirname, join as join4 } from "path";
-import { fileURLToPath } from "url";
-import { styleText } from "util";
-import { Command as Command11 } from "commander";
+// ../../cli-utils/dist/cache.js
+import { readFileSync, writeFileSync, mkdirSync, statSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
 
-// src/commands/board/issues.ts
-import { Argument } from "commander";
+// ../../cli-utils/dist/bootstrap.js
+import { readFileSync as readFileSync2 } from "fs";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+function readPackageVersion(importMetaUrl) {
+  try {
+    const here = dirname(fileURLToPath(importMetaUrl));
+    const pkg = JSON.parse(readFileSync2(join2(here, "..", "package.json"), "utf-8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
 
-// src/utils/cli.ts
+// ../../cli-utils/dist/validators.js
 import { InvalidArgumentError } from "commander";
 function intInRange(min, max) {
   return (raw) => {
@@ -39,43 +48,281 @@ function positiveInt(raw) {
   return n;
 }
 
-// src/utils/client.ts
-import { JiraClient } from "jira-data-center-client";
+// ../../cli-utils/dist/registry.js
+var SUB_ENTITY_ID_NUMERIC = {
+  comment: true,
+  worklog: true,
+  attachment: true,
+  request: true,
+  type: true,
+  employee: true,
+  message: false,
+  membership: false
+};
+
+// ../../cli-utils/dist/builders.js
+function defineOption(cmd, flags, description, parser, mandatory) {
+  if (mandatory) {
+    return parser ? cmd.requiredOption(flags, description, parser) : cmd.requiredOption(flags, description);
+  }
+  return parser ? cmd.option(flags, description, parser) : cmd.option(flags, description);
+}
+function subjectArg(cmd, name, opts = {}) {
+  const inner = opts.variadic ? `${name}...` : name;
+  const token = opts.optional ? `[${inner}]` : `<${inner}>`;
+  return opts.parser ? cmd.argument(token, opts.description ?? "", opts.parser) : cmd.argument(token, opts.description ?? "");
+}
+function subEntityOption(cmd, entity, opts = {}) {
+  const numeric = opts.numeric ?? SUB_ENTITY_ID_NUMERIC[entity] ?? true;
+  const description = `${entity.charAt(0).toUpperCase()}${entity.slice(1)} id`;
+  return defineOption(cmd, `--${entity}-id <id>`, description, numeric ? positiveInt : void 0, opts.mandatory);
+}
+function bodyOption(cmd, opts = {}) {
+  return defineOption(cmd, "--body <text>", "Prose body content", void 0, opts.mandatory);
+}
+var EXAMPLES = /* @__PURE__ */ new WeakSet();
+function commandPath(cmd) {
+  const parts = [];
+  for (let c = cmd; c; c = c.parent)
+    parts.unshift(c.name());
+  return parts.join(" ");
+}
+function exampleLine(path, entry) {
+  if (typeof entry === "string")
+    return entry ? `  ${path} ${entry}` : `  ${path}`;
+  if ("raw" in entry)
+    return `  ${entry.raw}`;
+  const [args, comment] = entry;
+  const line = args ? `${path} ${args}` : path;
+  return `  ${line}  # ${comment}`;
+}
+function examples(cmd, entries) {
+  EXAMPLES.add(cmd);
+  return cmd.addHelpText("after", () => {
+    const path = commandPath(cmd);
+    return `
+Examples:
+${entries.map((e) => exampleLine(path, e)).join("\n")}`;
+  });
+}
 
-// src/utils/credentials.ts
-function getCredentialInfo() {
-  const baseUrl = process.env.JIRA_URL;
-  const token = process.env.JIRA_TOKEN;
+// ../../cli-utils/dist/errors.js
+import { CommanderError } from "commander";
+var EXIT = {
+  SUCCESS: 0,
+  GENERIC: 1,
+  USAGE: 2,
+  NOT_FOUND: 3,
+  FORBIDDEN: 4,
+  CONFLICT: 5,
+  AUTH: 6
+};
+var CliAuthError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CliAuthError";
+  }
+};
+var TYPE_EXIT = {
+  usage: EXIT.USAGE,
+  not_found: EXIT.NOT_FOUND,
+  forbidden: EXIT.FORBIDDEN,
+  conflict: EXIT.CONFLICT,
+  auth: EXIT.AUTH,
+  rate_limited: EXIT.GENERIC,
+  server: EXIT.GENERIC,
+  network: EXIT.GENERIC,
+  unknown: EXIT.GENERIC
+};
+var NETWORK_CODES = ["ENOTFOUND", "ECONNREFUSED", "ECONNRESET", "ETIMEDOUT"];
+function httpStatus(err) {
+  const e = err;
+  return e?.response?.status ?? e?.statusCode;
+}
+function responseDetail(err) {
+  const e = err;
+  const data = e?.response?.data;
+  if (data && typeof data === "object")
+    return data;
+  const body = e?.body;
+  if (typeof body === "string") {
+    try {
+      const parsed = JSON.parse(body);
+      return parsed.error ?? parsed;
+    } catch {
+      return void 0;
+    }
+  }
+  if (body && typeof body === "object") {
+    return body.error ?? body;
+  }
+  return void 0;
+}
+function errorCode(err) {
+  return err?.code;
+}
+function normalize(err, opts) {
+  const message = err instanceof Error ? err.message : String(err);
+  if (err instanceof CommanderError) {
+    return {
+      type: "usage",
+      message: message || "Invalid command usage",
+      recovery: "Check the command syntax and flags; run the command with --help.",
+      retryable: false
+    };
+  }
+  if (err instanceof CliAuthError) {
+    return { type: "auth", message: message || "Missing credentials", recovery: opts.authRecovery, retryable: false };
+  }
+  const status = httpStatus(err);
+  const detail = responseDetail(err);
+  if (status !== void 0) {
+    switch (status) {
+      case 400:
+        return {
+          type: "usage",
+          status,
+          message: "Bad request (HTTP 400)",
+          recovery: "Check parameter values (ids, keys, query syntax) against the API.",
+          retryable: false,
+          detail
+        };
+      case 401:
+        return {
+          type: "auth",
+          status,
+          message: "Authentication failed (HTTP 401)",
+          recovery: opts.authRecovery,
+          retryable: false
+        };
+      case 403:
+        return {
+          type: "forbidden",
+          status,
+          message: "Forbidden (HTTP 403)",
+          recovery: `Your ${opts.service} account lacks permission for this operation; check token scope and resource permissions.`,
+          retryable: false,
+          detail
+        };
+      case 404:
+        return {
+          type: "not_found",
+          status,
+          message: "Not found (HTTP 404)",
+          recovery: "Verify the id/key exists and that you have access to it.",
+          retryable: false,
+          detail
+        };
+      case 409:
+        return {
+          type: "conflict",
+          status,
+          message: "Conflict (HTTP 409)",
+          recovery: "The resource changed or already exists; re-fetch current state and retry.",
+          retryable: false,
+          detail
+        };
+      case 429:
+        return {
+          type: "rate_limited",
+          status,
+          message: "Rate limited (HTTP 429)",
+          recovery: "Wait and retry the request.",
+          retryable: true
+        };
+    }
+    if (status >= 500) {
+      return {
+        type: "server",
+        status,
+        message: `Server error (HTTP ${status})`,
+        recovery: `${opts.service} returned an internal error; retry shortly.`,
+        retryable: true,
+        detail
+      };
+    }
+    return {
+      type: "unknown",
+      status,
+      message: `${opts.service} error (HTTP ${status}): ${message}`,
+      recovery: "Inspect the detail field for the API response.",
+      retryable: false,
+      detail
+    };
+  }
+  const code = errorCode(err);
+  if (code && NETWORK_CODES.includes(code) || NETWORK_CODES.some((c) => message.includes(c))) {
+    return {
+      type: "network",
+      message: `Cannot connect to ${opts.service}: ${message}`,
+      recovery: opts.networkRecovery ?? "Verify the *_URL is correct, the server is reachable, and you are on the VPN if required.",
+      retryable: true
+    };
+  }
+  return { type: "unknown", message, recovery: "Unexpected error; inspect the message.", retryable: false };
+}
+function classifyError(err, opts) {
+  const base = normalize(err, opts);
+  const n = opts.adapt ? opts.adapt(base, err) : base;
+  if (n.type === "auth" && n.detail === void 0 && opts.credentialInfo) {
+    n.detail = opts.credentialInfo();
+  }
   return {
-    environment: {
-      JIRA_URL: {
-        value: baseUrl ?? null,
-        description: "Your Jira Server base URL (e.g., https://jira.example.com)"
-      },
-      JIRA_TOKEN: {
-        value: token ? "<set>" : null,
-        description: "Personal Access Token"
+    envelope: {
+      error: {
+        type: n.type,
+        message: n.message,
+        recovery: n.recovery,
+        retryable: n.retryable,
+        ...n.detail !== void 0 ? { detail: n.detail } : {}
       }
     },
-    tokenUrl: `${baseUrl ?? "https://jira.example.com"}/secure/ViewProfile.jspa`,
-    hint: "Export environment variables in your shell profile (e.g., ~/.zshrc)."
+    exitCode: TYPE_EXIT[n.type]
+  };
+}
+function createErrorHandler(opts) {
+  return (err) => {
+    const { envelope, exitCode } = classifyError(err, opts);
+    process.stderr.write(`${JSON.stringify(envelope)}
+`);
+    return process.exit(exitCode);
   };
 }
+function isCleanCommanderExit(err) {
+  return err instanceof CommanderError && (err.exitCode === 0 || err.code === "commander.helpDisplayed" || err.code === "commander.help" || err.code === "commander.version");
+}
+function routeErrors(cmd) {
+  cmd.exitOverride();
+  cmd.configureOutput({ writeErr: () => void 0 });
+  cmd.commands.forEach(routeErrors);
+}
+async function runCli(program, opts) {
+  routeErrors(program);
+  try {
+    await program.parseAsync();
+  } catch (err) {
+    if (isCleanCommanderExit(err)) {
+      process.exit(err.exitCode ?? 0);
+    }
+    createErrorHandler(opts)(err);
+  }
+}
+
+// src/program.ts
+import { styleText } from "util";
+import { Command as Command11 } from "commander";
+
+// src/commands/board/issues.ts
+import { Argument } from "commander";
 
 // src/utils/client.ts
+import { JiraClient } from "jira-data-center-client";
 function getClient() {
   const baseUrl = process.env.JIRA_URL;
   const token = process.env.JIRA_TOKEN;
   if (!baseUrl || !token) {
     const missing = [...!baseUrl ? ["JIRA_URL"] : [], ...!token ? ["JIRA_TOKEN"] : []];
-    process.stderr.write(
-      `${JSON.stringify({
-        error: `Missing required environment variables: ${missing.join(", ")}`,
-        ...getCredentialInfo()
-      })}
-`
-    );
-    process.exit(1);
+    throw new CliAuthError(`Missing required environment variables: ${missing.join(", ")}`);
   }
   return new JiraClient({ baseUrl, token });
 }
@@ -89,68 +336,6 @@ function output(data) {
   process.stdout.write(`${JSON.stringify(data, null, prettyPrint ? 2 : void 0)}
 `);
 }
-function handleError(err) {
-  const message = err instanceof Error ? err.message : String(err);
-  const axiosStatus = err?.response?.status;
-  if (axiosStatus === 400) {
-    const responseData = err?.response?.data;
-    const jiraErrors = responseData && typeof responseData === "object" ? responseData : void 0;
-    process.stderr.write(
-      `${JSON.stringify({
-        error: `Bad request (HTTP 400)`,
-        detail: jiraErrors ?? message,
-        hint: "Check that all parameters are valid (JQL syntax, field names, project keys, etc.)."
-      })}
-`
-    );
-  } else if (axiosStatus === 401) {
-    process.stderr.write(
-      `${JSON.stringify({
-        error: "Authentication failed (HTTP 401)",
-        ...getCredentialInfo()
-      })}
-`
-    );
-  } else if (axiosStatus === 403) {
-    const responseData = err?.response?.data;
-    process.stderr.write(
-      `${JSON.stringify({
-        error: "Forbidden (HTTP 403)",
-        detail: responseData && typeof responseData === "object" ? responseData : message,
-        hint: "Your account does not have permission for this operation. Check project permissions and token scope."
-      })}
-`
-    );
-  } else if (message.includes("ENOTFOUND") || message.includes("ECONNREFUSED") || message.includes("ECONNRESET")) {
-    process.stderr.write(
-      `${JSON.stringify({
-        error: `Cannot connect to Jira server: ${message}`,
-        hint: "Verify that JIRA_URL is correct and the server is reachable."
-      })}
-`
-    );
-  } else if (axiosStatus === 500) {
-    process.stderr.write(
-      `${JSON.stringify({
-        error: `Server error (HTTP 500): ${message}`,
-        hint: "The server returned an internal error. Check that all parameters are valid (project keys, issue keys, JQL query syntax)."
-      })}
-`
-    );
-  } else {
-    const responseData = err?.response?.data;
-    const detail = responseData && typeof responseData === "object" ? responseData : void 0;
-    process.stderr.write(
-      `${JSON.stringify({
-        error: message,
-        ...axiosStatus !== void 0 && { statusCode: axiosStatus },
-        ...detail && { detail }
-      })}
-`
-    );
-  }
-  process.exit(1);
-}
 
 // src/utils/transformers/base.ts
 function jiraBaseUrl() {
@@ -477,10 +662,14 @@ function transformTransitions(response) {
 
 // src/commands/board/issues.ts
 function issues(parent) {
-  parent.command("issues").description("Get issues for a board").addArgument(new Argument("<id>", "Board ID").argParser(positiveInt)).option("--limit <number>", "Max results (1-50, Jira DC caps at 50)", intInRange(1, 50), 25).option("--start <number>", "Starting index for pagination", nonNegativeInt).option("--fields <fields>", "Comma-separated field names to return").option("--jql <jql>", "Additional JQL filter within the board").addHelpText(
-    "after",
-    '\nExamples:\n  jiradc board issues 42\n  jiradc board issues 42 --limit 10\n  jiradc board issues 42 --jql "status = Open" --fields summary,status\n  jiradc board issues 42 --start 50 --limit 25'
-  ).action(async (id, opts) => {
+  const cmd = parent.command("issues").description("Get issues for a board").addArgument(new Argument("<id>", "Board ID").argParser(positiveInt)).option("--limit <number>", "Max results (1-50, Jira DC caps at 50)", intInRange(1, 50), 25).option("--start <number>", "Starting index for pagination", nonNegativeInt).option("--fields <fields>", "Comma-separated field names to return").option("--jql <jql>", "Additional JQL filter within the board");
+  examples(cmd, [
+    "42",
+    "42 --limit 10",
+    '42 --jql "status = Open" --fields summary,status',
+    "42 --start 50 --limit 25"
+  ]);
+  cmd.action(async (id, opts) => {
     const client = getClient();
     const result = await client.agile.getBoardIssues({
       boardId: id,
@@ -497,10 +686,9 @@ function issues(parent) {
 import { Option } from "commander";
 var BOARD_TYPES = ["scrum", "kanban", "simple"];
 function list(parent) {
-  parent.command("list").description("List agile boards").option("--limit <number>", "Max results (1-1000)", intInRange(1, 1e3), 25).option("--project <key>", "Filter boards by project key or ID").addOption(new Option("--type <type>", "Board type filter").choices(BOARD_TYPES)).option("--name <name>", "Filter boards by name").addHelpText(
-    "after",
-    '\nExamples:\n  jiradc board list\n  jiradc board list --limit 10\n  jiradc board list --project PROJ\n  jiradc board list --type scrum --name "Team Board"'
-  ).action(async (opts) => {
+  const cmd = parent.command("list").description("List agile boards").option("--limit <number>", "Max results (1-1000)", intInRange(1, 1e3), 25).option("--project <key>", "Filter boards by project key or ID").addOption(new Option("--type <type>", "Board type filter").choices(BOARD_TYPES)).option("--name <name>", "Filter boards by name");
+  examples(cmd, ["", "--limit 10", "--project PROJ", '--type scrum --name "Team Board"']);
+  cmd.action(async (opts) => {
     const client = getClient();
     const result = await client.agile.getBoards({
       maxResults: opts.limit,
@@ -513,16 +701,9 @@ function list(parent) {
 }
 
 // src/commands/board/index.ts
-function registerBoardCommands(program2) {
-  const board = program2.command("board").description("Board operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ jiradc board list
-  $ jiradc board list --type scrum --project PROJ
-  $ jiradc board issues 42 --limit 20
-`
-  );
+function registerBoardCommands(program) {
+  const board = program.command("board").description("Board operations");
+  examples(board, ["list", "list --type scrum --project PROJ", "issues 42 --limit 20"]);
   list(board);
   issues(board);
 }
@@ -536,14 +717,13 @@ var ASSIGNEE_TYPES = [
   "UNASSIGNED"
 ];
 function create(parent) {
-  parent.command("create").description("Create a new component in a project").requiredOption("--project <key>", "Project key (e.g., AI)").requiredOption("--name <name>", "Component name").option("--description <text>", "Component description").option("--lead <username>", "Username of the component lead").addOption(new Option2("--assignee-type <type>", "Assignee strategy").choices(ASSIGNEE_TYPES)).addHelpText(
-    "after",
-    `
-Examples:
-  jiradc component create --project AI --name Backend
-  jiradc component create --project AI --name Frontend --description "UI work" --lead jsmith
-  jiradc component create --project AI --name Infra --assignee-type COMPONENT_LEAD --lead jsmith`
-  ).action(
+  const cmd = parent.command("create").description("Create a new component in a project").requiredOption("--project <key>", "Project key (e.g., AI)").requiredOption("--name <name>", "Component name").option("--description <text>", "Component description").option("--lead <username>", "Username of the component lead").addOption(new Option2("--assignee-type <type>", "Assignee strategy").choices(ASSIGNEE_TYPES));
+  examples(cmd, [
+    "--project AI --name Backend",
+    '--project AI --name Frontend --description "UI work" --lead jsmith',
+    "--project AI --name Infra --assignee-type COMPONENT_LEAD --lead jsmith"
+  ]);
+  cmd.action(
     async (opts) => {
       const client = getClient();
       const result = await client.components.create({
@@ -560,13 +740,9 @@ Examples:
 
 // src/commands/component/delete.ts
 function deleteComponent(parent) {
-  parent.command("delete <id>").description("Delete a component, optionally reassigning its issues to another component").option("--move-issues-to <id>", "Reassign existing issues to this component ID before deletion").addHelpText(
-    "after",
-    `
-Examples:
-  jiradc component delete 11289
-  jiradc component delete 11289 --move-issues-to 11290`
-  ).action(async (id, opts) => {
+  const cmd = parent.command("delete <id>").description("Delete a component, optionally reassigning its issues to another component").option("--move-issues-to <id>", "Reassign existing issues to this component ID before deletion");
+  examples(cmd, ["11289", "11289 --move-issues-to 11290"]);
+  cmd.action(async (id, opts) => {
     const client = getClient();
     await client.components.delete({ id, moveIssuesTo: opts.moveIssuesTo });
     output({ deleted: true, componentId: id, ...opts.moveIssuesTo && { movedIssuesTo: opts.moveIssuesTo } });
@@ -575,7 +751,9 @@ Examples:
 
 // src/commands/component/get.ts
 function get(parent) {
-  parent.command("get <id>").description("Get a component by ID").addHelpText("after", "\nExamples:\n  jiradc component get 11289").action(async (id) => {
+  const cmd = parent.command("get <id>").description("Get a component by ID");
+  examples(cmd, ["11289"]);
+  cmd.action(async (id) => {
     const client = getClient();
     const result = await client.components.get({ id });
     output(transformComponent(result));
@@ -584,7 +762,9 @@ function get(parent) {
 
 // src/commands/component/issue-count.ts
 function issueCount(parent) {
-  parent.command("issue-count <id>").description("Get the number of issues currently using this component").addHelpText("after", "\nExamples:\n  jiradc component issue-count 11289").action(async (id) => {
+  const cmd = parent.command("issue-count <id>").description("Get the number of issues currently using this component");
+  examples(cmd, ["11289"]);
+  cmd.action(async (id) => {
     const client = getClient();
     const result = await client.components.getRelatedIssueCounts({ id });
     output(transformComponentIssueCounts(result));
@@ -593,7 +773,9 @@ function issueCount(parent) {
 
 // src/commands/component/list.ts
 function list2(parent) {
-  parent.command("list").description("List all components for a project").requiredOption("--project <key>", "Project key (e.g., AI)").addHelpText("after", "\nExamples:\n  jiradc component list --project AI").action(async (opts) => {
+  const cmd = parent.command("list").description("List all components for a project").requiredOption("--project <key>", "Project key (e.g., AI)");
+  examples(cmd, ["--project AI"]);
+  cmd.action(async (opts) => {
     const client = getClient();
     const result = await client.components.list({ projectKeyOrId: opts.project });
     output(result.map(transformComponent));
@@ -609,14 +791,13 @@ var ASSIGNEE_TYPES2 = [
   "UNASSIGNED"
 ];
 function update(parent) {
-  parent.command("update <id>").description("Update an existing component (only provided fields are changed)").option("--name <name>", "New component name").option("--description <text>", "New component description").option("--lead <username>", "Username of the component lead (empty string clears it)").addOption(new Option3("--assignee-type <type>", "New assignee strategy").choices(ASSIGNEE_TYPES2)).addHelpText(
-    "after",
-    `
-Examples:
-  jiradc component update 11289 --name Backend
-  jiradc component update 11289 --description "Server-side code"
-  jiradc component update 11289 --lead jsmith --assignee-type COMPONENT_LEAD`
-  ).action(
+  const cmd = parent.command("update <id>").description("Update an existing component (only provided fields are changed)").option("--name <name>", "New component name").option("--description <text>", "New component description").option("--lead <username>", "Username of the component lead (empty string clears it)").addOption(new Option3("--assignee-type <type>", "New assignee strategy").choices(ASSIGNEE_TYPES2));
+  examples(cmd, [
+    "11289 --name Backend",
+    '11289 --description "Server-side code"',
+    "11289 --lead jsmith --assignee-type COMPONENT_LEAD"
+  ]);
+  cmd.action(
     async (id, opts) => {
       if (opts.name === void 0 && opts.description === void 0 && opts.lead === void 0 && opts.assigneeType === void 0) {
         throw new Error("Provide at least one of --name, --description, --lead, --assignee-type");
@@ -635,19 +816,16 @@ Examples:
 }
 
 // src/commands/component/index.ts
-function registerComponentCommands(program2) {
-  const component = program2.command("component").description("Project component operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ jiradc component list --project AI
-  $ jiradc component get 11289
-  $ jiradc component create --project AI --name Backend
-  $ jiradc component update 11289 --name Backend
-  $ jiradc component delete 11289 --move-issues-to 11290
-  $ jiradc component issue-count 11289
-`
-  );
+function registerComponentCommands(program) {
+  const component = program.command("component").description("Project component operations");
+  examples(component, [
+    "list --project AI",
+    "get 11289",
+    "create --project AI --name Backend",
+    "update 11289 --name Backend",
+    "delete 11289 --move-issues-to 11290",
+    "issue-count 11289"
+  ]);
   list2(component);
   get(component);
   create(component);
@@ -658,16 +836,15 @@ Examples:
 
 // src/commands/field/options.ts
 function options(parent) {
-  parent.command("options <id>").description("Get available options for a custom field").option("--query <text>", "Filter options by text").option("--limit <number>", "Max results to return (1-1000)", intInRange(1, 1e3), 25).option("--page <number>", "Page number (1-indexed)", positiveInt).addHelpText(
-    "after",
-    '\nExamples:\n  jiradc field options 10001\n  jiradc field options 10001 --query "High"\n  jiradc field options 10001 --limit 20 --page 2'
-  ).action(async (id, opts) => {
+  const cmd = parent.command("options <id>").description("Get available options for a custom field").option("--query <text>", "Filter options by text").option("--limit <number>", "Max results to return (1-1000)", intInRange(1, 1e3), 25).option("--start <number>", "Page number (1-indexed)", positiveInt);
+  examples(cmd, ["10001", '10001 --query "High"', "10001 --limit 20 --start 2"]);
+  cmd.action(async (id, opts) => {
     const client = getClient();
     const result = await client.fields.getFieldOptions({
       fieldId: id,
       query: opts.query,
       maxResults: opts.limit,
-      page: opts.page
+      page: opts.start
     });
     output(transformPaged({ ...result, startAt: result.startAt ?? 0 }, transformCustomFieldOption));
   });
@@ -675,10 +852,9 @@ function options(parent) {
 
 // src/commands/field/search.ts
 function search(parent) {
-  parent.command("search <keyword>").description("Search for fields by name or ID").option("--limit <number>", "Maximum number of results (1-1000)", intInRange(1, 1e3), 25).addHelpText(
-    "after",
-    "\nExamples:\n  jiradc field search epic\n  jiradc field search customfield_10100\n  jiradc field search priority --limit 5"
-  ).action(async (keyword, opts) => {
+  const cmd = parent.command("search <keyword>").description("Search for fields by name or ID").option("--limit <number>", "Maximum number of results (1-1000)", intInRange(1, 1e3), 25);
+  examples(cmd, ["epic", "customfield_10100", "priority --limit 5"]);
+  cmd.action(async (keyword, opts) => {
     const client = getClient();
     const result = await client.fields.search(keyword, opts.limit);
     output(result.map(transformField));
@@ -686,16 +862,9 @@ function search(parent) {
 }
 
 // src/commands/field/index.ts
-function registerFieldCommands(program2) {
-  const field = program2.command("field").description("Field operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ jiradc field search "epic"
-  $ jiradc field search "priority"
-  $ jiradc field options 10120
-`
-  );
+function registerFieldCommands(program) {
+  const field = program.command("field").description("Field operations");
+  examples(field, ['search "epic"', 'search "priority"', "options 10120"]);
   search(field);
   options(field);
 }
@@ -718,15 +887,10 @@ async function resolveUserToken(token) {
 
 // src/commands/issue/assign.ts
 function assign(parent) {
-  parent.command("assign <key> <user>").description('Assign an issue. <user> is a username, "me", or "none" to unassign.').addHelpText(
-    "after",
-    `
-Examples:
-  jiradc issue assign PROJ-123 jsmith
-  jiradc issue assign PROJ-123 me
-  jiradc issue assign PROJ-123 none`
-  ).action(async (key, user) => {
-    const resolved = await resolveUserToken(user);
+  const cmd = parent.command("assign <key>").description('Assign an issue. --assignee is a username, "me", or "none" to unassign.').requiredOption("--assignee <user>", 'Username to assign, "me" for the current user, or "none" to unassign');
+  examples(cmd, ["PROJ-123 --assignee jsmith", "PROJ-123 --assignee me", "PROJ-123 --assignee none"]);
+  cmd.action(async (key, opts) => {
+    const resolved = await resolveUserToken(opts.assignee);
     const client = getClient();
     await client.issues.update({
       issueKeyOrId: key,
@@ -738,20 +902,25 @@ Examples:
 
 // src/commands/issue/attachment/delete.ts
 function deleteAttachment(parent) {
-  parent.command("delete").description("Delete an attachment by ID").requiredOption("--id <attachmentId>", "Attachment ID to delete").addHelpText("after", "\nExamples:\n  jiradc issue attachment delete --id 12345").action(async (opts) => {
+  const cmd = parent.command("delete <key>").description("Delete an attachment by ID");
+  subEntityOption(cmd, "attachment", { mandatory: true });
+  examples(cmd, ["PROJ-123 --attachment-id 12345"]);
+  cmd.action(async (key, opts) => {
     const client = getClient();
-    await client.issues.deleteAttachment({ attachmentId: opts.id });
-    output({ deleted: true, attachmentId: opts.id });
+    await client.issues.deleteAttachment({ attachmentId: String(opts.attachmentId) });
+    output({ deleted: true, issueKey: key, attachmentId: opts.attachmentId });
   });
 }
 
 // src/commands/issue/attachment/download-all.ts
-import { mkdirSync } from "fs";
-import { join } from "path";
+import { mkdirSync as mkdirSync2 } from "fs";
+import { join as join3 } from "path";
 function downloadAll(parent) {
-  parent.command("download-all <key>").description("Download all attachments from an issue").requiredOption("--output <dir>", "Local directory to save attachments into").addHelpText("after", "\nExamples:\n  jiradc issue attachment download-all PROJ-123 --output ./downloads").action(async (key, opts) => {
+  const cmd = parent.command("download-all <key>").description("Download all attachments from an issue").requiredOption("--output <dir>", "Local directory to save attachments into");
+  examples(cmd, ["PROJ-123 --output ./downloads"]);
+  cmd.action(async (key, opts) => {
     const client = getClient();
-    mkdirSync(opts.output, { recursive: true });
+    mkdirSync2(opts.output, { recursive: true });
     const issue = await client.issues.get({
       issueKeyOrId: key,
       fields: ["attachment"]
@@ -768,7 +937,7 @@ function downloadAll(parent) {
         failed.push({ filename: att.filename, error: "No content URL" });
         continue;
       }
-      const destPath = join(opts.output, att.filename);
+      const destPath = join3(opts.output, att.filename);
       try {
         await client.issues.downloadAttachment({ url: att.content, destinationPath: destPath });
         results.push({ filename: att.filename, size: att.size, path: destPath });
@@ -788,11 +957,16 @@ function downloadAll(parent) {
 
 // src/commands/issue/attachment/download.ts
 function download(parent) {
-  parent.command("download <key>").description("Download a single attachment by ID").requiredOption("--id <attachmentId>", "Attachment ID").requiredOption("--output <path>", "Local file path to save the attachment").addHelpText("after", "\nExamples:\n  jiradc issue attachment download PROJ-123 --id 12345 --output ./report.pdf").action(async (key, opts) => {
+  const cmd = parent.command("download <key>").description("Download a single attachment by ID");
+  subEntityOption(cmd, "attachment", { mandatory: true });
+  cmd.requiredOption("--output <path>", "Local file path to save the attachment");
+  examples(cmd, ["PROJ-123 --attachment-id 12345 --output ./report.pdf"]);
+  cmd.action(async (key, opts) => {
     const client = getClient();
-    const attachment = await client.issues.getAttachment({ attachmentId: opts.id });
+    const attachmentId = String(opts.attachmentId);
+    const attachment = await client.issues.getAttachment({ attachmentId });
     if (!attachment.content) {
-      throw new Error(`Attachment ${opts.id} has no content URL`);
+      throw new Error(`Attachment ${attachmentId} has no content URL`);
     }
     await client.issues.downloadAttachment({
       url: attachment.content,
@@ -810,7 +984,9 @@ function download(parent) {
 
 // src/commands/issue/attachment/list.ts
 function list3(parent) {
-  parent.command("list <key>").description("List attachments on an issue").addHelpText("after", "\nExamples:\n  jiradc issue attachment list PROJ-123").action(async (key) => {
+  const cmd = parent.command("list <key>").description("List attachments on an issue");
+  examples(cmd, ["PROJ-123"]);
+  cmd.action(async (key) => {
     const client = getClient();
     const issue = await client.issues.get({
       issueKeyOrId: key,
@@ -833,16 +1009,15 @@ function list3(parent) {
 
 // src/commands/issue/attachment/upload.ts
 function upload(parent) {
-  parent.command("upload <key>").description("Upload attachments to an issue").requiredOption("--files <paths>", "Comma-separated file paths to upload").addHelpText(
-    "after",
-    "\nExamples:\n  jiradc issue attachment upload PROJ-123 --files ./report.pdf\n  jiradc issue attachment upload PROJ-123 --files ./a.txt,./b.png"
-  ).action(async (key, opts) => {
+  const cmd = parent.command("upload <key>").description("Upload attachments to an issue").requiredOption("--files <paths>", "Comma-separated file paths to upload");
+  examples(cmd, ["PROJ-123 --files ./report.pdf", "PROJ-123 --files ./a.txt,./b.png"]);
+  cmd.action(async (key, opts) => {
     const client = getClient();
     const filePaths = opts.files.split(",").map((f) => f.trim());
     const results = [];
     for (const filePath of filePaths) {
-      const attachments2 = await client.issues.addAttachment({ issueKeyOrId: key, filePath });
-      results.push(...attachments2);
+      const attachments = await client.issues.addAttachment({ issueKeyOrId: key, filePath });
+      results.push(...attachments);
     }
     output({
       issueKey: key,
@@ -860,17 +1035,14 @@ function upload(parent) {
 
 // src/commands/issue/attachment/index.ts
 function registerAttachmentCommands(parent) {
-  const attachment = parent.command("attachment").description("Attachment operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ jiradc issue attachment list PROJ-123
-  $ jiradc issue attachment upload PROJ-123 --files ./report.pdf
-  $ jiradc issue attachment download PROJ-123 --id 12345 --output ./report.pdf
-  $ jiradc issue attachment download-all PROJ-123 --output ./downloads
-  $ jiradc issue attachment delete --id 12345
-`
-  );
+  const attachment = parent.command("attachment").description("Attachment operations");
+  examples(attachment, [
+    "list PROJ-123",
+    "upload PROJ-123 --files ./report.pdf",
+    "download PROJ-123 --attachment-id 12345 --output ./report.pdf",
+    "download-all PROJ-123 --output ./downloads",
+    "delete PROJ-123 --attachment-id 12345"
+  ]);
   upload(attachment);
   list3(attachment);
   download(attachment);
@@ -878,53 +1050,11 @@ Examples:
   deleteAttachment(attachment);
 }
 
-// src/commands/issue/attachments.ts
-import { mkdirSync as mkdirSync2 } from "fs";
-import { join as join2 } from "path";
-function attachments(parent) {
-  parent.command("attachments <key>").description("Download all attachments from an issue").requiredOption("--output <dir>", "Local directory to save attachments into").addHelpText("after", "\nExamples:\n  jiradc issue attachments PROJ-123 --output ./downloads").action(async (key, opts) => {
-    const client = getClient();
-    mkdirSync2(opts.output, { recursive: true });
-    const issue = await client.issues.get({
-      issueKeyOrId: key,
-      fields: ["attachment"]
-    });
-    const atts = issue.fields.attachment ?? [];
-    if (atts.length === 0) {
-      output({ issueKey: key, downloaded: 0, files: [] });
-      return;
-    }
-    const results = [];
-    const failed = [];
-    for (const att of atts) {
-      if (!att.content) {
-        failed.push({ filename: att.filename, error: "No content URL" });
-        continue;
-      }
-      const destPath = join2(opts.output, att.filename);
-      try {
-        await client.issues.downloadAttachment({ url: att.content, destinationPath: destPath });
-        results.push({ filename: att.filename, size: att.size, path: destPath });
-      } catch (err) {
-        failed.push({ filename: att.filename, error: String(err) });
-      }
-    }
-    output({
-      issueKey: key,
-      downloaded: results.length,
-      total: atts.length,
-      files: results,
-      ...failed.length > 0 && { failed }
-    });
-  });
-}
-
 // src/commands/issue/batch-changelog.ts
 function batchChangelog(parent) {
-  parent.command("batch-changelog <keys>").description("Get changelogs for multiple issues at once").option("--limit <number>", "Max changelog entries per issue (1-50, Jira DC caps at 50)", intInRange(1, 50), 25).addHelpText(
-    "after",
-    "\nExamples:\n  jiradc issue batch-changelog PROJ-1,PROJ-2,PROJ-3\n  jiradc issue batch-changelog PROJ-123,PROJ-124 --limit 10"
-  ).action(async (keys, opts) => {
+  const cmd = parent.command("batch-changelog <keys>").description("Get changelogs for multiple issues at once").option("--limit <number>", "Max changelog entries per issue (1-50, Jira DC caps at 50)", intInRange(1, 50), 25);
+  examples(cmd, ["PROJ-1,PROJ-2,PROJ-3", "PROJ-123,PROJ-124 --limit 10"]);
+  cmd.action(async (keys, opts) => {
     const client = getClient();
     const keyList = keys.split(",").map((k) => k.trim());
     const entries = await Promise.all(
@@ -943,12 +1073,11 @@ function batchChangelog(parent) {
 
 // src/commands/issue/batch-create.ts
 function batchCreate(parent) {
-  parent.command("batch-create").description("Create multiple issues from a JSON array").requiredOption("--issues <json>", "JSON array of issue objects").addHelpText(
-    "after",
-    `
-Examples:
-  jiradc issue batch-create --issues '[{"projectKeyOrId":"PROJ","issueTypeName":"Task","summary":"Task 1"},{"projectKeyOrId":"PROJ","issueTypeName":"Task","summary":"Task 2"}]'`
-  ).action(async (opts) => {
+  const cmd = parent.command("batch-create").description("Create multiple issues from a JSON array").requiredOption("--issues <json>", "JSON array of issue objects");
+  examples(cmd, [
+    `--issues '[{"projectKeyOrId":"PROJ","issueTypeName":"Task","summary":"Task 1"},{"projectKeyOrId":"PROJ","issueTypeName":"Task","summary":"Task 2"}]'`
+  ]);
+  cmd.action(async (opts) => {
     const client = getClient();
     const parsed = JSON.parse(opts.issues);
     const results = [];
@@ -966,10 +1095,9 @@ Examples:
 
 // src/commands/issue/changelog.ts
 function changelog(parent) {
-  parent.command("changelog <key>").description("Get changelog for an issue").option("--limit <number>", "Max changelog entries (1-50, Jira DC caps at 50)", intInRange(1, 50), 25).addHelpText(
-    "after",
-    "\nExamples:\n  jiradc issue changelog PROJ-123\n  jiradc issue changelog PROJ-123 --limit 10"
-  ).action(async (key, opts) => {
+  const cmd = parent.command("changelog <key>").description("Get changelog for an issue").option("--limit <number>", "Max changelog entries (1-50, Jira DC caps at 50)", intInRange(1, 50), 25);
+  examples(cmd, ["PROJ-123", "PROJ-123 --limit 10"]);
+  cmd.action(async (key, opts) => {
     const client = getClient();
     const result = await client.issues.getChangelog({ issueKeyOrId: key, maxResults: opts.limit });
     output(result);
@@ -979,7 +1107,7 @@ function changelog(parent) {
 // src/commands/issue/clone.ts
 import { unlink } from "fs/promises";
 import { tmpdir } from "os";
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 var CLONE_FIELDS = [
   "summary",
   "description",
@@ -995,14 +1123,13 @@ var CLONE_FIELDS = [
   "issuelinks"
 ];
 function clone(parent) {
-  parent.command("clone <key>").description("Clone an issue (create a duplicate with the same fields)").option("--summary <text>", 'Override the summary (default: "CLONE - <original>")').option("--project <key>", "Create in a different project").option("--assignee <username>", "Override assignee").option("--include-attachments", "Copy attachments to the cloned issue").option("--include-links", "Copy issue links to the cloned issue").addHelpText(
-    "after",
-    `
-Examples:
-  jiradc issue clone PROJ-123
-  jiradc issue clone PROJ-123 --summary "Cloned: new title"
-  jiradc issue clone PROJ-123 --include-attachments --include-links`
-  ).action(
+  const cmd = parent.command("clone <key>").description("Clone an issue (create a duplicate with the same fields)").option("--summary <text>", 'Override the summary (default: "CLONE - <original>")').option("--project <key>", "Create in a different project").option("--assignee <username>", "Override assignee").option("--include-attachments", "Copy attachments to the cloned issue").option("--include-links", "Copy issue links to the cloned issue");
+  examples(cmd, [
+    "PROJ-123",
+    'PROJ-123 --summary "Cloned: new title"',
+    "PROJ-123 --include-attachments --include-links"
+  ]);
+  cmd.action(
     async (key, opts) => {
       const client = getClient();
       const source = await client.issues.get({ issueKeyOrId: key, fields: CLONE_FIELDS });
@@ -1030,7 +1157,7 @@ Examples:
         const tmpFiles = [];
         const copied = await Promise.all(
           f.attachment.map(async (att) => {
-            const tmpPath = join3(tmpdir(), `jiradc-clone-${Date.now()}-${att.filename}`);
+            const tmpPath = join4(tmpdir(), `jiradc-clone-${Date.now()}-${att.filename}`);
             tmpFiles.push(tmpPath);
             await client.issues.downloadAttachment({ url: att.content, destinationPath: tmpPath });
             await client.issues.addAttachment({ issueKeyOrId: newKey, filePath: tmpPath });
@@ -1071,9 +1198,12 @@ Examples:
   );
 }
 
-// src/commands/issue/comment/add.ts
-function add(parent) {
-  parent.command("add <key>").description("Add a comment to an issue").requiredOption("--body <text>", "Comment body in wiki markup").addHelpText("after", '\nExamples:\n  jiradc issue comment add PROJ-123 --body "Fixed in latest build"').action(async (key, opts) => {
+// src/commands/issue/comment/create.ts
+function create2(parent) {
+  const cmd = parent.command("create <key>").description("Add a comment to an issue");
+  bodyOption(cmd, { mandatory: true });
+  examples(cmd, ['PROJ-123 --body "Fixed in latest build"']);
+  cmd.action(async (key, opts) => {
     const client = getClient();
     const result = await client.issues.addComment({ issueKeyOrId: key, body: opts.body });
     output(transformComment(result));
@@ -1082,49 +1212,55 @@ function add(parent) {
 
 // src/commands/issue/comment/delete.ts
 function deleteComment(parent) {
-  parent.command("delete <key>").description("Delete a comment from an issue").requiredOption("--id <commentId>", "Comment ID to delete").addHelpText("after", "\nExamples:\n  jiradc issue comment delete PROJ-123 --id 12345").action(async (key, opts) => {
+  const cmd = parent.command("delete <key>").description("Delete a comment from an issue");
+  subEntityOption(cmd, "comment", { mandatory: true });
+  examples(cmd, ["PROJ-123 --comment-id 12345"]);
+  cmd.action(async (key, opts) => {
     const client = getClient();
-    await client.issues.deleteComment({ issueKeyOrId: key, commentId: opts.id });
-    output({ deleted: true, issueKey: key, commentId: opts.id });
+    await client.issues.deleteComment({ issueKeyOrId: key, commentId: String(opts.commentId) });
+    output({ deleted: true, issueKey: key, commentId: opts.commentId });
   });
 }
 
-// src/commands/issue/comment/edit.ts
-function edit(parent) {
-  parent.command("edit <key>").description("Edit an existing comment").requiredOption("--id <commentId>", "Comment ID to edit").requiredOption("--body <text>", "Updated comment body in wiki markup").addHelpText("after", '\nExamples:\n  jiradc issue comment edit PROJ-123 --id 12345 --body "Updated comment text"').action(async (key, opts) => {
+// src/commands/issue/comment/update.ts
+function update2(parent) {
+  const cmd = parent.command("update <key>").description("Update an existing comment");
+  subEntityOption(cmd, "comment", { mandatory: true });
+  bodyOption(cmd, { mandatory: true });
+  examples(cmd, ['PROJ-123 --comment-id 12345 --body "Updated comment text"']);
+  cmd.action(async (key, opts) => {
     const client = getClient();
-    const result = await client.issues.editComment({ issueKeyOrId: key, commentId: opts.id, body: opts.body });
+    const result = await client.issues.editComment({
+      issueKeyOrId: key,
+      commentId: String(opts.commentId),
+      body: opts.body
+    });
     output(transformComment(result));
   });
 }
 
 // src/commands/issue/comment/index.ts
 function registerCommentCommands(parent) {
-  const comment = parent.command("comment").description("Comment operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ jiradc issue comment add PROJ-123 --body "Fixed in latest build"
-  $ jiradc issue comment edit PROJ-123 --id 12345 --body "Updated comment text"
-  $ jiradc issue comment delete PROJ-123 --id 12345
-`
-  );
-  add(comment);
-  edit(comment);
+  const comment = parent.command("comment").description("Comment operations");
+  examples(comment, [
+    'create PROJ-123 --body "Fixed in latest build"',
+    'update PROJ-123 --comment-id 12345 --body "Updated comment text"',
+    "delete PROJ-123 --comment-id 12345"
+  ]);
+  create2(comment);
+  update2(comment);
   deleteComment(comment);
 }
 
 // src/commands/issue/create.ts
-function create2(parent) {
-  parent.command("create").description("Create a new issue").requiredOption("--project <key>", "Project key or ID").requiredOption("--type <name>", "Issue type name (e.g., Task, Bug, Story)").requiredOption("--summary <text>", "Issue summary/title").option("--description <text>", "Issue description in wiki markup").option("--assignee <username>", "Assignee username").option("--reporter <username>", "Reporter username").option("--priority <name>", "Priority name (e.g., High, Medium, Low)").option("--labels <labels>", "Comma-separated labels").option("--components <names>", "Comma-separated component names").option("--fix-versions <versions>", "Comma-separated fix version names").option("--due-date <date>", "Due date in YYYY-MM-DD format").option("--parent <key>", "Parent issue key (for subtasks)").option("--custom-fields <json>", `Additional custom fields as JSON (e.g., '{"customfield_10100": "EPIC-1"}')`).addHelpText(
-    "after",
-    `
-Examples:
-  jiradc issue create --project PROJ --type Task --summary "Fix login bug"
-  jiradc issue create --project PROJ --type Story --summary "New feature" --assignee jsmith --priority High
-  jiradc issue create --project PROJ --type Task --summary "Epic child" --custom-fields '{"customfield_10100": "PROJ-123"}'
-  jiradc issue create --project PROJ --type Bug --summary "Urgent" --labels urgent,production --components Backend`
-  ).action(
+function create3(parent) {
+  const cmd = parent.command("create").description("Create a new issue").requiredOption("--project <key>", "Project key or ID").requiredOption("--type <name>", "Issue type name (e.g., Task, Bug, Story)").requiredOption("--summary <text>", "Issue summary/title").option("--description <text>", "Issue description in wiki markup").option("--assignee <username>", "Assignee username").option("--reporter <username>", "Reporter username").option("--priority <name>", "Priority name (e.g., High, Medium, Low)").option("--labels <labels>", "Comma-separated labels").option("--components <names>", "Comma-separated component names").option("--fix-versions <versions>", "Comma-separated fix version names").option("--due-date <date>", "Due date in YYYY-MM-DD format").option("--parent <key>", "Parent issue key (for subtasks)").option("--custom-fields <json>", `Additional custom fields as JSON (e.g., '{"customfield_10100": "EPIC-1"}')`);
+  examples(cmd, [
+    '--project PROJ --type Task --summary "Fix login bug"',
+    '--project PROJ --type Story --summary "New feature" --assignee jsmith --priority High',
+    '--project PROJ --type Bug --summary "Urgent" --labels urgent,production --components Backend'
+  ]);
+  cmd.action(
     async (opts) => {
       const client = getClient();
       const result = await client.issues.create({
@@ -1149,10 +1285,9 @@ Examples:
 
 // src/commands/issue/delete.ts
 function deleteIssue(parent) {
-  parent.command("delete <key>").description("Delete an issue").option("--delete-subtasks", "Also delete subtasks (default: false)").addHelpText(
-    "after",
-    "\nExamples:\n  jiradc issue delete PROJ-123\n  jiradc issue delete PROJ-123 --delete-subtasks"
-  ).action(async (key, opts) => {
+  const cmd = parent.command("delete <key>").description("Delete an issue").option("--delete-subtasks", "Also delete subtasks (default: false)");
+  examples(cmd, ["PROJ-123", "PROJ-123 --delete-subtasks"]);
+  cmd.action(async (key, opts) => {
     const client = getClient();
     await client.issues.delete({ issueKeyOrId: key, deleteSubtasks: opts.deleteSubtasks });
     output({ deleted: true, issueKey: key });
@@ -1161,10 +1296,9 @@ function deleteIssue(parent) {
 
 // src/commands/issue/dev-status.ts
 function devStatus(parent) {
-  parent.command("dev-status <key>").description("Get development status (PRs, commits, branches, builds) for an issue").option("--detail", "Include PR URLs, commit IDs, and other details").addHelpText(
-    "after",
-    "\nExamples:\n  jiradc issue dev-status PROJ-123\n  jiradc issue dev-status PROJ-123 --detail"
-  ).action(async (key, opts) => {
+  const cmd = parent.command("dev-status <key>").description("Get development status (PRs, commits, branches, builds) for an issue").option("--detail", "Include PR URLs, commit IDs, and other details");
+  examples(cmd, ["PROJ-123", "PROJ-123 --detail"]);
+  cmd.action(async (key, opts) => {
     const client = getClient();
     const issue = await client.issues.get({ issueKeyOrId: key, fields: ["summary"] });
     const issueId = issue.id;
@@ -1256,10 +1390,14 @@ var DEFAULT_FIELDS = [
 
 // src/commands/issue/get.ts
 function get2(parent) {
-  parent.command("get <key>").description("Get issue details").option("--fields <fields>", "Comma-separated fields to return (defaults to essential fields)").option("--all-fields", "Return all fields instead of defaults").option("--expand <expand>", 'Expand options (e.g., "transitions", "changelog")').addHelpText(
-    "after",
-    "\nExamples:\n  jiradc issue get PROJ-123\n  jiradc issue get PROJ-123 --fields summary,status,assignee\n  jiradc issue get PROJ-123 --all-fields\n  jiradc issue get PROJ-123 --expand changelog,transitions"
-  ).action(async (key, opts) => {
+  const cmd = parent.command("get <key>").description("Get issue details").option("--fields <fields>", "Comma-separated fields to return (defaults to essential fields)").option("--all-fields", "Return all fields instead of defaults").option("--expand <expand>", 'Expand options (e.g., "transitions", "changelog")');
+  examples(cmd, [
+    "PROJ-123",
+    "PROJ-123 --fields summary,status,assignee",
+    "PROJ-123 --all-fields",
+    "PROJ-123 --expand changelog,transitions"
+  ]);
+  cmd.action(async (key, opts) => {
     const client = getClient();
     const fields = opts.allFields ? void 0 : opts.fields?.split(",").map((f) => f.trim()) ?? DEFAULT_FIELDS;
     const result = await client.issues.get({
@@ -1273,13 +1411,9 @@ function get2(parent) {
 
 // src/commands/issue/link-epic.ts
 function linkEpic(parent) {
-  parent.command("link-epic <keys...>").description("Link one or more issues to an epic").requiredOption("--epic <epicKey>", "Epic issue key").addHelpText(
-    "after",
-    `
-Examples:
-  jiradc issue link-epic PROJ-456 --epic PROJ-123
-  jiradc issue link-epic PROJ-456 PROJ-457 PROJ-458 --epic PROJ-123`
-  ).action(async (keys, opts) => {
+  const cmd = parent.command("link-epic <keys...>").description("Link one or more issues to an epic").requiredOption("--epic <epicKey>", "Epic issue key");
+  examples(cmd, ["PROJ-456 --epic PROJ-123", "PROJ-456 PROJ-457 PROJ-458 --epic PROJ-123"]);
+  cmd.action(async (keys, opts) => {
     const client = getClient();
     const results = await Promise.allSettled(
       keys.map(
@@ -1309,7 +1443,9 @@ Examples:
 
 // src/commands/issue/link-types.ts
 function linkTypes(parent) {
-  parent.command("link-types").description("List all issue link types").addHelpText("after", "\nExamples:\n  jiradc issue link-types").action(async () => {
+  const cmd = parent.command("link-types").description("List all issue link types");
+  examples(cmd, [""]);
+  cmd.action(async () => {
     const client = getClient();
     const result = await client.links.getTypes();
     output(result.map(transformIssueLinkType));
@@ -1318,10 +1454,12 @@ function linkTypes(parent) {
 
 // src/commands/issue/link.ts
 function link(parent) {
-  parent.command("link").description("Link two issues together").requiredOption("--type <name>", "Link type name (e.g., 'Blocks', 'Duplicate', 'Relates')").requiredOption("--from <key>", 'Source issue key (e.g., the issue that "blocks")').requiredOption("--to <key>", 'Target issue key (e.g., the issue that "is blocked by")').option("--comment <text>", "Optional comment").addHelpText(
-    "after",
-    "\nExamples:\n  jiradc issue link --type Relates --from AI-154 --to AI-149\n  jiradc issue link --type Blocks --from PROJ-456 --to PROJ-123  # PROJ-456 blocks PROJ-123"
-  ).action(async (opts) => {
+  const cmd = parent.command("link").description("Link two issues together").requiredOption("--type <name>", "Link type name (e.g., 'Blocks', 'Duplicate', 'Relates')").requiredOption("--from <key>", 'Source issue key (e.g., the issue that "blocks")').requiredOption("--to <key>", 'Target issue key (e.g., the issue that "is blocked by")').option("--comment <text>", "Optional comment");
+  examples(cmd, [
+    "--type Relates --from AI-154 --to AI-149",
+    ["--type Blocks --from PROJ-456 --to PROJ-123", "PROJ-456 blocks PROJ-123"]
+  ]);
+  cmd.action(async (opts) => {
     const client = getClient();
     await client.links.create({
       typeName: opts.type,
@@ -1340,10 +1478,13 @@ function link(parent) {
 
 // src/commands/issue/search.ts
 function search2(parent) {
-  parent.command("search <jql>").description("Search issues using JQL").option("--limit <number>", "Max results (1-50, Jira DC caps at 50)", intInRange(1, 50), 25).option("--start <number>", "Starting index for pagination", nonNegativeInt).option("--fields <fields>", "Comma-separated fields to return (defaults to essential fields)").option("--all-fields", "Return all fields instead of defaults").addHelpText(
-    "after",
-    '\nExamples:\n  jiradc issue search "project = PROJ AND status = Open"\n  jiradc issue search "assignee = currentUser()" --limit 10 --fields summary,status\n  jiradc issue search "project = PROJ" --start 50 --limit 50'
-  ).action(async (jql, opts) => {
+  const cmd = parent.command("search <jql>").description("Search issues using JQL").option("--limit <number>", "Max results (1-50, Jira DC caps at 50)", intInRange(1, 50), 25).option("--start <number>", "Starting index for pagination", nonNegativeInt).option("--fields <fields>", "Comma-separated fields to return (defaults to essential fields)").option("--all-fields", "Return all fields instead of defaults");
+  examples(cmd, [
+    '"project = PROJ AND status = Open"',
+    '"assignee = currentUser()" --limit 10 --fields summary,status',
+    '"project = PROJ" --start 50 --limit 50'
+  ]);
+  cmd.action(async (jql, opts) => {
     const client = getClient();
     const fields = opts.allFields ? void 0 : opts.fields?.split(",").map((f) => f.trim()) ?? DEFAULT_FIELDS;
     const result = await client.issues.search({
@@ -1358,14 +1499,13 @@ function search2(parent) {
 
 // src/commands/issue/transition.ts
 function transition(parent) {
-  parent.command("transition <key>").description("Transition issue to a new status").requiredOption("--to <idOrName>", "Transition ID, or status name (case-insensitive)").option("--comment <text>", "Comment to add during transition").addHelpText(
-    "after",
-    `
-Examples:
-  jiradc issue transition PROJ-123 --to 31
-  jiradc issue transition PROJ-123 --to "In Review"
-  jiradc issue transition PROJ-123 --to Done --comment "Verified in staging"`
-  ).action(async (key, opts) => {
+  const cmd = parent.command("transition <key>").description("Transition issue to a new status").requiredOption("--to <idOrName>", "Transition ID, or status name (case-insensitive)").option("--comment <text>", "Comment to add during transition");
+  examples(cmd, [
+    "PROJ-123 --to 31",
+    'PROJ-123 --to "In Review"',
+    'PROJ-123 --to Done --comment "Verified in staging"'
+  ]);
+  cmd.action(async (key, opts) => {
     const client = getClient();
     let transitionId;
     if (/^\d+$/.test(opts.to)) {
@@ -1395,7 +1535,9 @@ Examples:
 
 // src/commands/issue/transitions.ts
 function transitions(parent) {
-  parent.command("transitions <key>").description("Get available transitions for an issue").addHelpText("after", "\nExamples:\n  jiradc issue transitions PROJ-123").action(async (key) => {
+  const cmd = parent.command("transitions <key>").description("Get available transitions for an issue");
+  examples(cmd, ["PROJ-123"]);
+  cmd.action(async (key) => {
     const client = getClient();
     const result = await client.issues.getTransitions({
       issueKeyOrId: key,
@@ -1407,7 +1549,9 @@ function transitions(parent) {
 
 // src/commands/issue/unlink.ts
 function unlink2(parent) {
-  parent.command("unlink <id>").description("Remove a link between two issues").addHelpText("after", "\nExamples:\n  jiradc issue unlink 12345").action(async (id) => {
+  const cmd = parent.command("unlink <id>").description("Remove a link between two issues");
+  examples(cmd, ["12345"]);
+  cmd.action(async (id) => {
     const client = getClient();
     await client.links.remove({ linkId: id });
     output({ removed: true, linkId: id });
@@ -1449,19 +1593,17 @@ function buildSetValue(parsed, wrap) {
   if (parsed.mode !== "set") return void 0;
   return parsed.values.map(wrap);
 }
-function update2(parent) {
-  parent.command("update <key>").description("Update issue fields").option("--fields <json>", "JSON string of fields to update (advanced; merges with shortcuts, wins on conflict)").option("--no-notify-users", "Suppress notification emails (default: notify)").option("--attachments <paths>", "Comma-separated local file paths to attach").option("--summary <text>", "Set the issue summary").option("--description <text>", "Set the issue description (wiki markup)").option("--priority <name>", "Set the priority by name (e.g. High)").option("--assignee <user>", 'Set the assignee. Username, "me", or "none" to unassign.').option("--labels <list>", 'Set labels ("a,b,c") or mutate ("+add,-remove")').option("--components <list>", 'Set components ("a,b") or mutate ("+add,-remove")').option("--fix-versions <list>", 'Set fix versions ("1.0,2.0") or mutate ("+1.0,-0.9")').addHelpText(
-    "after",
-    `
-Examples:
-  jiradc issue update PROJ-123 --summary "New title"
-  jiradc issue update PROJ-123 --priority High --assignee me
-  jiradc issue update PROJ-123 --labels backend,urgent
-  jiradc issue update PROJ-123 --labels +urgent,-backend
-  jiradc issue update PROJ-123 --components +Frontend
-  jiradc issue update PROJ-123 --fields '{"customfield_10100": "EPIC-1"}' --priority High
-  jiradc issue update PROJ-123 --attachments /path/to/file.pdf,/path/to/image.png`
-  ).action(async (key, opts) => {
+function update3(parent) {
+  const cmd = parent.command("update <key>").description("Update issue fields").option("--fields <json>", "JSON string of fields to update (advanced; merges with shortcuts, wins on conflict)").option("--no-notify-users", "Suppress notification emails (default: notify)").option("--attachments <paths>", "Comma-separated local file paths to attach").option("--summary <text>", "Set the issue summary").option("--description <text>", "Set the issue description (wiki markup)").option("--priority <name>", "Set the priority by name (e.g. High)").option("--assignee <user>", 'Set the assignee. Username, "me", or "none" to unassign.').option("--labels <list>", 'Set labels ("a,b,c") or mutate ("+add,-remove")').option("--components <list>", 'Set components ("a,b") or mutate ("+add,-remove")').option("--fix-versions <list>", 'Set fix versions ("1.0,2.0") or mutate ("+1.0,-0.9")');
+  examples(cmd, [
+    'PROJ-123 --summary "New title"',
+    "PROJ-123 --priority High --assignee me",
+    "PROJ-123 --labels backend,urgent",
+    "PROJ-123 --labels +urgent,-backend",
+    "PROJ-123 --components +Frontend",
+    "PROJ-123 --attachments /path/to/file.pdf,/path/to/image.png"
+  ]);
+  cmd.action(async (key, opts) => {
     const hasShortcut = opts.summary !== void 0 || opts.description !== void 0 || opts.priority !== void 0 || opts.assignee !== void 0 || opts.labels !== void 0 || opts.components !== void 0 || opts.fixVersions !== void 0;
     if (!opts.fields && !opts.attachments && !hasShortcut) {
       throw new Error(
@@ -1530,12 +1672,15 @@ Examples:
   });
 }
 
-// src/commands/issue/worklog/add.ts
-function add2(parent) {
-  parent.command("add <key>").description("Log time spent on an issue").requiredOption("--time <timeSpent>", "Time spent (e.g., '2h', '30m', '1d 4h')").option("--comment <text>", "Worklog comment").option("--started <datetime>", "Start time in ISO 8601 format").addHelpText(
-    "after",
-    '\nExamples:\n  jiradc issue worklog add PROJ-123 --time 2h\n  jiradc issue worklog add PROJ-123 --time "1d 4h" --comment "Backend implementation"\n  jiradc issue worklog add PROJ-123 --time 3h --started "2026-03-19T09:00:00.000+0000"'
-  ).action(async (key, opts) => {
+// src/commands/issue/worklog/create.ts
+function create4(parent) {
+  const cmd = parent.command("create <key>").description("Log time spent on an issue").requiredOption("--time <timeSpent>", "Time spent (e.g., '2h', '30m', '1d 4h')").option("--comment <text>", "Worklog comment").option("--started <datetime>", "Start time in ISO 8601 format");
+  examples(cmd, [
+    "PROJ-123 --time 2h",
+    'PROJ-123 --time "1d 4h" --comment "Backend implementation"',
+    'PROJ-123 --time 3h --started "2026-03-19T09:00:00.000+0000"'
+  ]);
+  cmd.action(async (key, opts) => {
     const client = getClient();
     const result = await client.issues.addWorklog({
       issueKeyOrId: key,
@@ -1551,37 +1696,65 @@ function add2(parent) {
 import { Option as Option4 } from "commander";
 var ADJUST_ESTIMATE = ["new", "leave", "manual", "auto"];
 function deleteWorklog(parent) {
-  parent.command("delete <key>").description("Delete a worklog entry").requiredOption("--id <worklogId>", "Worklog ID to delete").addOption(new Option4("--adjust-estimate <mode>", "How to adjust the remaining estimate").choices(ADJUST_ESTIMATE)).option("--new-estimate <estimate>", 'New remaining estimate; required when --adjust-estimate is "new"').option("--increase-by <amount>", 'Amount to increase the estimate by; required when --adjust-estimate is "manual"').addHelpText(
-    "after",
-    "\nExamples:\n  jiradc issue worklog delete PROJ-123 --id 12345\n  jiradc issue worklog delete PROJ-123 --id 12345 --adjust-estimate leave\n  jiradc issue worklog delete PROJ-123 --id 12345 --adjust-estimate new --new-estimate 2h"
-  ).action(
+  const cmd = parent.command("delete <key>").description("Delete a worklog entry");
+  subEntityOption(cmd, "worklog", { mandatory: true });
+  cmd.addOption(new Option4("--adjust-estimate <mode>", "How to adjust the remaining estimate").choices(ADJUST_ESTIMATE)).option("--new-estimate <estimate>", 'New remaining estimate; required when --adjust-estimate is "new"').option(
+    "--increase-by <amount>",
+    'Amount to increase the estimate by; required when --adjust-estimate is "manual"'
+  );
+  examples(cmd, [
+    "PROJ-123 --worklog-id 12345",
+    "PROJ-123 --worklog-id 12345 --adjust-estimate leave",
+    "PROJ-123 --worklog-id 12345 --adjust-estimate new --new-estimate 2h"
+  ]);
+  cmd.action(
     async (key, opts) => {
       const client = getClient();
       await client.issues.deleteWorklog({
         issueKeyOrId: key,
-        worklogId: opts.id,
+        worklogId: String(opts.worklogId),
         adjustEstimate: opts.adjustEstimate,
         newEstimate: opts.newEstimate,
         increaseBy: opts.increaseBy
       });
-      output({ deleted: true, issueKey: key, worklogId: opts.id });
+      output({ deleted: true, issueKey: key, worklogId: opts.worklogId });
     }
   );
 }
 
-// src/commands/issue/worklog/edit.ts
+// src/commands/issue/worklog/list.ts
+function list4(parent) {
+  const cmd = parent.command("list <key>").description("Get worklogs for an issue").option("--start <number>", "Starting index for pagination", nonNegativeInt).option("--limit <number>", "Max results per page (1-1000)", intInRange(1, 1e3), 25);
+  examples(cmd, ["PROJ-123", "PROJ-123 --limit 10", "PROJ-123 --start 10 --limit 5"]);
+  cmd.action(async (key, opts) => {
+    const client = getClient();
+    const result = await client.issues.getWorklogs({
+      issueKeyOrId: key,
+      startAt: opts.start,
+      maxResults: opts.limit
+    });
+    output(transformPaged(result, transformWorklog));
+  });
+}
+
+// src/commands/issue/worklog/update.ts
 import { Option as Option5 } from "commander";
 var ADJUST_ESTIMATE2 = ["new", "leave", "auto"];
-function edit2(parent) {
-  parent.command("edit <key>").description("Update an existing worklog entry").requiredOption("--id <worklogId>", "Worklog ID to edit").option("--time <timeSpent>", "Time spent (e.g., '2h', '30m', '1d 4h')").option("--comment <text>", "Worklog comment").option("--started <datetime>", "Start time in ISO 8601 format").addOption(new Option5("--adjust-estimate <mode>", "How to adjust the remaining estimate").choices(ADJUST_ESTIMATE2)).option("--new-estimate <estimate>", 'New remaining estimate; required when --adjust-estimate is "new"').addHelpText(
-    "after",
-    '\nExamples:\n  jiradc issue worklog edit PROJ-123 --id 12345 --time "1h 30m"\n  jiradc issue worklog edit PROJ-123 --id 12345 --comment "Revised note"\n  jiradc issue worklog edit PROJ-123 --id 12345 --time 2h --adjust-estimate new --new-estimate 4h'
-  ).action(
+function update4(parent) {
+  const cmd = parent.command("update <key>").description("Update an existing worklog entry");
+  subEntityOption(cmd, "worklog", { mandatory: true });
+  cmd.option("--time <timeSpent>", "Time spent (e.g., '2h', '30m', '1d 4h')").option("--comment <text>", "Worklog comment").option("--started <datetime>", "Start time in ISO 8601 format").addOption(new Option5("--adjust-estimate <mode>", "How to adjust the remaining estimate").choices(ADJUST_ESTIMATE2)).option("--new-estimate <estimate>", 'New remaining estimate; required when --adjust-estimate is "new"');
+  examples(cmd, [
+    'PROJ-123 --worklog-id 12345 --time "1h 30m"',
+    'PROJ-123 --worklog-id 12345 --comment "Revised note"',
+    "PROJ-123 --worklog-id 12345 --time 2h --adjust-estimate new --new-estimate 4h"
+  ]);
+  cmd.action(
     async (key, opts) => {
       const client = getClient();
       const result = await client.issues.updateWorklog({
         issueKeyOrId: key,
-        worklogId: opts.id,
+        worklogId: String(opts.worklogId),
         timeSpent: opts.time,
         comment: opts.comment,
         started: opts.started,
@@ -1593,58 +1766,36 @@ function edit2(parent) {
   );
 }
 
-// src/commands/issue/worklog/list.ts
-function list4(parent) {
-  parent.command("list <key>").description("Get worklogs for an issue").option("--start <number>", "Starting index for pagination", nonNegativeInt).option("--limit <number>", "Max results per page (1-1000)", intInRange(1, 1e3), 25).addHelpText(
-    "after",
-    "\nExamples:\n  jiradc issue worklog list PROJ-123\n  jiradc issue worklog list PROJ-123 --limit 10\n  jiradc issue worklog list PROJ-123 --start 10 --limit 5"
-  ).action(async (key, opts) => {
-    const client = getClient();
-    const result = await client.issues.getWorklogs({
-      issueKeyOrId: key,
-      startAt: opts.start,
-      maxResults: opts.limit
-    });
-    output(transformPaged(result, transformWorklog));
-  });
-}
-
 // src/commands/issue/worklog/index.ts
 function registerWorklogCommands(parent) {
-  const worklog = parent.command("worklog").description("Worklog operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ jiradc issue worklog add PROJ-123 --time 2h --comment "Backend work"
-  $ jiradc issue worklog list PROJ-123 --limit 10
-  $ jiradc issue worklog edit PROJ-123 --id 12345 --time "1h 30m"
-  $ jiradc issue worklog delete PROJ-123 --id 12345
-`
-  );
-  add2(worklog);
+  const worklog = parent.command("worklog").description("Worklog operations");
+  examples(worklog, [
+    'create PROJ-123 --time 2h --comment "Backend work"',
+    "list PROJ-123 --limit 10",
+    'update PROJ-123 --worklog-id 12345 --time "1h 30m"',
+    "delete PROJ-123 --worklog-id 12345"
+  ]);
+  create4(worklog);
   list4(worklog);
-  edit2(worklog);
+  update4(worklog);
   deleteWorklog(worklog);
 }
 
 // src/commands/issue/index.ts
-function registerIssueCommands(program2) {
-  const issue = program2.command("issue").description("Issue operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ jiradc issue get PROJ-123
-  $ jiradc issue search "project = PROJ AND status = Open" --limit 10
-  $ jiradc issue create --project PROJ --type Task --summary "Fix the bug" --priority High
-  $ jiradc issue update PROJ-123 --fields '{"summary": "New title"}'
-  $ jiradc issue transition PROJ-123 --to 11
-  $ jiradc issue attachment list PROJ-123
-`
-  );
+function registerIssueCommands(program) {
+  const issue = program.command("issue").description("Issue operations");
+  examples(issue, [
+    "get PROJ-123",
+    'search "project = PROJ AND status = Open" --limit 10',
+    'create --project PROJ --type Task --summary "Fix the bug" --priority High',
+    `update PROJ-123 --fields '{"summary": "New title"}'`,
+    "transition PROJ-123 --to 11",
+    "attachment list PROJ-123"
+  ]);
   get2(issue);
   search2(issue);
-  create2(issue);
-  update2(issue);
+  create3(issue);
+  update3(issue);
   deleteIssue(issue);
   transition(issue);
   transitions(issue);
@@ -1658,7 +1809,6 @@ Examples:
   linkTypes(issue);
   linkEpic(issue);
   registerAttachmentCommands(issue);
-  attachments(issue);
   batchCreate(issue);
   clone(issue);
   devStatus(issue);
@@ -1666,10 +1816,9 @@ Examples:
 
 // src/commands/project/list.ts
 function list5(parent) {
-  parent.command("list").description("List all projects").option("--expand <expand>", 'Expand options (e.g., "description,lead")').option("--include-archived", "Include archived projects (default: false)").addHelpText(
-    "after",
-    "\nExamples:\n  jiradc project list\n  jiradc project list --expand description,lead\n  jiradc project list --include-archived"
-  ).action(async (opts) => {
+  const cmd = parent.command("list").description("List all projects").option("--expand <expand>", 'Expand options (e.g., "description,lead")').option("--include-archived", "Include archived projects (default: false)");
+  examples(cmd, ["", "--expand description,lead", "--include-archived"]);
+  cmd.action(async (opts) => {
     const client = getClient();
     const result = await client.projects.getAll({ expand: opts.expand, includeArchived: opts.includeArchived });
     output(result.map(transformProject));
@@ -1678,10 +1827,9 @@ function list5(parent) {
 
 // src/commands/project/versions.ts
 function versions(parent) {
-  parent.command("versions <key>").description("Get all versions for a project").option("--expand <expand>", "Expand options").addHelpText(
-    "after",
-    "\nExamples:\n  jiradc project versions PROJ\n  jiradc project versions PROJ --expand operations"
-  ).action(async (key, opts) => {
+  const cmd = parent.command("versions <key>").description("Get all versions for a project").option("--expand <expand>", "Expand options");
+  examples(cmd, ["PROJ", "PROJ --expand operations"]);
+  cmd.action(async (key, opts) => {
     const client = getClient();
     const result = await client.projects.getVersions({ projectKeyOrId: key, expand: opts.expand });
     output(result.map(transformVersion));
@@ -1689,25 +1837,21 @@ function versions(parent) {
 }
 
 // src/commands/project/index.ts
-function registerProjectCommands(program2) {
-  const project = program2.command("project").description("Project operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ jiradc project list
-  $ jiradc project versions PROJ
-`
-  );
+function registerProjectCommands(program) {
+  const project = program.command("project").description("Project operations");
+  examples(project, ["list", "versions PROJ"]);
   list5(project);
   versions(project);
 }
 
 // src/commands/sprint/create.ts
-function create3(parent) {
-  parent.command("create").description("Create a new sprint").requiredOption("--board <id>", "Board ID to create sprint in", positiveInt).requiredOption("--name <name>", "Sprint name").option("--start-date <date>", "Start date in ISO 8601 format").option("--end-date <date>", "End date in ISO 8601 format").option("--goal <goal>", "Sprint goal").addHelpText(
-    "after",
-    '\nExamples:\n  jiradc sprint create --board 42 --name "Sprint 10"\n  jiradc sprint create --board 42 --name "Sprint 10" --start-date 2026-03-20 --end-date 2026-04-03 --goal "Complete auth module"'
-  ).action(async (opts) => {
+function create5(parent) {
+  const cmd = parent.command("create").description("Create a new sprint").requiredOption("--board <id>", "Board ID to create sprint in", positiveInt).requiredOption("--name <name>", "Sprint name").option("--start-date <date>", "Start date in ISO 8601 format").option("--end-date <date>", "End date in ISO 8601 format").option("--goal <goal>", "Sprint goal");
+  examples(cmd, [
+    '--board 42 --name "Sprint 10"',
+    '--board 42 --name "Sprint 10" --start-date 2026-03-20 --end-date 2026-04-03 --goal "Complete auth module"'
+  ]);
+  cmd.action(async (opts) => {
     const client = getClient();
     const result = await client.agile.createSprint({
       name: opts.name,
@@ -1723,7 +1867,9 @@ function create3(parent) {
 // src/commands/sprint/delete.ts
 import { Argument as Argument2 } from "commander";
 function deleteSprint(parent) {
-  parent.command("delete").description("Delete a sprint (returns its issues to the backlog)").addArgument(new Argument2("<id>", "Sprint ID").argParser(positiveInt)).addHelpText("after", "\nExamples:\n  jiradc sprint delete 100").action(async (id) => {
+  const cmd = parent.command("delete").description("Delete a sprint (returns its issues to the backlog)").addArgument(new Argument2("<id>", "Sprint ID").argParser(positiveInt));
+  examples(cmd, ["100"]);
+  cmd.action(async (id) => {
     const client = getClient();
     await client.agile.deleteSprint({ sprintId: id });
     output({ deleted: true, sprintId: id });
@@ -1733,10 +1879,14 @@ function deleteSprint(parent) {
 // src/commands/sprint/issues.ts
 import { Argument as Argument3 } from "commander";
 function issues2(parent) {
-  parent.command("issues").description("Get issues in a sprint").addArgument(new Argument3("<id>", "Sprint ID").argParser(positiveInt)).option("--limit <number>", "Max results (1-50, Jira DC caps at 50)", intInRange(1, 50), 25).option("--start <number>", "Starting index for pagination", nonNegativeInt).option("--fields <fields>", "Comma-separated field names to return").option("--jql <jql>", "Additional JQL filter within the sprint").addHelpText(
-    "after",
-    '\nExamples:\n  jiradc sprint issues 100\n  jiradc sprint issues 100 --limit 20\n  jiradc sprint issues 100 --jql "status = Done" --fields summary,status\n  jiradc sprint issues 100 --start 50 --limit 25'
-  ).action(async (id, opts) => {
+  const cmd = parent.command("issues").description("Get issues in a sprint").addArgument(new Argument3("<id>", "Sprint ID").argParser(positiveInt)).option("--limit <number>", "Max results (1-50, Jira DC caps at 50)", intInRange(1, 50), 25).option("--start <number>", "Starting index for pagination", nonNegativeInt).option("--fields <fields>", "Comma-separated field names to return").option("--jql <jql>", "Additional JQL filter within the sprint");
+  examples(cmd, [
+    "100",
+    "100 --limit 20",
+    '100 --jql "status = Done" --fields summary,status',
+    "100 --start 50 --limit 25"
+  ]);
+  cmd.action(async (id, opts) => {
     const client = getClient();
     const result = await client.agile.getSprintIssues({
       sprintId: id,
@@ -1753,10 +1903,9 @@ function issues2(parent) {
 import { Option as Option6 } from "commander";
 var SPRINT_STATES = ["future", "active", "closed"];
 function list6(parent) {
-  parent.command("list").description("List sprints for a board").requiredOption("--board <id>", "Board ID", positiveInt).addOption(new Option6("--state <state>", "Filter by sprint state").choices(SPRINT_STATES)).addHelpText(
-    "after",
-    "\nExamples:\n  jiradc sprint list --board 42\n  jiradc sprint list --board 42 --state active"
-  ).action(async (opts) => {
+  const cmd = parent.command("list").description("List sprints for a board").requiredOption("--board <id>", "Board ID", positiveInt).addOption(new Option6("--state <state>", "Filter by sprint state").choices(SPRINT_STATES));
+  examples(cmd, ["--board 42", "--board 42 --state active"]);
+  cmd.action(async (opts) => {
     const client = getClient();
     const result = await client.agile.getSprints({
       boardId: opts.board,
@@ -1769,11 +1918,14 @@ function list6(parent) {
 // src/commands/sprint/update.ts
 import { Argument as Argument4, Option as Option7 } from "commander";
 var SPRINT_STATES2 = ["future", "active", "closed"];
-function update3(parent) {
-  parent.command("update").description("Update an existing sprint").addArgument(new Argument4("<id>", "Sprint ID").argParser(positiveInt)).option("--name <name>", "New sprint name").addOption(new Option7("--state <state>", "New sprint state").choices(SPRINT_STATES2)).option("--start-date <date>", "New start date in ISO 8601 format").option("--end-date <date>", "New end date in ISO 8601 format").option("--goal <goal>", "New sprint goal").addHelpText(
-    "after",
-    '\nExamples:\n  jiradc sprint update 100 --name "Sprint 10 - Extended"\n  jiradc sprint update 100 --state active\n  jiradc sprint update 100 --end-date 2026-04-10 --goal "Updated goal"'
-  ).action(
+function update5(parent) {
+  const cmd = parent.command("update").description("Update an existing sprint").addArgument(new Argument4("<id>", "Sprint ID").argParser(positiveInt)).option("--name <name>", "New sprint name").addOption(new Option7("--state <state>", "New sprint state").choices(SPRINT_STATES2)).option("--start-date <date>", "New start date in ISO 8601 format").option("--end-date <date>", "New end date in ISO 8601 format").option("--goal <goal>", "New sprint goal");
+  examples(cmd, [
+    '100 --name "Sprint 10 - Extended"',
+    "100 --state active",
+    '100 --end-date 2026-04-10 --goal "Updated goal"'
+  ]);
+  cmd.action(
     async (id, opts) => {
       const client = getClient();
       const result = await client.agile.updateSprint({
@@ -1790,21 +1942,18 @@ function update3(parent) {
 }
 
 // src/commands/sprint/index.ts
-function registerSprintCommands(program2) {
-  const sprint = program2.command("sprint").description("Sprint operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ jiradc sprint list --board 42
-  $ jiradc sprint list --board 42 --state active
-  $ jiradc sprint issues 123 --limit 20
-  $ jiradc sprint create --board 42 --name "Sprint 10" --start-date 2026-04-01 --end-date 2026-04-14
-`
-  );
+function registerSprintCommands(program) {
+  const sprint = program.command("sprint").description("Sprint operations");
+  examples(sprint, [
+    "list --board 42",
+    "list --board 42 --state active",
+    "issues 123 --limit 20",
+    'create --board 42 --name "Sprint 10" --start-date 2026-04-01 --end-date 2026-04-14'
+  ]);
   list6(sprint);
   issues2(sprint);
-  create3(sprint);
-  update3(sprint);
+  create5(sprint);
+  update5(sprint);
   deleteSprint(sprint);
 }
 
@@ -1820,36 +1969,24 @@ function getTokenClient(options2 = {}) {
       ...!username ? ["JIRA_BASIC_USERNAME (or --basic-username)"] : [],
       ...!password ? ["JIRA_BASIC_PASSWORD (or --basic-password)"] : []
     ];
-    process.stderr.write(
-      `${JSON.stringify({
-        error: `Missing required credentials: ${missing.join(", ")}`,
-        hint: "Set JIRA_BASIC_USERNAME and JIRA_BASIC_PASSWORD in your shell profile, or pass --basic-username / --basic-password."
-      })}
-`
-    );
-    process.exit(1);
+    throw new CliAuthError(`Missing required credentials: ${missing.join(", ")}`);
   }
   const client = new JiraClient2({ baseUrl });
   return { client, username, password };
 }
 
 // src/commands/token/create.ts
-function create4(parent) {
-  parent.command("create").description("Create a Personal Access Token. The secret is returned exactly once.").requiredOption("--name <name>", "Token name").option(
+function create6(parent) {
+  const cmd = parent.command("create").description("Create a Personal Access Token. The secret is returned exactly once.").requiredOption("--name <name>", "Token name").option(
     "--expiration-duration <days>",
     "Token lifetime in days. Omit for a non-expiring token (admin policy permitting).",
     positiveInt
   ).option("--basic-username <u>", "Override $JIRA_BASIC_USERNAME").option(
     "--basic-password <p>",
     "Override $JIRA_BASIC_PASSWORD (caution: visible in process table; prefer the env var)"
-  ).addHelpText(
-    "after",
-    `
-Examples:
-  $ jiradc token create --name my-pat                          # non-expiring
-  $ jiradc token create --name svc-token --expiration-duration 365
-`
-  ).action(async (opts) => {
+  );
+  examples(cmd, [["--name my-pat", "non-expiring"], "--name svc-token --expiration-duration 365"]);
+  cmd.action(async (opts) => {
     const { client, username, password } = getTokenClient({
       basicUsername: opts.basicUsername,
       basicPassword: opts.basicPassword
@@ -1866,10 +2003,12 @@ Examples:
 
 // src/commands/token/list.ts
 function list7(parent) {
-  parent.command("list").description("List Personal Access Tokens owned by the authenticated user (secrets not included)").option("--basic-username <u>", "Override $JIRA_BASIC_USERNAME").option(
+  const cmd = parent.command("list").description("List Personal Access Tokens owned by the authenticated user (secrets not included)").option("--basic-username <u>", "Override $JIRA_BASIC_USERNAME").option(
     "--basic-password <p>",
     "Override $JIRA_BASIC_PASSWORD (caution: visible in process table; prefer the env var)"
-  ).action(async (opts) => {
+  );
+  examples(cmd, [""]);
+  cmd.action(async (opts) => {
     const { client, username, password } = getTokenClient({
       basicUsername: opts.basicUsername,
       basicPassword: opts.basicPassword
@@ -1880,42 +2019,40 @@ function list7(parent) {
 
 // src/commands/token/revoke.ts
 function revoke(parent) {
-  parent.command("revoke").description("Revoke a Personal Access Token by id").requiredOption("--id <tokenId>", "Token id to revoke", positiveInt).option("--basic-username <u>", "Override $JIRA_BASIC_USERNAME").option(
+  const cmd = parent.command("revoke").description("Revoke a Personal Access Token by id").option("--basic-username <u>", "Override $JIRA_BASIC_USERNAME").option(
     "--basic-password <p>",
     "Override $JIRA_BASIC_PASSWORD (caution: visible in process table; prefer the env var)"
-  ).action(async (opts) => {
+  );
+  subjectArg(cmd, "tokenId", { parser: positiveInt, description: "Token id to revoke" });
+  examples(cmd, ["173"]);
+  cmd.action(async (tokenId, opts) => {
     const { client, username, password } = getTokenClient({
       basicUsername: opts.basicUsername,
       basicPassword: opts.basicPassword
     });
-    await client.accessTokens.revoke({ username, password, tokenId: opts.id });
-    output({ revoked: opts.id });
+    await client.accessTokens.revoke({ username, password, tokenId });
+    output({ revoked: tokenId });
   });
 }
 
 // src/commands/token/index.ts
-function registerTokenCommands(program2) {
-  const token = program2.command("token").description("Personal Access Token management").addHelpText(
+function registerTokenCommands(program) {
+  const token = program.command("token").description("Personal Access Token management");
+  examples(token, ["list", "create --name my-pat", "revoke 173"]);
+  token.addHelpText(
     "after",
-    `
-Examples:
-  $ jiradc token list
-  $ jiradc token create --name my-pat
-  $ jiradc token revoke --id 173
-
-Auth:
-  Requires JIRA_BASIC_USERNAME + JIRA_BASIC_PASSWORD
-  (or --basic-username / --basic-password on any subcommand).
-`
+    "\nAuth:\n  Requires JIRA_BASIC_USERNAME + JIRA_BASIC_PASSWORD\n  (or --basic-username / --basic-password on any subcommand)."
   );
-  create4(token);
+  create6(token);
   list7(token);
   revoke(token);
 }
 
 // src/commands/user/get.ts
 function get3(parent) {
-  parent.command("get <username>").description("Get a user profile by exact username or key").option("--by-key", "Treat the positional argument as a user key instead of a username").addHelpText("after", "\nExamples:\n  jiradc user get jsmith\n  jiradc user get JIRAUSER10100 --by-key").action(async (identifier, opts) => {
+  const cmd = parent.command("get <username>").description("Get a user profile by exact username or key").option("--by-key", "Treat the positional argument as a user key instead of a username");
+  examples(cmd, ["jsmith", "JIRAUSER10100 --by-key"]);
+  cmd.action(async (identifier, opts) => {
     const client = getClient();
     const result = await client.users.getUser(opts.byKey ? { key: identifier } : { username: identifier });
     output(transformUser(result));
@@ -1924,7 +2061,9 @@ function get3(parent) {
 
 // src/commands/user/me.ts
 function me(parent) {
-  parent.command("me").description("Get the authenticated user profile").addHelpText("after", "\nExamples:\n  jiradc user me").action(async () => {
+  const cmd = parent.command("me").description("Get the authenticated user profile");
+  examples(cmd, [""]);
+  cmd.action(async () => {
     const client = getClient();
     const result = await client.users.getMyself();
     output(transformUser(result));
@@ -1933,10 +2072,9 @@ function me(parent) {
 
 // src/commands/user/search.ts
 function search3(parent) {
-  parent.command("search <query>").description("Search users by partial username, display name or email").option("--limit <n>", "Maximum results (1-50)", intInRange(1, 50), 25).option("--start <n>", "Starting index (pagination offset)", nonNegativeInt, 0).option("--include-inactive", "Include inactive users in results", false).addHelpText(
-    "after",
-    '\nExamples:\n  jiradc user search Drago\n  jiradc user search "John Smith"\n  jiradc user search dragomir@first.bet --limit 5'
-  ).action(async (query, opts) => {
+  const cmd = parent.command("search <query>").description("Search users by partial username, display name or email").option("--limit <n>", "Maximum results (1-50)", intInRange(1, 50), 25).option("--start <n>", "Starting index (pagination offset)", nonNegativeInt, 0).option("--include-inactive", "Include inactive users in results", false);
+  examples(cmd, ["Drago", '"John Smith"', "dragomir@first.bet --limit 5"]);
+  cmd.action(async (query, opts) => {
     const client = getClient();
     const result = await client.users.searchUsers({
       username: query,
@@ -1950,46 +2088,30 @@ function search3(parent) {
 }
 
 // src/commands/user/index.ts
-function registerUserCommands(program2) {
-  const user = program2.command("user").description("User operations").addHelpText(
-    "after",
-    `
-Examples:
-  $ jiradc user me
-  $ jiradc user get jsmith
-  $ jiradc user search Drago
-`
-  );
+function registerUserCommands(program) {
+  const user = program.command("user").description("User operations");
+  examples(user, ["me", "get jsmith", "search Drago"]);
   me(user);
   get3(user);
   search3(user);
 }
 
-// src/index.ts
-function readPackageVersion() {
-  try {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const pkgPath = join4(here, "..", "package.json");
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-    return pkg.version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
+// src/program.ts
 var DIM = "\x1B[2m";
 var RESET = "\x1B[0m";
-var program = new Command11();
-program.name("jiradc").description("Jira Data Center CLI").version(readPackageVersion()).configureHelp({
-  styleTitle: (str) => styleText("bold", str),
-  styleUsage: (str) => styleText("dim", str),
-  styleCommandDescription: (str) => styleText("dim", str),
-  styleOptionDescription: (str) => styleText("dim", str),
-  styleSubcommandDescription: (str) => styleText("dim", str)
-}).addHelpText("beforeAll", `
+function buildProgram() {
+  const program = new Command11();
+  program.name("jiradc").description("Jira Data Center CLI").version(readPackageVersion(import.meta.url)).configureHelp({
+    styleTitle: (str) => styleText("bold", str),
+    styleUsage: (str) => styleText("dim", str),
+    styleCommandDescription: (str) => styleText("dim", str),
+    styleOptionDescription: (str) => styleText("dim", str),
+    styleSubcommandDescription: (str) => styleText("dim", str)
+  }).addHelpText("beforeAll", `
 ${styleText("bold", "jiradc")} ${DIM}\u2014 Jira Data Center CLI${RESET}
 `).addHelpText(
-  "after",
-  `
+    "after",
+    `
 ${styleText("bold", "Environment:")}
   JIRA_URL      Jira Server base URL ${DIM}(e.g., https://jira.example.com)${RESET}
   JIRA_TOKEN    Personal Access Token ${DIM}(generate in Jira > Profile > Personal Access Tokens)${RESET}
@@ -2003,21 +2125,45 @@ ${styleText("bold", "Examples:")}
   ${DIM}$${RESET} jiradc board list --type scrum
   ${DIM}$${RESET} jiradc sprint list --board 42 --state active
 `
-);
-program.option("--pretty", "Pretty-print JSON output");
-program.hook("preAction", (thisCommand) => {
-  if (thisCommand.optsWithGlobals().pretty) setPretty(true);
-});
-registerIssueCommands(program);
-registerProjectCommands(program);
-registerComponentCommands(program);
-registerBoardCommands(program);
-registerSprintCommands(program);
-registerFieldCommands(program);
-registerUserCommands(program);
-registerTokenCommands(program);
-try {
-  await program.parseAsync();
-} catch (err) {
-  handleError(err);
+  );
+  program.option("--pretty", "Pretty-print JSON output");
+  program.hook("preAction", (thisCommand) => {
+    if (thisCommand.optsWithGlobals().pretty) setPretty(true);
+  });
+  registerIssueCommands(program);
+  registerProjectCommands(program);
+  registerComponentCommands(program);
+  registerBoardCommands(program);
+  registerSprintCommands(program);
+  registerFieldCommands(program);
+  registerUserCommands(program);
+  registerTokenCommands(program);
+  return program;
+}
+
+// src/utils/credentials.ts
+function getCredentialInfo() {
+  const baseUrl = process.env.JIRA_URL;
+  const token = process.env.JIRA_TOKEN;
+  return {
+    environment: {
+      JIRA_URL: {
+        value: baseUrl ?? null,
+        description: "Your Jira Server base URL (e.g., https://jira.example.com)"
+      },
+      JIRA_TOKEN: {
+        value: token ? "<set>" : null,
+        description: "Personal Access Token"
+      }
+    },
+    tokenUrl: `${baseUrl ?? "https://jira.example.com"}/secure/ViewProfile.jspa`
+  };
 }
+
+// src/index.ts
+await runCli(buildProgram(), {
+  credentialInfo: getCredentialInfo,
+  service: "Jira",
+  authRecovery: "Set the JIRA_URL and JIRA_TOKEN environment variables.",
+  networkRecovery: "Verify JIRA_URL is correct, the server is reachable, and you are on the VPN if required."
+});