jiradc-cli 1.0.24 → 1.0.25-g6beae79.4

package/dist/index.js

@@ -25,10 +25,10 @@ function intInRange(min, max) {
   return (raw) => {
     const n = parseInt(raw, 10);
     if (Number.isNaN(n) || !Number.isFinite(n)) {
-      throw new InvalidArgumentError(`Not a number: "${raw}"`);
+      throw new InvalidArgumentError("Must be an integer.");
     }
     if (n < min || n > max) {
-      throw new InvalidArgumentError(`Must be between ${min} and ${max} (got ${n})`);
+      throw new InvalidArgumentError(`Must be between ${min} and ${max}.`);
     }
     return n;
   };
@@ -36,37 +36,80 @@ function intInRange(min, max) {
 function nonNegativeInt(raw) {
   const n = parseInt(raw, 10);
   if (Number.isNaN(n) || n < 0) {
-    throw new InvalidArgumentError(`Must be a non-negative integer (got "${raw}")`);
+    throw new InvalidArgumentError("Must be a non-negative integer.");
   }
   return n;
 }
 function positiveInt(raw) {
   const n = parseInt(raw, 10);
   if (Number.isNaN(n) || n < 1) {
-    throw new InvalidArgumentError(`Must be a positive integer (got "${raw}")`);
+    throw new InvalidArgumentError("Must be a positive integer.");
   }
   return n;
 }
+function text(raw) {
+  return raw;
+}
+function date(raw) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(raw);
+  if (!m) {
+    throw new InvalidArgumentError("Must be a date in YYYY-MM-DD format.");
+  }
+  const [, y, mo, d] = m;
+  const year = Number(y);
+  const month = Number(mo);
+  const day = Number(d);
+  const dt = new Date(Date.UTC(year, month - 1, day));
+  if (dt.getUTCFullYear() !== year || dt.getUTCMonth() !== month - 1 || dt.getUTCDate() !== day) {
+    throw new InvalidArgumentError("Not a real calendar date.");
+  }
+  return raw;
+}
+function dateTime(raw) {
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(raw) || Number.isNaN(Date.parse(raw))) {
+    throw new InvalidArgumentError("Must be an ISO 8601 date-time, e.g. 2026-06-08T14:30:00Z.");
+  }
+  return raw;
+}
+
+// ../../cli-utils/dist/json.js
+import { InvalidArgumentError as InvalidArgumentError2 } from "commander";
+function jsonShape(schema) {
+  return (raw) => {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      throw new InvalidArgumentError2("Must be valid JSON.");
+    }
+    const result = schema.safeParse(parsed);
+    if (!result.success) {
+      const issues3 = result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+      throw new InvalidArgumentError2(`Invalid JSON shape \u2014 ${issues3}`);
+    }
+    return result.data;
+  };
+}
 
 // ../../cli-utils/dist/text-or-file.js
 import { readFileSync as readFileSync3 } from "fs";
