jirallm 0.5.0 → 0.6.0

package/dist/cli/index.js

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-import { Command } from 'commander';
+import { pathToFileURL } from 'node:url';
+import { Command, Option } from 'commander';
 import updateNotifier from 'update-notifier';
-import { select, isCancel, cancel } from '@clack/prompts';
 import { JiraExporter } from '../lib/exporter.js';
-import { findOrgsByProjectKey, loadProfile, readConfig } from '../lib/config.js';
+import { listOrgs, loadProfile } from '../lib/config.js';
+import { resolveOrgInteractive } from './resolveOrg.js';
 import { parseIssueKeyArgs } from './issueKey.js';
 import { runInit } from './commands/init.js';
 import { runAuthSet, runAuthRm, runAuthList, runAuthStatus } from './commands/auth.js';
 import { runOrgsList, runOrgsRemove, runProjectRemove } from './commands/orgs.js';
 import { runDoctor } from './commands/doctor.js';
 import { runSetup } from './commands/setup.js';
-import { runComment, runDeleteComment } from './commands/comment.js';
+import { runComment, runCommentList, runDeleteComment } from './commands/comment.js';
 import { runBoardIssues } from './commands/board.js';
 import { runTransition } from './commands/transition.js';
 import { runWorklog } from './commands/worklog.js';
@@ -33,22 +34,6 @@ import { runAttach, runAttachRemove } from './commands/attach.js';
 import { runWatchers } from './commands/watchers.js';
 import { runUpgrade } from './commands/upgrade.js';
 import { parseFieldsFlag, resolveFieldSet } from '../lib/exportFields.js';
-async function pickOrgInteractively(candidates, projectKey) {
-    const raw = readConfig();
-    const choice = await select({
-        message: `Multiple orgs have a "${projectKey}" project. Which one?`,
-        options: candidates.map((name) => ({
-            value: name,
-            label: name,
-            hint: raw.orgs?.[name]?.base_url,
-        })),
-    });
-    if (isCancel(choice)) {
-        cancel('Cancelled.');
-        process.exit(0);
-    }
-    return choice;
-}
 async function resolveOrgAndKeys(rawArgs, flags) {
     const parsed = parseIssueKeyArgs(rawArgs);
     const keys = parsed.keys;
@@ -56,25 +41,15 @@ async function resolveOrgAndKeys(rawArgs, flags) {
         throw new Error(`--org "${flags.org}" conflicts with the org/ prefix "${parsed.org}/" in the issue keys.`);
     }
     const projectKey = flags.project ?? parsed.projectKey;
-    const explicitOrg = flags.org ?? parsed.org;
-    if (explicitOrg)
-        return { org: explicitOrg, projectKey, keys };
-    const matches = findOrgsByProjectKey(parsed.projectKey);
-    if (matches.length === 0) {
-        throw new Error(`Project "${parsed.projectKey}" not found in any configured org. ` +
-            'Run `jirallm init` to add it, or pass --org explicitly.');
-    }
-    if (matches.length === 1)
-        return { org: matches[0], projectKey, keys };
-    if (!process.stdin.isTTY) {
-        throw new Error(`Project "${parsed.projectKey}" exists in multiple orgs (${matches.join(', ')}). ` +
-            `Pass --org or use the org/${parsed.projectKey}-N syntax.`);
-    }
-    const org = await pickOrgInteractively(matches, parsed.projectKey);
+    const org = await resolveOrgInteractive(parsed.org, flags.org, parsed.projectKey);
     return { org, projectKey, keys };
 }
-async function runExport(rawArgs, flags) {
+async function runExport(rawArgs, flags, program) {
     if (rawArgs.length === 0) {
+        if (listOrgs().length > 0) {
+            program.outputHelp();
+            process.exit(0);
+        }
         await runInit();
         process.exit(0);
     }
@@ -146,6 +121,10 @@ async function runExport(rawArgs, flags) {
         console.log(`Project:       ${projectKey}`);
         console.log(`Base URL:      ${baseUrl}`);
         console.log(`Output dir:    ${outputDir}`);
+        console.log(`Include subtasks: ${includeSubtasks}`);
+        console.log(`With history:  ${flags.withHistory ?? false}`);
+        console.log(`With worklog:  ${flags.withWorklog ?? false}`);
+        console.log(`Video frames:  ${videoEnabled ? `enabled (fps=${fps}, maxFrames=${maxFrames})` : 'disabled'}`);
         console.log(`Issues (${keys.length}): ${keys.join(', ')}`);
         console.log(`Field preset:  ${fieldSelector?.preset ?? '(default)'}`);
         if (fieldSelector?.include?.length)
@@ -194,49 +173,53 @@ async function runExport(rawArgs, flags) {
         process.exit(1);
     }
 }
-const program = new Command();
-program.enablePositionalOptions();
-const pkg = createRequire(import.meta.url)('../../package.json');
-program.name(pkg.name).description(pkg.description).version(pkg.version);
-const notifier = updateNotifier({ pkg, updateCheckInterval: 1000 * 60 * 60 * 24 });
-if (!process.argv.includes('--json')) {
-    notifier.notify({
-        defer: true,
-        isGlobal: true,
-        message: `Update available {currentVersion} → {latestVersion}\nRun \`${pkg.name} upgrade\` to update.`,
-    });
-}
-function addExportOptions(cmd) {
-    return cmd
-        .option('-o, --org <name>', 'Organization name from config (auto-resolved from issue prefix if unique)')
-        .option('-P, --project <key>', 'Project key override')
-        .option('--output-dir <path>', 'Output directory (default: ./jira-export)')
-        .option('--base-url <url>', 'Jira base URL (overrides config)')
-        .option('--user-email <email>', 'Jira user email (overrides config)')
-        .option('--api-token <token>', 'Jira API token (overrides keychain)')
-        .option('--no-video-frames', 'Disable video frame extraction')
-        .option('--fps <n>', 'Frame extraction FPS')
-        .option('--max-frames <n>', 'Max frames kept per video')
-        .option('--include-subtasks', 'Fetch and include subtask metadata')
-        .option('--fields <list>', 'Comma-separated friendly field names to include in frontmatter. Use +name/-name to add/remove, or "all" | "default" | "minimal".')
-        .option('--with-history', 'Include full field-change history (not just status changes)')
-        .option('--with-worklog', 'Include worklogs')
-        .option('--dry-run', 'Resolve config & print plan without calling Jira or writing files');
-}
-addExportOptions(program.argument('[issue-keys...]', 'Jira issue keys, e.g. PROJ-123 or acme/PROJ-123'))
-    .action(async (keys, flags) => {
-    await runExport(keys, flags);
-})
-    .addHelpText('after', `
+export function buildProgram() {
+    const program = new Command();
+    program.enablePositionalOptions();
+    const pkg = createRequire(import.meta.url)('../../package.json');
+    program.name(pkg.name).description(pkg.description).version(pkg.version);
+    const notifier = updateNotifier({ pkg, updateCheckInterval: 1000 * 60 * 60 * 24 });
+    if (!process.argv.includes('--json')) {
+        notifier.notify({
+            defer: true,
+            isGlobal: true,
+            message: `Update available {currentVersion} → {latestVersion}\nRun \`${pkg.name} upgrade\` to update.`,
+        });
+    }
+    function addExportOptions(cmd) {
+        return cmd
+            .option('-o, --org <name>', 'Organization name from config (auto-resolved from issue prefix if unique)')
+            .option('-P, --project <key>', 'Project key override')
+            .option('--output-dir <path>', 'Output directory (default: ./jira-export)')
+            .option('--base-url <url>', 'Jira base URL (overrides config)')
+            .option('--user-email <email>', 'Jira user email (overrides config)')
+            .option('--api-token <token>', 'Jira API token (overrides keychain)')
+            .option('--no-video-frames', 'Disable video frame extraction')
+            .option('--fps <n>', 'Frame extraction FPS')
+            .option('--max-frames <n>', 'Max frames kept per video')
+            .option('--include-subtasks', 'Fetch subtask metadata (may already be enabled via org config).')
+            .option('--fields <list>', 'Comma-separated friendly field names to include in frontmatter. Use +name/-name to add/remove, or "all" | "default" | "minimal".')
+            .option('--with-history', 'Include full field-change history (not just status changes)')
+            .option('--with-worklog', 'Include worklogs')
+            .option('--dry-run', 'Resolve config & print plan without calling Jira or writing files');
+    }
+    addExportOptions(program.argument('[issue-keys...]', 'Jira issue keys, e.g. PROJ-123 or acme/PROJ-123'))
+        .action(async (keys, flags) => {
+        await runExport(keys, flags, program);
+    })
+        .addHelpText('after', `
+Read-command output auto-switches to JSON when piped (stdout is not a TTY);
+pass --json to force it explicitly.
+
 Examples:
   $ jirallm init
   $ jirallm PROJ-123                       # auto-resolves org from PROJ prefix
   $ jirallm acme/PROJ-123                  # disambiguate when multiple orgs have PROJ
+  $ jirallm --org acme PROJ-123            # or pass --org when multiple orgs have PROJ
   $ jirallm PROJ-123 PROJ-124 --output-dir ./context
   $ jirallm PROJ-123 --no-video-frames
   $ jirallm PROJ-123 --fps 2 --max-frames 6
   $ jirallm PROJ-123 --include-subtasks
-  $ jirallm --org acme PROJ-123
   $ jirallm export PROJ-123
   $ jirallm fetch PROJ-123 --with-comments --with-history
   $ jirallm fetch PROJ-123 --full
@@ -246,235 +229,277 @@ Examples:
 
 Run \`jirallm <command> --help\` for command-specific options.
 `);