-import { InvalidArgumentError as InvalidArgumentError2, Option } from "commander";
+import { InvalidArgumentError as InvalidArgumentError3, Option } from "commander";
 var STDIN_REF = "-";
 function rejectStdinSentinel(value) {
   if (value === "@-" || value === STDIN_REF) {
-    throw new InvalidArgumentError2(`"${value}" looks like a stdin redirect, which is not supported here. Pass the text directly, or read it from a file/stdin with the matching --\u2026-file <path|-> option.`);
+    throw new InvalidArgumentError3(`"${value}" looks like a stdin redirect, which is not supported here. Pass the text directly, or read it from a file/stdin with the matching --\u2026-file <path|-> option.`);
   }
   return value;
 }
 function readFileOrStdin(ref) {
   if (ref === STDIN_REF) {
     if (process.stdin.isTTY) {
-      throw new InvalidArgumentError2('"--\u2026-file -" reads stdin, but stdin is a terminal (nothing piped).');
+      throw new InvalidArgumentError3('"--\u2026-file -" reads stdin, but stdin is a terminal (nothing piped).');
     }
     try {
       return readFileSync3(0, "utf8");
     } catch (err) {
-      throw new InvalidArgumentError2(`failed to read stdin for "--\u2026-file -": ${err.message}`);
+      throw new InvalidArgumentError3(`failed to read stdin for "--\u2026-file -": ${err.message}`);
     }
   }
   try {
@@ -74,28 +117,28 @@ function readFileOrStdin(ref) {
   } catch (err) {
     const e = err;
     if (e.code === "ENOENT") {
-      throw new InvalidArgumentError2(`file not found: "${ref}".`);
+      throw new InvalidArgumentError3(`file not found: "${ref}".`);
     }
-    throw new InvalidArgumentError2(`failed to read file "${ref}": ${e.message}`);
+    throw new InvalidArgumentError3(`failed to read file "${ref}": ${e.message}`);
   }
 }
 function textOrFileOption(cmd, name, opts = {}) {
   const label = `${name.charAt(0).toUpperCase()}${name.slice(1)} content`;
   cmd.option(`--${name} <text>`, opts.description ?? label, rejectStdinSentinel);
-  cmd.addOption(new Option(`--${name}-file <path>`, `Read --${name} from a file, or "-" for stdin (mutually exclusive with --${name})`).conflicts(name));
+  cmd.addOption(new Option(`--${name}-file <path>`, `Read --${name} from a file, or "-" for stdin (mutually exclusive with --${name})`).conflicts(name).argParser(text));
   return cmd;
 }
 function resolveTextOrFile(opts, name, { required = true } = {}) {
   const literal = opts[name];
   const ref = opts[`${name}File`];
   if (literal !== void 0 && ref !== void 0) {
-    throw new InvalidArgumentError2(`--${name} and --${name}-file are mutually exclusive; provide only one.`);
+    throw new InvalidArgumentError3(`--${name} and --${name}-file are mutually exclusive; provide only one.`);
   }
   if (ref !== void 0) {
     return readFileOrStdin(ref);
   }
   if (literal === void 0 && required) {
-    throw new InvalidArgumentError2(`a ${name} is required: provide --${name} <text> or --${name}-file <path>.`);
+    throw new InvalidArgumentError3(`a ${name} is required: provide --${name} <text> or --${name}-file <path>.`);
   }
   return literal;
 }
@@ -127,7 +170,7 @@ function subjectArg(cmd, name, opts = {}) {
 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);
+  return defineOption(cmd, `--${entity}-id <id>`, description, numeric ? positiveInt : text, opts.mandatory);
 }
 function bodyOption(cmd, opts = {}) {
   return textOrFileOption(cmd, "body", { description: "Prose body content", ...opts });
@@ -717,7 +760,7 @@ function transformTransitions(response) {
 
 // src/commands/board/issues.ts
 function issues(parent) {
-  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");
+  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", text).option("--jql <jql>", "Additional JQL filter within the board", text);
   examples(cmd, [
     "42",
     "42 --limit 10",
@@ -741,7 +784,7 @@ function issues(parent) {
 import { Option as Option2 } from "commander";
 var BOARD_TYPES = ["scrum", "kanban", "simple"];
 function list(parent) {
-  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 Option2("--type <type>", "Board type filter").choices(BOARD_TYPES)).option("--name <name>", "Filter boards by name");
+  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", text).addOption(new Option2("--type <type>", "Board type filter").choices(BOARD_TYPES)).option("--name <name>", "Filter boards by name", text);
   examples(cmd, ["", "--limit 10", "--project PROJ", '--type scrum --name "Team Board"']);
   cmd.action(async (opts) => {
     const client = getClient();
@@ -772,7 +815,7 @@ var ASSIGNEE_TYPES = [
   "UNASSIGNED"
 ];
 function create(parent) {
-  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("--lead <username>", "Username of the component lead").addOption(new Option3("--assignee-type <type>", "Assignee strategy").choices(ASSIGNEE_TYPES));
+  const cmd = parent.command("create").description("Create a new component in a project").requiredOption("--project <key>", "Project key (e.g., AI)", text).requiredOption("--name <name>", "Component name", text).option("--lead <username>", "Username of the component lead", text).addOption(new Option3("--assignee-type <type>", "Assignee strategy").choices(ASSIGNEE_TYPES));
   textOrFileOption(cmd, "description", { description: "Component description" });
   examples(cmd, [
     "--project AI --name Backend",
@@ -797,40 +840,40 @@ function create(parent) {
 
 // src/commands/component/delete.ts
 function deleteComponent(parent) {
-  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");
+  const cmd = parent.command("delete").description("Delete a component, optionally reassigning its issues to another component").argument("<id>", "Component ID", positiveInt).option("--move-issues-to <id>", "Reassign existing issues to this component ID before deletion", text);
   examples(cmd, ["11289", "11289 --move-issues-to 11290"]);
   cmd.action(async (id, opts) => {
     const client = getClient();
-    await client.components.delete({ id, moveIssuesTo: opts.moveIssuesTo });
+    await client.components.delete({ id: String(id), moveIssuesTo: opts.moveIssuesTo });
     output({ deleted: true, componentId: id, ...opts.moveIssuesTo && { movedIssuesTo: opts.moveIssuesTo } });
   });
 }
 
 // src/commands/component/get.ts
 function get(parent) {
-  const cmd = parent.command("get <id>").description("Get a component by ID");
+  const cmd = parent.command("get").description("Get a component by ID").argument("<id>", "Component ID", positiveInt);
   examples(cmd, ["11289"]);
   cmd.action(async (id) => {
     const client = getClient();
-    const result = await client.components.get({ id });
+    const result = await client.components.get({ id: String(id) });
     output(transformComponent(result));
   });
 }
 
 // src/commands/component/issue-count.ts
 function issueCount(parent) {
-  const cmd = parent.command("issue-count <id>").description("Get the number of issues currently using this component");
+  const cmd = parent.command("issue-count").description("Get the number of issues currently using this component").argument("<id>", "Component ID", positiveInt);
   examples(cmd, ["11289"]);
   cmd.action(async (id) => {
     const client = getClient();
-    const result = await client.components.getRelatedIssueCounts({ id });
+    const result = await client.components.getRelatedIssueCounts({ id: String(id) });
     output(transformComponentIssueCounts(result));
   });
 }
 
 // src/commands/component/list.ts
 function list2(parent) {
-  const cmd = parent.command("list").description("List all components for a project").requiredOption("--project <key>", "Project key (e.g., AI)");
+  const cmd = parent.command("list").description("List all components for a project").requiredOption("--project <key>", "Project key (e.g., AI)", text);
   examples(cmd, ["--project AI"]);
   cmd.action(async (opts) => {
     const client = getClient();
@@ -848,7 +891,7 @@ var ASSIGNEE_TYPES2 = [
   "UNASSIGNED"
 ];
 function update(parent) {
-  const cmd = parent.command("update <id>").description("Update an existing component (only provided fields are changed)").option("--name <name>", "New component name").option("--lead <username>", "Username of the component lead (empty string clears it)").addOption(new Option4("--assignee-type <type>", "New assignee strategy").choices(ASSIGNEE_TYPES2));
+  const cmd = parent.command("update").description("Update an existing component (only provided fields are changed)").argument("<id>", "Component ID", positiveInt).option("--name <name>", "New component name", text).option("--lead <username>", "Username of the component lead (empty string clears it)", text).addOption(new Option4("--assignee-type <type>", "New assignee strategy").choices(ASSIGNEE_TYPES2));
   textOrFileOption(cmd, "description", { description: "New component description" });
   examples(cmd, [
     "11289 --name Backend",
@@ -863,7 +906,7 @@ function update(parent) {
       }
       const client = getClient();
       const result = await client.components.update({
-        id,
+        id: String(id),
         name: opts.name,
         description,
         leadUserName: opts.lead,
@@ -895,7 +938,7 @@ function registerComponentCommands(program) {
 
 // src/commands/field/options.ts
 function options(parent) {
-  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);
+  const cmd = parent.command("options").description("Get available options for a custom field").argument("<id>", "Field ID", text).option("--query <text>", "Filter options by text", 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();
@@ -911,7 +954,7 @@ function options(parent) {
 
 // src/commands/field/search.ts
 function search(parent) {
-  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);
+  const cmd = parent.command("search").description("Search for fields by name or ID").argument("<keyword>", "Search keyword", text).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();
@@ -944,9 +987,18 @@ async function resolveUserToken(token) {
   return token;
 }
 
+// src/utils/validators.ts
+import { InvalidArgumentError as InvalidArgumentError4 } from "commander";
+function issueKey(raw) {
+  if (!/^[A-Z][A-Z0-9]+-\d+$/.test(raw)) {
+    throw new InvalidArgumentError4("Must be a Jira issue key like PROJ-123.");
+  }
+  return raw;
+}
+
 // src/commands/issue/assign.ts
 function assign(parent) {
-  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');
+  const cmd = parent.command("assign").description('Assign an issue. --assignee is a username, "me", or "none" to unassign.').argument("<key>", "Issue key", issueKey).requiredOption("--assignee <user>", 'Username to assign, "me" for the current user, or "none" to unassign', text);
   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);
@@ -961,7 +1013,7 @@ function assign(parent) {
 
 // src/commands/issue/attachment/delete.ts
 function deleteAttachment(parent) {
-  const cmd = parent.command("delete <key>").description("Delete an attachment by ID");
+  const cmd = parent.command("delete").description("Delete an attachment by ID").argument("<key>", "Issue key", issueKey);
   subEntityOption(cmd, "attachment", { mandatory: true });
   examples(cmd, ["PROJ-123 --attachment-id 12345"]);
   cmd.action(async (key, opts) => {
@@ -975,7 +1027,7 @@ function deleteAttachment(parent) {
 import { mkdirSync as mkdirSync2 } from "fs";
 import { join as join3 } from "path";
 function downloadAll(parent) {
-  const cmd = parent.command("download-all <key>").description("Download all attachments from an issue").requiredOption("--output <dir>", "Local directory to save attachments into");
+  const cmd = parent.command("download-all").description("Download all attachments from an issue").argument("<key>", "Issue key", issueKey).requiredOption("--output <dir>", "Local directory to save attachments into", text);
   examples(cmd, ["PROJ-123 --output ./downloads"]);
   cmd.action(async (key, opts) => {
     const client = getClient();
@@ -1016,9 +1068,9 @@ function downloadAll(parent) {
 
 // src/commands/issue/attachment/download.ts
 function download(parent) {
-  const cmd = parent.command("download <key>").description("Download a single attachment by ID");
+  const cmd = parent.command("download").description("Download a single attachment by ID").argument("<key>", "Issue key", issueKey);
   subEntityOption(cmd, "attachment", { mandatory: true });
-  cmd.requiredOption("--output <path>", "Local file path to save the attachment");
+  cmd.requiredOption("--output <path>", "Local file path to save the attachment", text);
   examples(cmd, ["PROJ-123 --attachment-id 12345 --output ./report.pdf"]);
   cmd.action(async (key, opts) => {
     const client = getClient();
@@ -1043,7 +1095,7 @@ function download(parent) {
 
 // src/commands/issue/attachment/list.ts
 function list3(parent) {
-  const cmd = parent.command("list <key>").description("List attachments on an issue");
+  const cmd = parent.command("list").description("List attachments on an issue").argument("<key>", "Issue key", issueKey);
   examples(cmd, ["PROJ-123"]);
   cmd.action(async (key) => {
     const client = getClient();
@@ -1068,7 +1120,7 @@ function list3(parent) {
 
 // src/commands/issue/attachment/upload.ts
 function upload(parent) {
-  const cmd = parent.command("upload <key>").description("Upload attachments to an issue").requiredOption("--files <paths>", "Comma-separated file paths to upload");
+  const cmd = parent.command("upload").description("Upload attachments to an issue").argument("<key>", "Issue key", issueKey).requiredOption("--files <paths>", "Comma-separated file paths to upload", text);
   examples(cmd, ["PROJ-123 --files ./report.pdf", "PROJ-123 --files ./a.txt,./b.png"]);
   cmd.action(async (key, opts) => {
     const client = getClient();
@@ -1111,7 +1163,7 @@ function registerAttachmentCommands(parent) {
 
 // src/commands/issue/batch-changelog.ts
 function batchChangelog(parent) {
-  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);
+  const cmd = parent.command("batch-changelog").description("Get changelogs for multiple issues at once").argument("<keys>", "Comma-separated issue keys", text).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();
@@ -1131,14 +1183,16 @@ function batchChangelog(parent) {
 }
 
 // src/commands/issue/batch-create.ts
+import { z } from "zod";
+var issuesSchema = z.array(z.record(z.unknown())).min(1, "must be a non-empty array");
 function batchCreate(parent) {
-  const cmd = parent.command("batch-create").description("Create multiple issues from a JSON array").requiredOption("--issues <json>", "JSON array of issue objects");
+  const cmd = parent.command("batch-create").description("Create multiple issues from a JSON array").requiredOption("--issues <json>", "JSON array of issue objects", jsonShape(issuesSchema));
   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 parsed = opts.issues;
     const results = [];
     for (const issue of parsed) {
       try {
@@ -1154,7 +1208,7 @@ function batchCreate(parent) {
 
 // src/commands/issue/changelog.ts
 function changelog(parent) {
-  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);
+  const cmd = parent.command("changelog").description("Get changelog for an issue").argument("<key>", "Issue key", issueKey).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();
@@ -1182,7 +1236,7 @@ var CLONE_FIELDS = [
   "issuelinks"
 ];
 function clone(parent) {
-  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");
+  const cmd = parent.command("clone").description("Clone an issue (create a duplicate with the same fields)").argument("<key>", "Issue key", issueKey).option("--summary <text>", 'Override the summary (default: "CLONE - <original>")', text).option("--project <key>", "Create in a different project", text).option("--assignee <username>", "Override assignee", text).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"',
@@ -1259,7 +1313,7 @@ function clone(parent) {
 
 // src/commands/issue/comment/create.ts
 function create2(parent) {
-  const cmd = parent.command("create <key>").description("Add a comment to an issue");
+  const cmd = parent.command("create").description("Add a comment to an issue").argument("<key>", "Issue key", issueKey);
   bodyOption(cmd);
   examples(cmd, ['PROJ-123 --body "Fixed in latest build"']);
   cmd.action(async (key, opts) => {
@@ -1272,7 +1326,7 @@ function create2(parent) {
 
 // src/commands/issue/comment/delete.ts
 function deleteComment(parent) {
-  const cmd = parent.command("delete <key>").description("Delete a comment from an issue");
+  const cmd = parent.command("delete").description("Delete a comment from an issue").argument("<key>", "Issue key", issueKey);
   subEntityOption(cmd, "comment", { mandatory: true });
   examples(cmd, ["PROJ-123 --comment-id 12345"]);
   cmd.action(async (key, opts) => {
@@ -1284,7 +1338,7 @@ function deleteComment(parent) {
 
 // src/commands/issue/comment/update.ts
 function update2(parent) {
-  const cmd = parent.command("update <key>").description("Update an existing comment");
+  const cmd = parent.command("update").description("Update an existing comment").argument("<key>", "Issue key", issueKey);
   subEntityOption(cmd, "comment", { mandatory: true });
   bodyOption(cmd);
   examples(cmd, ['PROJ-123 --comment-id 12345 --body "Updated comment text"']);
@@ -1314,32 +1368,40 @@ function registerCommentCommands(parent) {
 }
 
 // src/commands/issue/create.ts
+import { z as z2 } from "zod";
+var customFieldsSchema = z2.record(z2.unknown());
 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("--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"}')`);
+  const cmd = parent.command("create").description("Create a new issue").requiredOption("--project <key>", "Project key or ID", text).requiredOption("--type <name>", "Issue type name (e.g., Task, Bug, Story)", text).requiredOption("--summary <text>", "Issue summary/title", text).option("--assignee <user>", 'Assignee. Username, "me", or "none" to leave unassigned.', text).option("--reporter <user>", 'Reporter. Username or "me".', text).option("--priority <name>", "Priority name (e.g., High, Medium, Low)", text).option("--labels <labels>", "Comma-separated labels", text).option("--components <names>", "Comma-separated component names", text).option("--fix-versions <versions>", "Comma-separated fix version names", text).option("--due-date <date>", "Due date in YYYY-MM-DD format", date).option("--parent <key>", "Parent issue key (for subtasks)", issueKey).option(
+    "--custom-fields <json>",
+    `Additional custom fields as JSON (e.g., '{"customfield_10100": "EPIC-1"}')`,
+    jsonShape(customFieldsSchema)
+  );
   textOrFileOption(cmd, "description", { description: "Issue description in wiki markup" });
   examples(cmd, [
     '--project PROJ --type Task --summary "Fix login bug"',
-    '--project PROJ --type Story --summary "New feature" --assignee jsmith --priority High',
+    '--project PROJ --type Story --summary "New feature" --assignee me --priority High',
     '--project PROJ --type Bug --summary "Urgent" --labels urgent,production --components Backend'
   ]);
   cmd.action(
     async (opts) => {
       const description = resolveTextOrFile(opts, "description", { required: false });
+      const assignee = opts.assignee !== void 0 ? await resolveUserToken(opts.assignee) : void 0;
+      const reporter = opts.reporter !== void 0 ? await resolveUserToken(opts.reporter) : void 0;
       const client = getClient();
       const result = await client.issues.create({
         projectKeyOrId: opts.project,
         issueTypeName: opts.type,
         summary: opts.summary,
         description,
-        assignee: opts.assignee,
-        reporter: opts.reporter,
+        assignee: assignee ?? void 0,
+        reporter: reporter ?? void 0,
         priority: opts.priority,
         labels: opts.labels?.split(",").map((l) => l.trim()),
         components: opts.components?.split(",").map((c) => c.trim()),
         fixVersions: opts.fixVersions?.split(",").map((v) => v.trim()),
         dueDate: opts.dueDate,
         parent: opts.parent,
-        customFields: opts.customFields ? JSON.parse(opts.customFields) : void 0
+        customFields: opts.customFields
       });
       output(transformCreatedIssue(result));
     }
@@ -1348,7 +1410,7 @@ function create3(parent) {
 
 // src/commands/issue/delete.ts
 function deleteIssue(parent) {
-  const cmd = parent.command("delete <key>").description("Delete an issue").option("--delete-subtasks", "Also delete subtasks (default: false)");
+  const cmd = parent.command("delete").description("Delete an issue").argument("<key>", "Issue key", issueKey).option("--delete-subtasks", "Also delete subtasks (default: false)");
   examples(cmd, ["PROJ-123", "PROJ-123 --delete-subtasks"]);
   cmd.action(async (key, opts) => {
     const client = getClient();
@@ -1359,7 +1421,7 @@ function deleteIssue(parent) {
 
 // src/commands/issue/dev-status.ts
 function devStatus(parent) {
-  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");
+  const cmd = parent.command("dev-status").description("Get development status (PRs, commits, branches, builds) for an issue").argument("<key>", "Issue key", issueKey).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();
@@ -1453,7 +1515,7 @@ var DEFAULT_FIELDS = [
 
 // src/commands/issue/get.ts
 function get2(parent) {
-  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")');
+  const cmd = parent.command("get").description("Get issue details").argument("<key>", "Issue key", issueKey).option("--fields <fields>", "Comma-separated fields to return (defaults to essential fields)", text).option("--all-fields", "Return all fields instead of defaults").option("--expand <expand>", 'Expand options (e.g., "transitions", "changelog")', text);
   examples(cmd, [
     "PROJ-123",
     "PROJ-123 --fields summary,status,assignee",
@@ -1474,7 +1536,7 @@ function get2(parent) {
 
 // src/commands/issue/link-epic.ts
 function linkEpic(parent) {
-  const cmd = parent.command("link-epic <keys...>").description("Link one or more issues to an epic").requiredOption("--epic <epicKey>", "Epic issue key");
+  const cmd = parent.command("link-epic").description("Link one or more issues to an epic").argument("<keys...>", "Issue keys to link", issueKey).requiredOption("--epic <epicKey>", "Epic issue key", issueKey);
   examples(cmd, ["PROJ-456 --epic PROJ-123", "PROJ-456 PROJ-457 PROJ-458 --epic PROJ-123"]);
   cmd.action(async (keys, opts) => {
     const client = getClient();
@@ -1517,7 +1579,7 @@ function linkTypes(parent) {
 
 // src/commands/issue/link.ts
 function link(parent) {
-  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")');
+  const cmd = parent.command("link").description("Link two issues together").requiredOption("--type <name>", "Link type name (e.g., 'Blocks', 'Duplicate', 'Relates')", text).requiredOption("--from <key>", 'Source issue key (e.g., the issue that "blocks")', issueKey).requiredOption("--to <key>", 'Target issue key (e.g., the issue that "is blocked by")', issueKey);
   commentOption(cmd, { description: "Optional comment" });
   examples(cmd, [
     "--type Relates --from AI-154 --to AI-149",
@@ -1543,7 +1605,7 @@ function link(parent) {
 
 // src/commands/issue/search.ts
 function search2(parent) {
-  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");
+  const cmd = parent.command("search").description("Search issues using JQL").argument("<jql>", "JQL query string", text).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)", text).option("--all-fields", "Return all fields instead of defaults");
   examples(cmd, [
     '"project = PROJ AND status = Open"',
     '"assignee = currentUser()" --limit 10 --fields summary,status',
@@ -1564,7 +1626,7 @@ function search2(parent) {
 
 // src/commands/issue/transition.ts
 function transition(parent) {
-  const cmd = parent.command("transition <key>").description("Transition issue to a new status").requiredOption("--to <idOrName>", "Transition ID, or status name (case-insensitive)");
+  const cmd = parent.command("transition").description("Transition issue to a new status").argument("<key>", "Issue key", issueKey).requiredOption("--to <idOrName>", "Transition ID, or status name (case-insensitive)", text);
   commentOption(cmd, { description: "Comment to add during transition" });
   examples(cmd, [
     "PROJ-123 --to 31",
@@ -1602,7 +1664,7 @@ function transition(parent) {
 
 // src/commands/issue/transitions.ts
 function transitions(parent) {
-  const cmd = parent.command("transitions <key>").description("Get available transitions for an issue");
+  const cmd = parent.command("transitions").description("Get available transitions for an issue").argument("<key>", "Issue key", issueKey);
   examples(cmd, ["PROJ-123"]);
   cmd.action(async (key) => {
     const client = getClient();
@@ -1616,30 +1678,33 @@ function transitions(parent) {
 
 // src/commands/issue/unlink.ts
 function unlink2(parent) {
-  const cmd = parent.command("unlink <id>").description("Remove a link between two issues");
+  const cmd = parent.command("unlink").description("Remove a link between two issues").argument("<id>", "Link ID", positiveInt);
   examples(cmd, ["12345"]);
   cmd.action(async (id) => {
     const client = getClient();
-    await client.links.remove({ linkId: id });
+    await client.links.remove({ linkId: String(id) });
     output({ removed: true, linkId: id });
   });
 }
 
+// src/commands/issue/update.ts
+import { z as z3 } from "zod";
+
 // src/utils/multi-value.ts
-import { InvalidArgumentError as InvalidArgumentError3 } from "commander";
+import { InvalidArgumentError as InvalidArgumentError5 } from "commander";
 function parseMultiValue(flagName, raw) {
   const items = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
   if (items.length === 0) {
-    throw new InvalidArgumentError3(`${flagName} cannot be empty`);
+    throw new InvalidArgumentError5(`${flagName} cannot be empty`);
   }
   const lonePrefix = items.find((s) => s === "+" || s === "-");
   if (lonePrefix !== void 0) {
-    throw new InvalidArgumentError3(`${flagName} has an empty value after '${lonePrefix}' prefix`);
+    throw new InvalidArgumentError5(`${flagName} has an empty value after '${lonePrefix}' prefix`);
   }
   const prefixed = items.filter((s) => s.startsWith("+") || s.startsWith("-"));
   const bare = items.filter((s) => !s.startsWith("+") && !s.startsWith("-"));
   if (prefixed.length > 0 && bare.length > 0) {
-    throw new InvalidArgumentError3(
+    throw new InvalidArgumentError5(
       `${flagName} mixes set and mutate syntax. Either all values have +/- prefix, or none do.`
     );
   }
@@ -1652,6 +1717,7 @@ function parseMultiValue(flagName, raw) {
 }
 
 // src/commands/issue/update.ts
+var fieldsSchema = z3.record(z3.unknown());
 function buildUpdateOps(parsed, wrap) {
   if (parsed.mode !== "mutate") return void 0;
   return [...parsed.adds.map((v) => ({ add: wrap(v) })), ...parsed.removes.map((v) => ({ remove: wrap(v) }))];
@@ -1661,7 +1727,11 @@ function buildSetValue(parsed, wrap) {
   return parsed.values.map(wrap);
 }
 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("--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")');
+  const cmd = parent.command("update").description("Update issue fields").argument("<key>", "Issue key", issueKey).option(
+    "--fields <json>",
+    "JSON string of fields to update (advanced; merges with shortcuts, wins on conflict)",
+    jsonShape(fieldsSchema)
+  ).option("--no-notify-users", "Suppress notification emails (default: notify)").option("--attachments <paths>", "Comma-separated local file paths to attach", text).option("--summary <text>", "Set the issue summary", text).option("--priority <name>", "Set the priority by name (e.g. High)", text).option("--assignee <user>", 'Set the assignee. Username, "me", or "none" to unassign.', text).option("--labels <list>", 'Set labels ("a,b,c") or mutate ("+add,-remove")', text).option("--components <list>", 'Set components ("a,b") or mutate ("+add,-remove")', text).option("--fix-versions <list>", 'Set fix versions ("1.0,2.0") or mutate ("+1.0,-0.9")', text);
   textOrFileOption(cmd, "description", { description: "Set the issue description (wiki markup)" });
   examples(cmd, [
     'PROJ-123 --summary "New title"',
@@ -1710,8 +1780,7 @@ function update3(parent) {
       if (ops) updateOps.fixVersions = ops;
     }
     if (opts.fields) {
-      const parsedFields = JSON.parse(opts.fields);
-      Object.assign(fields, parsedFields);
+      Object.assign(fields, opts.fields);
     }
     const client = getClient();
     const didFieldUpdate = Object.keys(fields).length > 0 || Object.keys(updateOps).length > 0;
@@ -1743,7 +1812,7 @@ function update3(parent) {
 
 // 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("--started <datetime>", "Start time in ISO 8601 format");
+  const cmd = parent.command("create").description("Log time spent on an issue").argument("<key>", "Issue key", issueKey).requiredOption("--time <timeSpent>", "Time spent (e.g., '2h', '30m', '1d 4h')", text).option("--started <datetime>", "Start time in ISO 8601 format", dateTime);
   commentOption(cmd, { description: "Worklog comment" });
   examples(cmd, [
     "PROJ-123 --time 2h",
@@ -1767,11 +1836,12 @@ function create4(parent) {
 import { Option as Option5 } from "commander";
 var ADJUST_ESTIMATE = ["new", "leave", "manual", "auto"];
 function deleteWorklog(parent) {
-  const cmd = parent.command("delete <key>").description("Delete a worklog entry");
+  const cmd = parent.command("delete").description("Delete a worklog entry").argument("<key>", "Issue key", issueKey);
   subEntityOption(cmd, "worklog", { mandatory: true });
-  cmd.addOption(new Option5("--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(
+  cmd.addOption(new Option5("--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"', text).option(
     "--increase-by <amount>",
-    'Amount to increase the estimate by; required when --adjust-estimate is "manual"'
+    'Amount to increase the estimate by; required when --adjust-estimate is "manual"',
+    text
   );
   examples(cmd, [
     "PROJ-123 --worklog-id 12345",
@@ -1795,7 +1865,7 @@ function deleteWorklog(parent) {
 
 // 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);
+  const cmd = parent.command("list").description("Get worklogs for an issue").argument("<key>", "Issue key", issueKey).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();
@@ -1812,9 +1882,9 @@ function list4(parent) {
 import { Option as Option6 } from "commander";
 var ADJUST_ESTIMATE2 = ["new", "leave", "auto"];
 function update4(parent) {
-  const cmd = parent.command("update <key>").description("Update an existing worklog entry");
+  const cmd = parent.command("update").description("Update an existing worklog entry").argument("<key>", "Issue key", issueKey);
   subEntityOption(cmd, "worklog", { mandatory: true });
-  cmd.option("--time <timeSpent>", "Time spent (e.g., '2h', '30m', '1d 4h')").option("--started <datetime>", "Start time in ISO 8601 format").addOption(new Option6("--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"');
+  cmd.option("--time <timeSpent>", "Time spent (e.g., '2h', '30m', '1d 4h')", text).option("--started <datetime>", "Start time in ISO 8601 format", dateTime).addOption(new Option6("--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"', text);
   commentOption(cmd, { description: "Worklog comment" });
   examples(cmd, [
     'PROJ-123 --worklog-id 12345 --time "1h 30m"',
@@ -1889,7 +1959,7 @@ function registerIssueCommands(program) {
 
 // src/commands/project/list.ts
 function list5(parent) {
-  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)");
+  const cmd = parent.command("list").description("List all projects").option("--expand <expand>", 'Expand options (e.g., "description,lead")', text).option("--include-archived", "Include archived projects (default: false)");
   examples(cmd, ["", "--expand description,lead", "--include-archived"]);
   cmd.action(async (opts) => {
     const client = getClient();
@@ -1900,7 +1970,7 @@ function list5(parent) {
 
 // src/commands/project/versions.ts
 function versions(parent) {
-  const cmd = parent.command("versions <key>").description("Get all versions for a project").option("--expand <expand>", "Expand options");
+  const cmd = parent.command("versions").description("Get all versions for a project").argument("<key>", "Project key", text).option("--expand <expand>", "Expand options", text);
   examples(cmd, ["PROJ", "PROJ --expand operations"]);
   cmd.action(async (key, opts) => {
     const client = getClient();
@@ -1919,7 +1989,7 @@ function registerProjectCommands(program) {
 
 // src/commands/sprint/create.ts
 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");
+  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", text).option("--start-date <date>", "Start date in ISO 8601 format", text).option("--end-date <date>", "End date in ISO 8601 format", text).option("--goal <goal>", "Sprint goal", text);
   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"'
@@ -1952,7 +2022,7 @@ function deleteSprint(parent) {
 // src/commands/sprint/issues.ts
 import { Argument as Argument3 } from "commander";
 function issues2(parent) {
-  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");
+  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", text).option("--jql <jql>", "Additional JQL filter within the sprint", text);
   examples(cmd, [
     "100",
     "100 --limit 20",
@@ -1992,7 +2062,7 @@ function list6(parent) {
 import { Argument as Argument4, Option as Option8 } from "commander";
 var SPRINT_STATES2 = ["future", "active", "closed"];
 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 Option8("--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");
+  const cmd = parent.command("update").description("Update an existing sprint").addArgument(new Argument4("<id>", "Sprint ID").argParser(positiveInt)).option("--name <name>", "New sprint name", text).addOption(new Option8("--state <state>", "New sprint state").choices(SPRINT_STATES2)).option("--start-date <date>", "New start date in ISO 8601 format", text).option("--end-date <date>", "New end date in ISO 8601 format", text).option("--goal <goal>", "New sprint goal", text);
   examples(cmd, [
     '100 --name "Sprint 10 - Extended"',
     "100 --state active",
@@ -2050,13 +2120,14 @@ function getTokenClient(options2 = {}) {
 
 // src/commands/token/create.ts
 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(
+  const cmd = parent.command("create").description("Create a Personal Access Token. The secret is returned exactly once.").requiredOption("--name <name>", "Token name", text).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(
+  ).option("--basic-username <u>", "Override $JIRA_BASIC_USERNAME", text).option(
     "--basic-password <p>",
-    "Override $JIRA_BASIC_PASSWORD (caution: visible in process table; prefer the env var)"
+    "Override $JIRA_BASIC_PASSWORD (caution: visible in process table; prefer the env var)",
+    text
   );
   examples(cmd, [["--name my-pat", "non-expiring"], "--name svc-token --expiration-duration 365"]);
   cmd.action(async (opts) => {
@@ -2076,9 +2147,10 @@ function create6(parent) {
 
 // src/commands/token/list.ts
 function list7(parent) {
-  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(
+  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", text).option(
     "--basic-password <p>",
-    "Override $JIRA_BASIC_PASSWORD (caution: visible in process table; prefer the env var)"
+    "Override $JIRA_BASIC_PASSWORD (caution: visible in process table; prefer the env var)",
+    text
   );
   examples(cmd, [""]);
   cmd.action(async (opts) => {
@@ -2092,9 +2164,10 @@ function list7(parent) {
 
 // src/commands/token/revoke.ts
 function revoke(parent) {
-  const cmd = parent.command("revoke").description("Revoke a Personal Access Token by id").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", text).option(
     "--basic-password <p>",
-    "Override $JIRA_BASIC_PASSWORD (caution: visible in process table; prefer the env var)"
+    "Override $JIRA_BASIC_PASSWORD (caution: visible in process table; prefer the env var)",
+    text
   );
   subjectArg(cmd, "tokenId", { parser: positiveInt, description: "Token id to revoke" });
   examples(cmd, ["173"]);
@@ -2123,7 +2196,7 @@ function registerTokenCommands(program) {
 
 // src/commands/user/get.ts
 function get3(parent) {
-  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");
+  const cmd = parent.command("get").description("Get a user profile by exact username or key").argument("<username>", "Username or user key", text).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();
@@ -2145,7 +2218,7 @@ function me(parent) {
 
 // src/commands/user/search.ts
 function search3(parent) {
-  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);
+  const cmd = parent.command("search").description("Search users by partial username, display name or email").argument("<query>", "Search query", text).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, ["Smith", '"John Smith"', "jsmith@example.com --limit 5"]);
   cmd.action(async (query, opts) => {
     const client = getClient();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jiradc-cli",
-  "version": "1.0.24",
+  "version": "1.0.25-g6beae79.4",
   "publish": true,
   "type": "module",
   "main": "dist/index.js",
@@ -12,6 +12,7 @@
   ],
   "dependencies": {
     "commander": "^13.1.0",
+    "zod": "^3.25.67",
     "jira-data-center-client": "1.0.39"
   },
   "devDependencies": {
@@ -22,8 +23,8 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^4.0.16",
-    "cli-utils": "1.0.0",
     "config-eslint": "0.0.0",
+    "cli-utils": "1.0.0",
     "config-typescript": "0.0.0"
   },
   "engines": {