-addExportOptions(program.command('export [issue-keys...]'))
-    .description('Export issues as LLM-ready context bundles (same as the default command).')
-    .action(async (keys, flags) => {
-    await runExport(keys, flags);
-});
-program
-    .command('init')
-    .description('Interactive setup wizard — creates an org or adds a project, and stores the API token in your OS keychain')
-    .action(async () => {
-    await runInit();
-})
-    .addHelpText('after', '\nExample:\n  $ jirallm init\n');
-const auth = program.command('auth').description('Manage stored API tokens (per organization)');
-auth
-    .command('set')
-    .description('Store/replace the API token for an organization')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .action(async (opts) => {
-    await runAuthSet(opts.org);
-});
-auth
-    .command('rm')
-    .description('Remove the stored API token for an organization')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .option('-y, --yes', 'Skip confirmation prompt')
-    .action(async (opts) => {
-    await runAuthRm(opts.org, { yes: opts.yes });
-});
-auth
-    .command('list')
-    .description('List all orgs and the resolved state of their API tokens')
-    .action(async () => {
-    await runAuthList();
-});
-auth
-    .command('status')
-    .description('Show whether a token is resolvable for an org (exits non-zero if missing)')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .action(async (opts) => {
-    await runAuthStatus(opts.org);
-});
-auth.addHelpText('after', `
+    addExportOptions(program.command('export [issue-keys...]'))
+        .description('Export issues as LLM-ready context bundles (same as the default command).')
+        .action(async (keys, flags) => {
+        await runExport(keys, flags, program);
+    });
+    program
+        .command('init')
+        .description('Interactive setup wizard — creates an org or adds a project, and stores the API token in your OS keychain')
+        .option('--org <name>', 'Organization name (non-interactive)')
+        .option('--base-url <url>', 'Jira base URL (non-interactive)')
+        .option('--email <email>', 'Jira user email (non-interactive)')
+        .option('--project <key>', 'Project key (non-interactive)')
+        .option('--token-stdin', 'Read the API token from stdin (non-interactive)')
+        .option('-y, --yes', 'Skip confirmation prompts (non-interactive)')
+        .action(async (opts) => {
+        await runInit(opts);
+    })
+        .addHelpText('after', `
+A token stored in your OS keychain is preferred. As a fallback, the API token may be
+supplied via the JIRALLM_API_TOKEN environment variable (or JIRALLM_API_TOKEN_<ORG>
+for a specific org) when no keychain token is stored.
+
+Examples:
+  $ jirallm init
+  $ jirallm init --org acme --base-url https://acme.atlassian.net --email me@acme.com --project PROJ --token-stdin --yes
+`);
+    const auth = program.command('auth').description('Manage stored API tokens (per organization)');
+    auth
+        .command('set')
+        .description('Store/replace the API token for an organization')
+        .requiredOption('-o, --org <name>', 'Organization name')
+        .action(async (opts) => {
+        await runAuthSet(opts.org);
+    });
+    auth
+        .command('rm')
+        .description('Remove the stored API token for an organization')
+        .requiredOption('-o, --org <name>', 'Organization name')
+        .option('-y, --yes', 'Skip confirmation prompt')
+        .action(async (opts) => {
+        await runAuthRm(opts.org, { yes: opts.yes });
+    });
+    auth
+        .command('list')
+        .description('List all orgs and the resolved state of their API tokens')
+        .action(async () => {
+        await runAuthList();
+    });
+    auth
+        .command('status')
+        .description('Show whether a token is resolvable for an org (exits non-zero if missing)')
+        .requiredOption('-o, --org <name>', 'Organization name')
+        .action(async (opts) => {
+        await runAuthStatus(opts.org);
+    });
+    auth.addHelpText('after', `
+Tokens are stored in your OS keychain. As a fallback, an API token may be supplied via
+the JIRALLM_API_TOKEN environment variable (or JIRALLM_API_TOKEN_<ORG> for a specific
+org) when no keychain token is stored; \`auth status\`/\`auth list\` report which source is used.
+
 Examples:
   $ jirallm auth list
   $ jirallm auth status --org acme
   $ jirallm auth set --org acme
   $ jirallm auth rm --org acme --yes
 `);
-const orgs = program.command('orgs').description('Inspect or modify organizations and their projects');
-orgs
-    .command('list')
-    .description('List all configured organizations and projects')
-    .action(async () => {
-    await runOrgsList();
-});
-orgs
-    .command('rm')
-    .description('Remove an organization (and its keychain token) along with all its projects')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .option('-y, --yes', 'Skip confirmation prompt')
-    .action(async (opts) => {
-    await runOrgsRemove(opts.org, { yes: opts.yes });
-});
-const orgProject = orgs.command('project').description('Manage projects within an organization');
-orgProject
-    .command('rm')
-    .description('Remove a project from an organization')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .requiredOption('-k, --key <key>', 'Project key')
-    .option('-y, --yes', 'Skip confirmation prompt')
-    .action(async (opts) => {
-    await runProjectRemove(opts.org, opts.key, { yes: opts.yes });
-});
-orgs.addHelpText('after', `
+    const orgs = program.command('orgs').description('Inspect or modify organizations and their projects');
+    orgs
+        .command('list')
+        .description('List all configured organizations and projects')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (opts) => {
+        await runOrgsList(opts);
+    });
+    orgs
+        .command('rm [org]')
+        .description('Remove an organization (and its keychain token) along with all its projects')
+        .option('-o, --org <name>', 'Organization name (alias for the positional)')
+        .option('--dry-run', 'Show what would be removed without changing config')
+        .option('-y, --yes', 'Skip confirmation prompt')
+        .action(async (orgArg, opts) => {
+        const org = orgArg ?? opts.org;
+        if (!org)
+            throw new Error('Organization name is required (positional or --org).');
+        await runOrgsRemove(org, { yes: opts.yes, dryRun: opts.dryRun });
+    });
+    const orgProject = orgs.command('project').description('Manage projects within an organization');
+    orgProject
+        .command('rm')
+        .description('Remove a project from an organization')
+        .option('-o, --org <name>', 'Organization name (auto-resolved from the project key if unique)')
+        .option('-P, --project <key>', 'Project key')
+        .addOption(new Option('-k, --key <key>', 'Project key (alias for --project)').hideHelp())
+        .option('-y, --yes', 'Skip confirmation prompt')
+        .action(async (opts) => {
+        const projectKey = opts.project ?? opts.key;
+        if (!projectKey)
+            throw new Error('Project key is required (-P/--project).');
+        await runProjectRemove(opts.org, projectKey, { yes: opts.yes });
+    });
+    orgs.addHelpText('after', `
 Examples:
   $ jirallm orgs list
-  $ jirallm orgs rm --org acme
-  $ jirallm orgs project rm --org acme --key PROJ
+  $ jirallm orgs rm acme
+  $ jirallm orgs rm --org acme --dry-run
+  $ jirallm orgs project rm -P PROJ
+  $ jirallm orgs project rm --org acme -P PROJ
 `);
-program
-    .command('doctor')
-    .description('Check that everything jirallm needs is installed and reachable')
-    .option('-o, --org <name>', 'Organization to use for the Jira reachability check')
-    .option('-P, --project <key>', 'Project key to use for the Jira reachability check')
-    .action(async (opts) => {
-    await runDoctor({ org: opts.org, project: opts.project });
-})
-    .addHelpText('after', '\nExample:\n  $ jirallm doctor --org acme\n');
-program
-    .command('setup')
-    .description('Install missing system dependencies (currently: ffmpeg) with cascading consent')
-    .option('--bundled', 'Install ffmpeg-static globally instead of system ffmpeg')
-    .option('-y, --yes', 'Auto-confirm package-manager install (does NOT auto-confirm Homebrew install)')
-    .action(async (opts) => {
-    await runSetup({ bundled: opts.bundled, yes: opts.yes });
-})
-    .addHelpText('after', `
+    program
+        .command('doctor')
+        .description('Check that everything jirallm needs is installed and reachable')
+        .option('-o, --org <name>', 'Organization to use for the Jira reachability check')
+        .option('-P, --project <key>', 'Project key to use for the Jira reachability check')
+        .option('--strict', 'Exit non-zero on warnings as well as failures')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (opts) => {
+        await runDoctor({ org: opts.org, project: opts.project, strict: opts.strict, json: opts.json });
+    })
+        .addHelpText('after', '\nExamples:\n  $ jirallm doctor --org acme\n  $ jirallm doctor --org acme --strict --json\n');
+    program
+        .command('setup')
+        .description('Install missing system dependencies (currently: ffmpeg) with cascading consent')
+        .option('--bundled', 'Install ffmpeg-static globally instead of system ffmpeg')
+        .option('-y, --yes', 'Auto-confirm package-manager install (does NOT auto-confirm Homebrew install)')
+        .option('--allow-brew', 'Also auto-confirm the Homebrew install step')
+        .option('--dry-run', 'Show what would be installed without running any installer')
+        .action(async (opts) => {
+        await runSetup({ bundled: opts.bundled, yes: opts.yes, allowBrew: opts.allowBrew, dryRun: opts.dryRun });
+    })
+        .addHelpText('after', `
 Examples:
   $ jirallm setup
   $ jirallm setup --yes
   $ jirallm setup --bundled
+  $ jirallm setup --yes --allow-brew
+  $ jirallm setup --dry-run
 `);
-program
-    .command('upgrade')
-    .description('Upgrade jirallm to the latest version (auto-detects npm/pnpm/yarn/Homebrew)')
-    .option('-y, --yes', 'Skip confirmation prompt')
-    .option('--check', 'Print whether an update is available without installing (exits non-zero if outdated)')
-    .action(async (opts) => {
-    try {
-        await runUpgrade(opts);
-    }
-    catch (err) {
-        console.error(err.message);
-        process.exit(1);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('upgrade')
+        .description('Upgrade jirallm to the latest version (auto-detects npm/pnpm/yarn/Homebrew)')
+        .option('-y, --yes', 'Skip confirmation prompt')
+        .option('--check', 'Print whether an update is available without installing (exits non-zero if outdated)')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (opts) => {
+        try {
+            await runUpgrade(opts);
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 Examples:
   $ jirallm upgrade
   $ jirallm upgrade --yes
   $ jirallm upgrade --check
 `);
-program
-    .command('comment <issue-key>')
-    .description('Post a (possibly multi-part) comment on a Jira issue. Markdown converted to Jira wiki by default.')
-    .option('-f, --file <path>', 'Read comment body from a file')
-    .option('-t, --text <text>', 'Inline comment text (alternative to --file / stdin)')
-    .option('-o, --org <name>', 'Organization name override')
-    .option('--max-chars <n>', 'Max chars per comment chunk (default 25000)')
-    .option('--no-wiki', 'Skip markdown→wiki conversion (post body as-is)')
-    .option('--reply-to <commentId>', 'Post as reply to an existing comment (threaded)')
-    .option('--no-thread', 'When posting multiple chunks, do not chain them as replies')
-    .option('--dry-run', 'Show what would be posted without calling Jira')
-    .action(async (issueKey, opts) => {
-    try {
-        await runComment(issueKey, {
-            file: opts.file,
-            text: opts.text,
-            org: opts.org,
-            maxChars: opts.maxChars,
-            noWiki: opts.wiki === false,
-            noThread: opts.thread === false,
-            replyTo: opts.replyTo,
-            dryRun: opts.dryRun,
-        });
-    }
-    catch (err) {
-        console.error(err.message);
-        process.exit(1);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('comment <issue-key>')
+        .description('Post a (possibly multi-part) comment on a Jira issue. Markdown converted to Jira wiki by default.')
+        .option('-f, --file <path>', 'Read comment body from a file')
+        .option('-t, --text <text>', 'Inline comment text (alternative to --file / stdin)')
+        .option('-o, --org <name>', 'Organization name override')
+        .option('--max-chars <n>', 'Max chars per comment chunk (default 25000)')
+        .option('--no-wiki', 'Skip markdown→wiki conversion (post body as-is)')
+        .option('--reply-to <commentId>', 'Post as reply to an existing comment (threaded)')
+        .option('--no-thread', 'When posting multiple chunks, do not chain them as replies')
+        .option('--dry-run', 'Show what would be posted without calling Jira')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (issueKey, opts) => {
+        try {
+            await runComment(issueKey, {
+                file: opts.file,
+                text: opts.text,
+                org: opts.org,
+                maxChars: opts.maxChars,
+                noWiki: opts.wiki === false,
+                noThread: opts.thread === false,
+                replyTo: opts.replyTo,
+                dryRun: opts.dryRun,
+                json: opts.json,
+            });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 Examples:
-  $ jirallm comment CN-2505 --file ./summary.md
-  $ jirallm comment CN-2505 -t "Quick note"
-  $ cat summary.md | jirallm comment CN-2505
-  $ jirallm comment CN-2505 --file ./summary.md --dry-run
-  $ jirallm comment CN-2505 --reply-to 26215 -t "follow-up"
+  $ jirallm comment PROJ-123 --file ./summary.md
+  $ jirallm comment PROJ-123 -t "Quick note"
+  $ cat summary.md | jirallm comment PROJ-123
+  $ jirallm comment PROJ-123 --file ./summary.md --dry-run
+  $ jirallm comment PROJ-123 --reply-to 10001 -t "follow-up"
 `);
-program
-    .command('board:issues')
-    .description('List issues in a board column. Output JSON with --json for piping into other tools.')
-    .requiredOption('-b, --board <name>', 'Board name (exact match)')
-    .requiredOption('-c, --column <name>', 'Column name (exact match)')
-    .requiredOption('-o, --org <name>', 'Organization name from config')
-    .option('-P, --project <key>', 'Project key override (defaults to the org\'s configured project)')
-    .option('-a, --assignee <accountIdOrMe>', 'Filter by assignee. Use "me" for the current user.')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (opts) => {
-    try {
-        await runBoardIssues(opts);
-    }
-    catch (err) {
-        console.error(err.message);
-        process.exit(1);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('board:issues')
+        .description('List issues in a board column. Output JSON with --json for piping into other tools.')
+        .requiredOption('-b, --board <name>', 'Board name (case-insensitive match)')
+        .option('-c, --column <name>', 'Column name (case-insensitive match); lists all columns when omitted')
+        .requiredOption('-o, --org <name>', 'Organization name from config')
+        .option('-P, --project <key>', 'Project key override (auto-selected when the org has a single project)')
+        .option('-a, --assignee <accountIdOrMe>', 'Filter by assignee. Use "me" for the current user.')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (opts) => {
+        try {
+            await runBoardIssues(opts);
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 Examples:
   $ jirallm board:issues -o MyOrg -b "My Board" -c "In Review" -a me --json
   $ jirallm board:issues -o MyOrg -b "My Board" -c "Done"
 `);
-program
-    .command('transition <issue-key>')
-    .description('Transition a Jira issue to a target status (matches transition.to.name).')
-    .option('-t, --to <status>', 'Target status name (e.g. "In Review")')
-    .option('-o, --org <name>', 'Organization name override')
-    .option('-l, --list', 'List available transitions for the issue instead of performing one')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (issueKey, opts) => {
-    try {
-        if (!opts.list && !opts.to) {
-            throw new Error('Either --to <status> or --list is required.');
+    program
+        .command('transition <issue-key>')
+        .description('Transition a Jira issue to a target status (case-insensitive match on transition to.name, then name).')
+        .option('-t, --to <status>', 'Target status name (e.g. "In Review")')
+        .option('-o, --org <name>', 'Organization name override')
+        .option('-l, --list', 'List available transitions (matched case-insensitively by to.name then name) instead of performing one')
+        .option('--dry-run', 'Resolve the transition and print it without calling Jira')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (issueKey, opts) => {
+        try {
+            if (!opts.list && !opts.to) {
+                throw new Error('Either --to <status> or --list is required.');
+            }
+            await runTransition(issueKey, { to: opts.to ?? '', org: opts.org, list: opts.list, dryRun: opts.dryRun, json: opts.json });
         }
-        await runTransition(issueKey, { to: opts.to ?? '', org: opts.org, list: opts.list, json: opts.json });
-    }
-    catch (err) {
-        console.error(err.message);
-        process.exit(1);
-    }
-})
-    .addHelpText('after', `
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 Examples:
   $ jirallm transition PROJ-123 --to "In Review"
+  $ jirallm transition PROJ-123 --to "In Review" --dry-run
   $ jirallm transition PROJ-123 --list
 `);
-program
-    .command('worklog')
-    .description('Batch log work to Jira from a JSON array (stdin or --file).')
-    .option('-f, --file <path>', 'Read JSON array from a file (default: stdin)')
-    .option('-o, --org <name>', 'Default org for entries without an org/ prefix or "org" field')
-    .option('--no-wiki', 'Skip markdown→wiki conversion of description')
-    .option('--dry-run', 'Validate and print what would be posted, without calling Jira')
-    .action(async (opts) => {
-    try {
-        await runWorklog({
-            file: opts.file,
-            org: opts.org,
-            noWiki: opts.wiki === false,
-            dryRun: opts.dryRun,
-        });
-    }
-    catch (err) {
-        console.error(err.message);
-        process.exit(1);
-    }
-})
-    .addHelpText('after', `
-JSON entry shape (any 2 of startTime/endTime/duration required):
+    program
+        .command('worklog [issue-key] [duration]')
+        .description('Log work to Jira. Quick form: `worklog PROJ-123 "1h 30m"`. Batch form: JSON array on stdin or --file.')
+        .option('-f, --file <path>', 'Read JSON array from a file (default: stdin)')
+        .option('-o, --org <name>', 'Default org for entries without an org/ prefix or "org" field')
+        .option('--no-wiki', 'Skip markdown→wiki conversion of description')
+        .option('--dry-run', 'Validate and print what would be posted, without calling Jira')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (issueKey, duration, opts) => {
+        try {
+            await runWorklog({
+                issueKey,
+                duration,
+                file: opts.file,
+                org: opts.org,
+                noWiki: opts.wiki === false,
+                dryRun: opts.dryRun,
+                json: opts.json,
+            });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
+Quick single-entry form logs against "now": \`jirallm worklog PROJ-123 "1h 30m"\`.
+For the batch form, pass a JSON array on stdin or via --file.
+
+JSON entry shape (a duration alone is accepted — startTime defaults to now; or supply any 2 of startTime/endTime/duration):
   {
     "issueKey": "PROJ-123",         // required; supports "org/PROJ-123"
     "startTime": "2026-05-23T09:00:00+02:00",
@@ -490,50 +515,82 @@ Examples:
   $ cat worklogs.json | jirallm worklog --dry-run
   $ echo '[{"issueKey":"PROJ-1","startTime":"2026-05-23T09:00:00+02:00","duration":"1h"}]' | jirallm worklog
 `);
-program
-    .command('comment:rm <issue-key> <comment-id>')
-    .description('Delete a comment from a Jira issue')
-    .option('-o, --org <name>', 'Organization name override')
-    .action(async (issueKey, commentId, opts) => {
-    try {
-        await runDeleteComment(issueKey, commentId, opts);
-    }
-    catch (err) {
-        console.error(err.message);
-        process.exit(1);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('comment:rm <issue-key> <comment-id>')
+        .description('Delete a comment from a Jira issue')
+        .option('-o, --org <name>', 'Organization name override')
+        .option('--dry-run', 'Show what would be deleted without calling Jira')
+        .option('-y, --yes', 'Skip confirmation prompt')
+        .action(async (issueKey, commentId, opts) => {
+        try {
+            await runDeleteComment(issueKey, commentId, { org: opts.org, dryRun: opts.dryRun, yes: opts.yes });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 Examples:
   $ jirallm comment:rm PROJ-123 26215
-  $ jirallm comment:rm acme/PROJ-123 26215
+  $ jirallm comment:rm acme/PROJ-123 26215 --dry-run
+  $ jirallm comment:rm PROJ-123 26215 --yes
 `);
-function exitOnError(err) {
-    console.error(err.message);
-    process.exit(1);
-}
-/** Commander collector for repeatable options (e.g. --field a=1 --field b=2). */
-function collect(value, previous = []) {
-    return [...previous, value];
-}
-program
-    .command('search <jql>')
-    .description('Search issues by JQL (single page; pass --cursor for next page).')
-    .option('-o, --org <name>', 'Organization name')
-    .option('-P, --project <key>', 'Project key override')
-    .option('--limit <n>', 'Page size (default 50)')
-    .option('--cursor <token>', 'Next page token from prior search')
-    .option('--fields <list>', 'Comma-separated Jira field IDs to include')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (jql, opts) => {
-    try {
-        await runSearch({ jql, ...opts });
+    program
+        .command('comment:ls <issue-key>')
+        .description('List comments on a Jira issue.')
+        .option('-o, --org <name>', 'Organization name override')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (issueKey, opts) => {
+        try {
+            await runCommentList(issueKey, { org: opts.org, json: opts.json });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
+Examples:
+  $ jirallm comment:ls PROJ-123
+  $ jirallm comment:ls acme/PROJ-123 --json
+`);
+    function jsonModeRequested() {
+        return process.argv.includes('--json');
     }
-    catch (err) {
-        exitOnError(err);
+    function reportError(err) {
+        const message = err.message ?? String(err);
+        if (jsonModeRequested()) {
+            console.error(JSON.stringify({ error: message }));
+            return;
+        }
+        console.error(message);
+    }
+    function exitOnError(err) {
+        reportError(err);
+        process.exit(1);
     }
-})
-    .addHelpText('after', `
+    /** Commander collector for repeatable options (e.g. --field a=1 --field b=2). */
+    function collect(value, previous = []) {
+        return [...previous, value];
+    }
+    program
+        .command('search <jql>')
+        .description('Search issues by JQL (single page; pass --cursor for next page).')
+        .option('-o, --org <name>', 'Organization name')
+        .option('--limit <n>', 'Page size (default 50)')
+        .option('--cursor <token>', 'Next page token from prior search')
+        .option('--next-page-token <token>', 'Alias for --cursor')
+        .option('--fields <list>', 'Comma-separated Jira field IDs to include')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (jql, opts) => {
+        try {
+            const { nextPageToken, ...rest } = opts;
+            await runSearch({ jql, ...rest, cursor: opts.cursor ?? nextPageToken });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 JQL must be quoted in your shell (it usually contains spaces and shell metacharacters).
 Output JSON includes "nextPageToken" — pass it back via --cursor for the next page.
 
@@ -543,48 +600,48 @@ Examples:
   $ jirallm search 'project = PROJ' -o acme --cursor eyJsYXN0SXNzdWVLZXkiOi4uLn0= --json
   $ jirallm search 'project = PROJ' -o acme --fields summary,status,assignee --json
 `);
-program
-    .command('projects')
-    .description('List projects accessible in an org.')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .option('--query <text>', 'Filter by name/key substring')
-    .option('--limit <n>', 'Page size')
-    .option('--start-at <n>', 'Pagination offset')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (opts) => {
-    try {
-        await runProjects(opts);
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('projects')
+        .description('List projects accessible in an org.')
+        .requiredOption('-o, --org <name>', 'Organization name')
+        .option('--query <text>', 'Filter by name/key substring')
+        .option('--limit <n>', 'Page size')
+        .option('--start-at <n>', 'Pagination offset')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (opts) => {
+        try {
+            await runProjects(opts);
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 Examples:
   $ jirallm projects -o acme
   $ jirallm projects -o acme --query docs --json
   $ jirallm projects -o acme --limit 50 --start-at 100 --json
 `);
-program
-    .command('boards')
-    .description('List agile boards in an org.')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .option('-P, --project <key>', 'Filter by project key')
-    .option('-t, --type <type>', 'scrum | kanban | simple')
-    .option('-n, --name <name>', 'Name substring filter')
-    .option('--limit <n>', 'Page size')
-    .option('--start-at <n>', 'Pagination offset')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (opts) => {
-    try {
-        await runBoards(opts);
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
-When --project is omitted, falls back to the org's default project.
+    program
+        .command('boards')
+        .description('List agile boards in an org.')
+        .option('-o, --org <name>', 'Organization name (auto-resolved from the -P project key when it maps to a unique org)')
+        .option('-P, --project <key>', 'Filter by project key')
+        .option('-t, --type <type>', 'scrum | kanban | simple')
+        .option('-n, --name <name>', 'Name substring filter')
+        .option('--limit <n>', 'Page size')
+        .option('--start-at <n>', 'Pagination offset')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (opts) => {
+        try {
+            await runBoards(opts);
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
+When --project is omitted and the org has a single project, that project is used automatically.
 The board id printed here is what you pass to \`jirallm sprints <id>\`.
 
 Examples:
@@ -592,87 +649,87 @@ Examples:
   $ jirallm boards -o acme -P PROJ -t scrum --json
   $ jirallm boards -o acme -n "Team Alpha" --json
 `);
-program
-    .command('sprints <board-id>')
-    .description('List sprints on a board.')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .option('-s, --state <state>', 'active | future | closed')
-    .option('--limit <n>', 'Page size')
-    .option('--start-at <n>', 'Pagination offset')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (boardId, opts) => {
-    try {
-        await runSprints({ boardId, ...opts });
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('sprints <board-id>')
+        .description('List sprints on a board.')
+        .requiredOption('-o, --org <name>', 'Organization name')
+        .option('-s, --state <state>', 'active | future | closed')
+        .option('--limit <n>', 'Page size')
+        .option('--start-at <n>', 'Pagination offset')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (boardId, opts) => {
+        try {
+            await runSprints({ boardId, ...opts });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 Get board ids from \`jirallm boards --org <name>\`.
 
 Examples:
   $ jirallm sprints 42 -o acme --state active --json
   $ jirallm sprints 42 -o acme --state closed --limit 20
 `);
-program
-    .command('issuetypes')
-    .description('List issue types (project-scoped if --project provided).')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .option('-P, --project <key>', 'Project key (defaults to org default)')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (opts) => {
-    try {
-        await runIssueTypes(opts);
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('issuetypes')
+        .description('List issue types (project-scoped if --project provided).')
+        .option('-o, --org <name>', 'Organization name (auto-resolved from the -P project key when it maps to a unique org)')
+        .option('-P, --project <key>', 'Project key (auto-selected when the org has a single project)')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (opts) => {
+        try {
+            await runIssueTypes(opts);
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 Use this before \`jirallm create\` to discover the valid --type values for a project.
 
 Examples:
   $ jirallm issuetypes -o acme --json
   $ jirallm issuetypes -o acme -P PROJ --json
 `);
-program
-    .command('components')
-    .description('List components defined on a project.')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .option('-P, --project <key>', 'Project key (defaults to org default)')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (opts) => {
-    try {
-        await runComponents(opts);
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('components')
+        .description('List components defined on a project.')
+        .option('-o, --org <name>', 'Organization name (auto-resolved from the project key if unique)')
+        .option('-P, --project <key>', 'Project key (auto-selected when the org has a single project)')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (opts) => {
+        try {
+            await runComponents(opts);
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 The "name" values are what \`jirallm create/edit --components\` expects.
 
 Examples:
   $ jirallm components -o acme -P PROJ
   $ jirallm components -o acme -P PROJ --json
 `);
-program
-    .command('fields')
-    .description('List custom fields (and select options with --type) for use with --field.')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .option('-P, --project <key>', 'Project key (defaults to org default)')
-    .option('-t, --type <issueType>', 'Show create-screen fields + allowed values for this issue type')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (opts) => {
-    try {
-        await runFields(opts);
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('fields')
+        .description('List custom fields (and select options with --type) for use with --field.')
+        .option('-o, --org <name>', 'Organization name (auto-resolved from the -P project key when it maps to a unique org)')
+        .option('-P, --project <key>', 'Project key (auto-selected when the org has a single project)')
+        .option('-t, --type <issueType>', 'Show create-screen fields + allowed values for this issue type')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (opts) => {
+        try {
+            await runFields(opts);
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 The [customfield_NNNNN] ids are what \`jirallm create/edit --field\` expects.
 Add --type Bug to see valid select options (e.g. for Severity, Environment).
 
@@ -681,40 +738,40 @@ Examples:
   $ jirallm fields -o acme -P PROJ --type Bug
   $ jirallm fields -o acme -P PROJ --type Bug --json
 `);
-program
-    .command('linktypes')
-    .description('List issue link types available in an org.')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (opts) => {
-    try {
-        await runLinkTypes(opts);
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('linktypes')
+        .description('List issue link types available in an org.')
+        .requiredOption('-o, --org <name>', 'Organization name')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (opts) => {
+        try {
+            await runLinkTypes(opts);
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 The "name" column is what \`jirallm link\` expects as <type> (e.g. "Blocks", "Relates").
 
 Examples:
   $ jirallm linktypes -o acme
   $ jirallm linktypes -o acme --json
 `);
-program
-    .command('me')
-    .description('Show the currently authenticated Jira user.')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (opts) => {
-    try {
-        await runMe(opts);
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('me')
+        .description('Show the currently authenticated Jira user.')
+        .requiredOption('-o, --org <name>', 'Organization name')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (opts) => {
+        try {
+            await runMe(opts);
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 Returns the accountId — use it as --assignee for \`create\` / \`edit\` / \`assign\`,
 or pass "me" as a shorthand in commands that resolve it (\`assign\`, \`watchers\`).
 
@@ -722,27 +779,27 @@ Examples:
   $ jirallm me -o acme
   $ jirallm me -o acme --json | jq -r .accountId
 `);
-program
-    .command('fetch <issue-key>')
-    .description('Fetch a single issue as JSON or pretty text (no file output).')
-    .option('-o, --org <name>', 'Organization name override')
-    .option('--json', 'Output JSON instead of human-readable')
-    .option('--with-comments', 'Include comments')
-    .option('--with-history', 'Include status + field-change history')
-    .option('--with-worklog', 'Include worklogs')
-    .option('--with-subtasks', 'Include subtask metadata')
-    .option('--with-links', 'Include issue links')
-    .option('--with-attachments', 'List attachment metadata (does not download)')
-    .option('--full', 'Include everything (comments, history, worklog, subtasks, links, attachments)')
-    .action(async (issueKey, opts) => {
-    try {
-        await runFetch({ issueKey, ...opts });
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('fetch <issue-key>')
+        .description('Fetch a single issue as JSON or pretty text (no file output).')
+        .option('-o, --org <name>', 'Organization name override')
+        .option('--json', 'Output JSON instead of human-readable')
+        .option('--with-comments', 'Include comments')
+        .option('--with-history', 'Include status + field-change history')
+        .option('--with-worklog', 'Include worklogs')
+        .option('--with-subtasks', 'Include subtask metadata')
+        .option('--with-links', 'Include issue links')
+        .option('--with-attachments', 'List attachment metadata (does not download)')
+        .option('--full', 'Include everything (comments, history, worklog, subtasks, links, attachments)')
+        .action(async (issueKey, opts) => {
+        try {
+            await runFetch({ issueKey, ...opts });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 For the full export bundle (attachments, video frames, on-disk folder),
 use the default \`jirallm <key>\` command instead.
 
@@ -753,47 +810,47 @@ Examples:
   $ jirallm fetch PROJ-123 --full
   $ jirallm fetch PROJ-123 --json | jq .status
 `);
-program
-    .command('create')
-    .description('Create a new Jira issue.')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .option('-P, --project <key>', 'Project key (defaults to org default)')
-    .requiredOption('-t, --type <type>', 'Issue type name (e.g. Task, Bug, Story)')
-    .requiredOption('-s, --summary <text>', 'Issue summary')
-    .option('-d, --description <text>', 'Description (markdown)')
-    .option('--description-file <path>', 'Read description (markdown) from a file')
-    .option('-a, --assignee <accountId>', 'Assignee accountId')
-    .option('-l, --labels <list>', 'Comma-separated labels')
-    .option('--priority <name>', 'Priority name (e.g. High)')
-    .option('--parent <key>', 'Parent issue key (for subtasks / epic children)')
-    .option('--components <names>', 'Comma-separated component names')
-    .option('-F, --field <pair>', 'Set a custom field: friendlyName=value or customfield_NNNNN[:type]=value (repeatable)', collect)
-    .option('--dry-run', 'Show what would be created without calling Jira')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (opts) => {
-    try {
-        await runCreate({
-            org: opts.org,
-            projectKey: opts.project,
-            type: opts.type,
-            summary: opts.summary,
-            description: opts.description,
-            descriptionFile: opts.descriptionFile,
-            assignee: opts.assignee,
-            labels: opts.labels,
-            priority: opts.priority,
-            parent: opts.parent,
-            components: opts.components,
-            field: opts.field,
-            dryRun: opts.dryRun,
-            json: opts.json,
-        });
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('create')
+        .description('Create a new Jira issue.')
+        .option('-o, --org <name>', 'Organization name (auto-resolved from the project key if unique)')
+        .option('-P, --project <key>', 'Project key (auto-selected when the org has a single project)')
+        .requiredOption('-t, --type <type>', 'Issue type name (e.g. Task, Bug, Story)')
+        .requiredOption('-s, --summary <text>', 'Issue summary')
+        .option('-d, --description <text>', 'Description (markdown)')
+        .option('--description-file <path>', 'Read description (markdown) from a file')
+        .option('-a, --assignee <user>', 'Assignee: an accountId, email, display name, or "me"')
+        .option('-l, --labels <list>', 'Comma-separated labels')
+        .option('--priority <name>', 'Priority name (e.g. High)')
+        .option('--parent <key>', 'Parent issue key (for subtasks / epic children)')
+        .option('--components <names>', 'Comma-separated component names')
+        .option('-F, --field <pair>', 'Set a custom field: friendlyName=value or customfield_NNNNN[:type]=value (repeatable)', collect)
+        .option('--dry-run', 'Show what would be created without calling Jira')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (opts) => {
+        try {
+            await runCreate({
+                org: opts.org,
+                projectKey: opts.project,
+                type: opts.type,
+                summary: opts.summary,
+                description: opts.description,
+                descriptionFile: opts.descriptionFile,
+                assignee: opts.assignee,
+                labels: opts.labels,
+                priority: opts.priority,
+                parent: opts.parent,
+                components: opts.components,
+                field: opts.field,
+                dryRun: opts.dryRun,
+                json: opts.json,
+            });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 Run \`jirallm issuetypes -o <org>\` to discover valid --type values.
 Run \`jirallm components -o <org> -P <project>\` to discover valid --components names.
 Run \`jirallm fields -o <org> -P <project> --type Bug\` to discover custom field ids and select options.
@@ -813,30 +870,30 @@ Examples:
   $ jirallm create -o acme -t Bug -s "Crash" --components Web,API --field severity=High --field environment=PROD
   $ jirallm create -o acme -t Bug -s "test" --dry-run --json
 `);
-program
-    .command('edit <issue-key>')
-    .description('Edit fields on an existing Jira issue.')
-    .option('-o, --org <name>', 'Organization name override')
-    .option('-s, --summary <text>', 'New summary')
-    .option('-d, --description <text>', 'New description (markdown)')
-    .option('--description-file <path>', 'Read description (markdown) from a file')
-    .option('-a, --assignee <accountId>', 'Assignee accountId')
-    .option('--unassign', 'Unassign the issue (clears assignee)')
-    .option('-l, --labels <list>', 'Comma-separated labels (replaces existing)')
-    .option('--priority <name>', 'Priority name')
-    .option('--components <names>', 'Comma-separated component names (replaces existing)')
-    .option('-F, --field <pair>', 'Set a custom field: friendlyName=value or customfield_NNNNN[:type]=value (repeatable)', collect)
-    .option('--dry-run', 'Show what would change without calling Jira')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (issueKey, opts) => {
-    try {
-        await runEdit({ issueKey, ...opts });
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('edit <issue-key>')
+        .description('Edit fields on an existing Jira issue.')
+        .option('-o, --org <name>', 'Organization name override')
+        .option('-s, --summary <text>', 'New summary')
+        .option('-d, --description <text>', 'New description (markdown)')
+        .option('--description-file <path>', 'Read description (markdown) from a file')
+        .option('-a, --assignee <user>', 'Assignee: an accountId, email, display name, or "me"')
+        .option('--unassign', 'Unassign the issue (clears assignee)')
+        .option('-l, --labels <list>', 'Comma-separated labels (replaces existing)')
+        .option('--priority <name>', 'Priority name')
+        .option('--components <names>', 'Comma-separated component names (replaces existing)')
+        .option('-F, --field <pair>', 'Set a custom field: friendlyName=value or customfield_NNNNN[:type]=value (repeatable)', collect)
+        .option('--dry-run', 'Show what would change without calling Jira')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (issueKey, opts) => {
+        try {
+            await runEdit({ issueKey, ...opts });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 --labels and --components REPLACE the existing sets; there is no add/remove syntax here.
 --unassign and --assignee are mutually exclusive (use one).
 Custom fields work like \`create\`: --field friendlyName=value or --field customfield_NNNNN[:type]=value.
@@ -849,23 +906,23 @@ Examples:
   $ jirallm edit PROJ-123 --assignee 5ac1234567890abcdef
   $ jirallm edit PROJ-123 --unassign --dry-run --json
 `);
-program
-    .command('assign <issue-key> <assignee>')
-    .description('Assign an issue. Use "me" for the current user, "none" to unassign.')
-    .option('-o, --org <name>', 'Organization name override')
-    .option('--dry-run', 'Show what would change without calling Jira')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (issueKey, assignee, opts) => {
-    try {
-        await runAssign({ issueKey, assignee, ...opts });
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('assign <issue-key> <assignee>')
+        .description('Assign an issue. Use "me" for the current user, "none" to unassign.')
+        .option('-o, --org <name>', 'Organization name override')
+        .option('--dry-run', 'Show what would change without calling Jira')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (issueKey, assignee, opts) => {
+        try {
+            await runAssign({ issueKey, assignee, ...opts });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 <assignee> shortcuts: "me" (current user) or "none"/"-" (unassign).
-Any other value is treated as a Jira accountId.
+Any other value is resolved as an email, display name, or accountId.
 
 Examples:
   $ jirallm assign PROJ-123 me
@@ -873,22 +930,22 @@ Examples:
   $ jirallm assign PROJ-123 5ac1234567890abcdef
   $ jirallm assign PROJ-123 me --dry-run --json
 `);
-program
-    .command('link <inward-key> <type> <outward-key>')
-    .description('Create an issue link (e.g. `link FOO-1 "blocks" FOO-2`).')
-    .option('-c, --comment <text>', 'Add a comment when linking')
-    .option('-o, --org <name>', 'Organization name override')
-    .option('--dry-run', 'Show what would be created without calling Jira')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (inwardKey, type, outwardKey, opts) => {
-    try {
-        await runLink({ inwardKey, type, outwardKey, ...opts });
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('link <inward-key> <type> <outward-key>')
+        .description('Create an issue link (e.g. `link FOO-1 "blocks" FOO-2`).')
+        .option('-c, --comment <text>', 'Add a comment when linking')
+        .option('-o, --org <name>', 'Organization name override')
+        .option('--dry-run', 'Show what would be created without calling Jira')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (inwardKey, type, outwardKey, opts) => {
+        try {
+            await runLink({ inwardKey, type, outwardKey, ...opts });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 <type> is the link-type NAME (e.g. "Blocks", "Relates", "Duplicate"), not the inward/outward label.
 Discover the available types with: \`jirallm linktypes -o <org>\`.
 --comment is markdown; it gets converted to Jira wiki.
@@ -898,44 +955,50 @@ Examples:
   $ jirallm link PROJ-1 "Relates" PROJ-2 --comment "see also **infra rewrite**"
   $ jirallm link PROJ-1 "Blocks" PROJ-2 --dry-run --json
 `);
-program
-    .command('link:rm <link-id>')
-    .description('Remove an issue link by ID.')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .option('--dry-run', 'Show what would be deleted without calling Jira')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (linkId, opts) => {
-    try {
-        await runLinkRemove({ linkId, ...opts });
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('link:rm [issue-key] [link-id]')
+        .description('Remove an issue link by ID, or by issue key + --to target.')
+        .option('-o, --org <name>', 'Organization name (auto-resolved from the issue/project key if unique)')
+        .option('--to <key>', 'Remove the link between <issue-key> and this issue key')
+        .option('--dry-run', 'Show what would be deleted without calling Jira')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (issueKey, linkId, opts) => {
+        try {
+            const target = issueKey ?? linkId;
+            if (!target)
+                throw new Error('Provide a link id, or an issue key with --to.');
+            await runLinkRemove({ linkId: target, to: opts.to, org: opts.org, dryRun: opts.dryRun, json: opts.json });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 Get link IDs from the issueLinks array in \`jirallm fetch <key> --json\`.
+Alternatively, drop the link between two issues with --to.
 
 Examples:
   $ jirallm link:rm 10042 -o acme
   $ jirallm link:rm 10042 -o acme --dry-run --json
+  $ jirallm link:rm PROJ-1 --to PROJ-2
 `);
-program
-    .command('attach <issue-key> [files...]')
-    .description('Upload one or more file attachments to an issue. At least one file is required.')
-    .option('-o, --org <name>', 'Organization name override')
-    .option('--dry-run', 'Show what would be uploaded without calling Jira')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (issueKey, files, opts) => {
-    try {
-        if (!files || files.length === 0)
-            throw new Error('At least one file is required.');
-        await runAttach({ issueKey, files, ...opts });
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('attach <issue-key> [files...]')
+        .description('Upload one or more file attachments to an issue. At least one file is required.')
+        .option('-o, --org <name>', 'Organization name override')
+        .option('--dry-run', 'Show what would be uploaded without calling Jira')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (issueKey, files, opts) => {
+        try {
+            if (!files || files.length === 0)
+                throw new Error('At least one file is required.');
+            await runAttach({ issueKey, files, ...opts });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 Files are uploaded sequentially; --json returns the aggregated attachments array.
 The id from the response is what \`jirallm attach:rm\` takes.
 
@@ -944,44 +1007,47 @@ Examples:
   $ jirallm attach PROJ-123 ./a.png ./b.png ./recording.mp4 --json
   $ jirallm attach PROJ-123 ./screenshot.png --dry-run
 `);
-program
-    .command('attach:rm <attachment-id>')
-    .description('Delete an attachment by ID.')
-    .requiredOption('-o, --org <name>', 'Organization name')
-    .option('--dry-run', 'Show what would be deleted without calling Jira')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (attachmentId, opts) => {
-    try {
-        await runAttachRemove({ attachmentId, ...opts });
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
-Get attachment IDs from the attachments array in \`jirallm fetch <key> --json\`.
+    program
+        .command('attach:rm [target] [filename]')
+        .description('Delete an attachment by ID, or by issue key + filename.')
+        .option('-o, --org <name>', 'Organization name (auto-resolved from the issue/project key if unique)')
+        .option('--dry-run', 'Show what would be deleted without calling Jira')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (target, filename, opts) => {
+        try {
+            await runAttachRemove({ target, filename, org: opts.org, dryRun: opts.dryRun, json: opts.json });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
+Delete by attachment id (get ids from the attachments array in \`jirallm fetch <key> --json\`);
+a bare numeric id needs -o (or an org/KEY) since it cannot infer the org on its own.
+Alternatively, delete by issue key + filename — the org is inferred from the key prefix.
 
 Examples:
   $ jirallm attach:rm 99021 -o acme
   $ jirallm attach:rm 99021 -o acme --dry-run --json
+  $ jirallm attach:rm PROJ-123 screenshot.png
 `);
-program
-    .command('watchers <issue-key>')
-    .description('List, add, or remove watchers on an issue.')
-    .option('-o, --org <name>', 'Organization name override')
-    .option('--add <accountId>', 'Add watcher by accountId (or "me")')
-    .option('--rm <accountId>', 'Remove watcher by accountId (or "me")')
-    .option('--dry-run', 'Show what would change without calling Jira')
-    .option('--json', 'Output JSON instead of human-readable')
-    .action(async (issueKey, opts) => {
-    try {
-        await runWatchers({ issueKey, ...opts });
-    }
-    catch (err) {
-        exitOnError(err);
-    }
-})
-    .addHelpText('after', `
+    program
+        .command('watchers <issue-key>')
+        .description('List, add, or remove watchers on an issue.')
+        .option('-o, --org <name>', 'Organization name override')
+        .option('--add <user>', 'Add watcher: an accountId, email, display name, or "me"')
+        .option('--rm <user>', 'Remove watcher: an accountId, email, display name, or "me"')
+        .option('--dry-run', 'Show what would change without calling Jira')
+        .option('--json', 'Output JSON instead of human-readable')
+        .action(async (issueKey, opts) => {
+        try {
+            await runWatchers({ issueKey, ...opts });
+        }
+        catch (err) {
+            exitOnError(err);
+        }
+    })
+        .addHelpText('after', `
 With no --add/--rm, just lists current watchers.
 You can pass both --add and --rm in one call; both run before the final listing.
 Pass "me" to add/remove yourself (resolved via \`/myself\`).
@@ -992,8 +1058,19 @@ Examples:
   $ jirallm watchers PROJ-123 --rm 5ac1234567890abcdef
   $ jirallm watchers PROJ-123 --add me --rm 5acOldUser --json
 `);
-program.parseAsync(process.argv).catch((error) => {
-    console.error('Unexpected error:', error);
-    process.exit(1);
-});
+    return program;
+}
+const isDirectRun = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+    buildProgram()
+        .parseAsync(process.argv)
+        .catch((error) => {
+        if (process.argv.includes('--json')) {
+            console.error(JSON.stringify({ error: error.message ?? String(error) }));
+            process.exit(1);
+        }
+        console.error('Unexpected error:', error);
+        process.exit(1);
+    });
+}
 //# sourceMappingURL=index.js.map