@enrichlayer/el-linear 1.19.0 → 1.21.0

package/README.md

@@ -447,6 +447,24 @@ el-linear <command> --help       # detailed help for one command
 All `list` subcommands support `-l, --limit <n>`. All commands accept the
 top-level filters: `--format <json|summary>`, `--raw`, `--jq <expr>`, `--fields <list>`.
 
+### Open by default — `issues list` and `issues search` skip terminal states
+
+`el-linear issues list` and `el-linear issues search` **exclude issues in
+terminal workflow states (`Done` / `Canceled`) by default** so triage and
+survey runs return the open set without piping through `grep`. The implicit
+filter is surfaced in `_warnings` on every invocation, so scripts notice it
+deterministically rather than silently. Three ways to opt back in:
+
+```bash
+el-linear issues list --include-closed              # everything, including Done/Canceled
+el-linear issues search "auth" --status "Done"      # explicit --status wins
+el-linear issues list --status "Todo,In Progress"   # any explicit status disables the implicit filter
+```
+
+`--include-closed` and explicit `--status` both bypass the implicit filter
+(explicit choice always wins). The change is per-command and only affects
+list-shaped reads — single-issue `issues read DEV-123` is unaffected.
+
 ## Output formats
 
 Every command accepts `--format <kind>` at the root:
@@ -535,6 +553,76 @@ el-linear read ADM-652 --field "Out of scope"
 Single-issue only — pair it with `--jq` on full JSON for batch
 extraction across many issues.
 
+### Render an issue's tree: `issues tree`
+
+`issues tree <ID>` walks the parent → children graph for an issue in a
+single GraphQL round-trip and returns either a nested JSON envelope
+(default) or an ASCII tree (`--format summary`).
+
+```bash
+el-linear issues tree DEV-100 --format summary
+# DEV-100 Migrate auth middleware
+# ├── DEV-101 Write design doc
+# │   ├── DEV-104 Survey existing auth flows [Done]
+# │   └── DEV-105 Draft RFC
+# ├── DEV-102 Build new session store (@Alice)
+# └── DEV-103 Cutover plan
+```
+
+Depth defaults to **3** (max 5 — Linear has no native depth-N recursion,
+so each level adds a `children { nodes { ... } }` block to the generated
+query). Terminal-state branches (`Done` / `Canceled`) are **kept** by
+default because the tree's value is *structural*; pass
+`--no-include-closed` to prune them.
+
+### Extract several sections in one call: `--sections`
+
+When you want multiple sections (e.g. `Done when`, `Out of scope`, and
+`Steps`), don't issue N separate `--field` calls — pass a comma-separated
+list to `--sections` instead:
+
+```bash
+el-linear issues read DEV-123 --sections "Done when,Out of scope"
+# {
+#   "identifier": "DEV-123",
+#   "sections": {
+#     "Done when": "...",
+#     "Out of scope": "..."
+#   }
+# }
+```
+
+Returns a JSON envelope `{ identifier, sections: { name → text|null } }`.
+Missing sections map to `null` and surface in `_warnings` so scripts can
+detect them deterministically. Single-issue only, mutually exclusive
+with `--field`. (Named `--sections` rather than the seemingly-obvious
+`--fields` because `--fields` is already taken at the program level for
+output-key filtering — `el-linear` is the namespace owner.)
+
+### Opt-in includes: `--with`
+
+`issues read --with <names>` adds extra blocks of related data to the
+JSON envelope. Comma-separated; unknown values are rejected with the
+candidate list.
+
+Currently supported:
+
+| Include | What it adds |
+|---------|--------------|
+| `relations` | A top-level `relations` array (outgoing + incoming cross-issue links), built from the same data as `issues related`. |
+
+```bash
+# Issue + its sidebar relations in one call:
+el-linear issues read DEV-123 --with relations
+
+# Across multiple issues — relations fetched per issue in parallel:
+el-linear read DEV-1 DEV-2 --with relations | jq '.data[].relations'
+```
+
+`--with` is JSON-only — it composes with `--jq` / `--fields` / `--raw`,
+and is mutually exclusive with `--field` (which prints raw section text,
+no envelope).
+
 ## Wrapping Linear references in arbitrary text
 
 `el-linear refs wrap` takes plain text on stdin (or via `--file`) and rewrites

package/claude-skills/linear-operations/SKILL.md

@@ -123,7 +123,11 @@ and outreach tracked in one place.
 **Search before creating. No exceptions.**
 
 ```bash
-el-linear issues search "keywords from proposed title" 2>&1
+# --include-closed is required so previously-completed duplicates surface.
+# `issues search` defaults to open states (DEV-4478); the duplicate check
+# intentionally widens to Done/Canceled because a closed-out duplicate is
+# still a duplicate.
+el-linear issues search "keywords from proposed title" --include-closed 2>&1
 ```
 
 1. Extract 2–3 key terms from the proposed title (skip generic words).
@@ -269,6 +273,7 @@ Run `el-linear usage` for the full command reference. Non-obvious rules:
 - **Subcommand aliases** — `read`/`view`/`get`/`show`, `update`/`edit`/`set`.
 - **`--jq` for GraphQL filtering** — never pipe through `jq` directly (zsh escaping breaks `!=`).
 - **`--raw` flag** strips the `{ data, meta }` wrapper — emits just the array.
+- **Body/description from a file** — `issues create`/`update` take `--description-file <path>`; `comments create`/`update` take `--body-file <path>`. Prefer the file form for any body with backticks, fenced code, or markdown tables — it sidesteps shell-quoting traps (the same reason `el-git mr comment --body-file` exists). `--body` and `--body-file` are **mutually exclusive** (passing both errors); file-sourced bodies get the same auto-link / auto-mention treatment as inline `--body`.
 
 ### Output format
 

package/dist/commands/comments.js

@@ -18,6 +18,12 @@ import { getWorkspaceUrlKey } from "../utils/workspace-url.js";
 const BODY_DATA_ERROR_RE = /prosemirror|bodydata|invalid.*body/i;
 const ISSUE_IDENTIFIER_REGEX = /^[A-Z][A-Z0-9]*-\d+$/;
 function readBody(options) {
+    // --body and --body-file are two sources for the same field; accepting both
+    // would silently drop one. Reject up front (DEV-4450) — the same mutual-
+    // exclusivity contract resolveDescription() enforces for --template.
+    if (options.body && options.bodyFile) {
+        throw new Error("--body and --body-file are mutually exclusive — pass one or the other");
+    }
     if (options.bodyFile) {
         return readFileSync(options.bodyFile, "utf-8");
     }

package/dist/commands/issues/tree.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `el-linear issues tree <ID>` (DEV-4480).
+ *
+ * Renders the parent-and-children tree of an issue to depth N (default 3,
+ * max 5 — see `MAX_TREE_DEPTH`). One GraphQL round-trip per invocation;
+ * the query string is generated by `buildIssueTreeQuery(depth)` at call
+ * time because the children connection has no `@include`-style depth
+ * directive.
+ *
+ * Two output modes:
+ *   - **JSON** (default): nested `IssueTreeNode` shape.
+ *   - **Summary**: ASCII tree via `formatTree`.
+ *
+ * Closed-issue filtering: `--include-closed` is on by default for `tree`
+ * because the tree's value is *structural* — knowing that a child was
+ * canceled is part of the picture. Pass `--no-include-closed` to prune
+ * terminal-state branches client-side after the fetch (Linear's children
+ * connection has no top-level state filter).
+ */
+import type { Command, OptionValues } from "commander";
+export declare function setupTreeCommand(issues: Command): void;
+export declare function handleTreeCommand(issueId: string, options: OptionValues, command: Command): Promise<void>;

package/dist/commands/issues/tree.js

@@ -0,0 +1,102 @@
+/**
+ * `el-linear issues tree <ID>` (DEV-4480).
+ *
+ * Renders the parent-and-children tree of an issue to depth N (default 3,
+ * max 5 — see `MAX_TREE_DEPTH`). One GraphQL round-trip per invocation;
+ * the query string is generated by `buildIssueTreeQuery(depth)` at call
+ * time because the children connection has no `@include`-style depth
+ * directive.
+ *
+ * Two output modes:
+ *   - **JSON** (default): nested `IssueTreeNode` shape.
+ *   - **Summary**: ASCII tree via `formatTree`.
+ *
+ * Closed-issue filtering: `--include-closed` is on by default for `tree`
+ * because the tree's value is *structural* — knowing that a child was
+ * canceled is part of the picture. Pass `--no-include-closed` to prune
+ * terminal-state branches client-side after the fetch (Linear's children
+ * connection has no top-level state filter).
+ */
+import { buildIssueTreeQuery, DEFAULT_TREE_DEPTH, MAX_TREE_DEPTH, } from "../../queries/issue-tree.js";
+import { formatTree } from "../../utils/format-tree.js";
+import { createIssuesService } from "../../utils/issues-service-bootstrap.js";
+import { handleAsyncCommand, outputSuccess } from "../../utils/output.js";
+import { getRootOpts } from "../../utils/root-opts.js";
+export function setupTreeCommand(issues) {
+    issues
+        .command("tree <issueId>")
+        .description("Render the parent-and-children tree of an issue (DEV-4480). " +
+        "One GraphQL call. Depth defaults to 3 (max 5).")
+        .option("--depth <n>", `Tree depth, integer in [1, ${MAX_TREE_DEPTH}] (default ${DEFAULT_TREE_DEPTH})`, String(DEFAULT_TREE_DEPTH))
+        .option("--no-include-closed", "Prune branches whose state is Done or Canceled. By default tree " +
+        "renders all states because the tree's value is structural.")
+        .addHelpText("after", "\nExamples:" +
+        "\n  el-linear issues tree DEV-100" +
+        "\n  el-linear issues tree DEV-100 --depth 5 --format summary" +
+        "\n  el-linear issues tree DEV-100 --no-include-closed")
+        .action(handleAsyncCommand(handleTreeCommand));
+}
+export async function handleTreeCommand(issueId, options, command) {
+    const rootOpts = getRootOpts(command);
+    const { graphQLService, linearService } = await createIssuesService(rootOpts);
+    const treeOptions = options;
+    const depth = parseDepth(treeOptions.depth);
+    // commander turns `--no-include-closed` into `includeClosed: false`; the
+    // default is true (see option declaration).
+    const includeClosed = treeOptions.includeClosed !== false;
+    const resolvedId = await linearService.resolveIssueId(issueId);
+    const result = await graphQLService.rawRequest(buildIssueTreeQuery(depth), { id: resolvedId });
+    if (!result.issue) {
+        throw new Error(`Issue "${issueId}" not found`);
+    }
+    const filtered = includeClosed
+        ? result.issue
+        : pruneTerminalStates(result.issue);
+    // `--format` is a *root-program* option (see main.ts), so commander
+    // surfaces it via `command.parent.opts()` — NOT via the subcommand
+    // action's local `options` parameter. Reading from `rootOpts` mirrors
+    // the precedent in `read-shortcut.ts`'s `--field` handling.
+    // (DEV-4480 cycle-1 blocker.)
+    if (rootOpts.format === "summary") {
+        process.stdout.write(`${formatTree(filtered)}\n`);
+        return;
+    }
+    outputSuccess(filtered);
+}
+function parseDepth(raw) {
+    if (raw === undefined) {
+        return DEFAULT_TREE_DEPTH;
+    }
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isInteger(n) || n < 1 || n > MAX_TREE_DEPTH) {
+        throw new Error(`--depth must be an integer in [1, ${MAX_TREE_DEPTH}]; got "${raw}".`);
+    }
+    return n;
+}
+/**
+ * Walk the tree depth-first and drop any node whose `state.type` is
+ * `completed` or `canceled`. Pure function — does not mutate the input.
+ * A pruned child takes its entire subtree with it (consistent with how
+ * `issues list --no-include-closed` excludes closed work entirely).
+ *
+ * Assumes Linear's parent → children graph stays single-parent (a tree,
+ * not a DAG). If Linear ever ships multi-parent issues, this recursion
+ * would re-emit nodes reachable via multiple paths — at that point add
+ * a `Set<string>` of seen `id`s to the walk. Today the assumption is
+ * safe. Bounded recursion: `MAX_TREE_DEPTH=5` caps the call stack at
+ * ≤6 frames (root + 5 children levels). (Cycle-1 nit.)
+ */
+function pruneTerminalStates(root) {
+    const kids = root.children?.nodes ?? [];
+    const surviving = kids
+        .filter((c) => !isTerminalState(c))
+        .map((c) => pruneTerminalStates(c));
+    return {
+        ...root,
+        children: { nodes: surviving },
+    };
+}
+function isTerminalState(node) {
+    const t = node.state?.type;
+    return t === "completed" || t === "canceled";
+}

package/dist/commands/issues.js

@@ -21,6 +21,7 @@ import { currentGitBranch, extractIssueIdentifierFromBranch, getBranchLinearIssu
 import { maybeAutoLink, prepareAutoLinkedDescription, readDescriptionFile, resolveDescription, } from "./issues/description.js";
 import { handleLinkReferencesIssue } from "./issues/link-references.js";
 import { buildIncomingRelationEntries, buildOutgoingRelationEntries, createRelations, } from "./issues/relations.js";
+import { setupTreeCommand } from "./issues/tree.js";
 import { readIssues } from "./read-shortcut.js";
 const IMAGE_EXTENSIONS = new Set([
     ".png",
@@ -160,7 +161,12 @@ async function handleListIssues(options, command) {
     }
     const rootOpts = getRootOpts(command);
     const { issuesService } = await createIssuesService(rootOpts);
-    const hasFilters = options.team ||
+    const explicitStatus = options.status ? splitList(options.status) : undefined;
+    // DEV-4478: default-exclude terminal states (Done/Canceled) unless the
+    // user passes --include-closed OR explicit --status. Explicit status
+    // wins because the user already named the workflow states they want.
+    const excludeTerminalStates = !options.includeClosed && explicitStatus === undefined;
+    const hasOtherFilters = options.team ||
         options.labels ||
         options.status ||
         options.assignee ||
@@ -169,7 +175,14 @@ async function handleListIssues(options, command) {
         options.project === false ||
         options.priority;
     const limit = parsePositiveInt(options.limit, "--limit");
-    if (hasFilters) {
+    // Route through searchIssues whenever the CLI needs to control the GraphQL
+    // state filter: any explicit filter, the default `excludeTerminalStates`,
+    // OR an explicit `--include-closed`. The last case is load-bearing —
+    // getIssues' query hard-codes `state: { type: { neq: "completed" } }`, so
+    // falling through to it on `--include-closed --no-other-filters` would
+    // silently drop Done issues, the exact opposite of the flag's intent.
+    // (DEV-4478 cycle-1.)
+    if (hasOtherFilters || excludeTerminalStates || options.includeClosed) {
         const searchArgs = {
             teamId: options.team ? resolveTeam(options.team) : undefined,
             assigneeId: options.assignee
@@ -180,7 +193,8 @@ async function handleListIssues(options, command) {
                 : undefined,
             project: resolveProjectFlag(options.project),
             labelNames: options.labels ? splitList(options.labels) : undefined,
-            status: options.status ? splitList(options.status) : undefined,
+            status: explicitStatus,
+            excludeTerminalStates,
             priority: options.priority
                 ? parsePriorityFilter(options.priority)
                 : undefined,
@@ -188,6 +202,9 @@ async function handleListIssues(options, command) {
             limit,
         };
         const result = sortIssues(await issuesService.searchIssues(searchArgs), options.sort);
+        if (excludeTerminalStates) {
+            outputWarning("excluded terminal states (Done / Canceled) by default; pass --include-closed to include them");
+        }
         warnIfTruncated(result.length, limit);
         outputIssues(result, options.format, options.fields, {
             team: options.team,
@@ -206,6 +223,11 @@ async function handleSearchIssues(query, options, command) {
     const rootOpts = getRootOpts(command);
     const { issuesService } = await createIssuesService(rootOpts);
     const limit = parsePositiveInt(options.limit, "--limit");
+    const explicitStatus = options.status ? splitList(options.status) : undefined;
+    // DEV-4478: default-exclude terminal states (Done/Canceled) unless the
+    // user passes --include-closed OR explicit --status. Explicit status
+    // wins because the user already named the workflow states they want.
+    const excludeTerminalStates = !options.includeClosed && explicitStatus === undefined;
     const searchArgs = {
         query,
         teamId: options.team ? resolveTeam(options.team) : undefined,
@@ -216,7 +238,8 @@ async function handleSearchIssues(query, options, command) {
             ? resolveMember(options.delegate)
             : undefined,
         project: resolveProjectFlag(options.project),
-        status: options.status ? splitList(options.status) : undefined,
+        status: explicitStatus,
+        excludeTerminalStates,
         labelNames: options.labels ? splitList(options.labels) : undefined,
         priority: options.priority
             ? parsePriorityFilter(options.priority)
@@ -224,6 +247,9 @@ async function handleSearchIssues(query, options, command) {
         limit,
     };
     const result = sortIssues(await issuesService.searchIssues(searchArgs), options.sort);
+    if (excludeTerminalStates) {
+        outputWarning("excluded terminal states (Done / Canceled) by default; pass --include-closed to include them");
+    }
     warnIfTruncated(result.length, limit);
     outputIssues(result, options.format, options.fields, { query });
 }
@@ -869,6 +895,10 @@ export function setupIssuesCommands(program) {
         .alias("issue")
         .description("Issue operations");
     issues.action(() => issues.help());
+    // DEV-4480: `issues tree <ID>` lives in its own file because the
+    // recursive query builder + ASCII formatter belong together and are
+    // substantial enough to warrant the split.
+    setupTreeCommand(issues);
     issues
         .command("list")
         .description("List issues.")
@@ -881,6 +911,7 @@ export function setupIssuesCommands(program) {
         .option("--labels <labels>", "filter by labels (comma-separated names)")
         .option("--label <labels>", "alias for --labels")
         .option("--status <status>", "filter by status (comma-separated, e.g. Todo,Backlog)")
+        .option("--include-closed", "include issues in terminal states (Done / Canceled). Default is to exclude them; pass this flag to see everything. Ignored when --status is set (explicit choice wins).")
         .option("--priority <priority>", "filter by priority (comma-separated: urgent,high,medium,low,none or 0-4)")
         .option("--sort <field>", "sort results (priority, status, created, updated)")
         .option("--format <format>", "output format (json, summary, table, md, csv)", "json")
@@ -895,6 +926,7 @@ export function setupIssuesCommands(program) {
         .option("--project <project>", "filter by project name or ID")
         .option("--no-project", "filter issues with no project assigned")
         .option("--status <status>", "filter by status (comma-separated)")
+        .option("--include-closed", "include issues in terminal states (Done / Canceled). Default is to exclude them; pass this flag to see everything. Ignored when --status is set (explicit choice wins).")
         .option("--labels <labels>", "filter by labels (comma-separated names)")
         .option("--label <labels>", "alias for --labels")
         .option("--priority <priority>", "filter by priority (comma-separated: urgent,high,medium,low,none or 0-4)")
@@ -965,7 +997,13 @@ export function setupIssuesCommands(program) {
         .option("--field <name>", 'Extract a single named section from the issue description (e.g. "Done when"). ' +
         "Matches H2/H3 headers and bold pseudo-headers case-insensitively. " +
         "Outputs the section text only — no JSON envelope. Single-issue only.")
-        .addHelpText("after", '\nBoth UUID and identifiers like ABC-123 are supported.\nMultiple IDs: el-linear issue get DEV-123 DEV-456 DEV-789\nExtract a section: el-linear issue read DEV-123 --field "Done when"')
+        .option("--sections <names>", 'Extract multiple named description sections in one call (comma-separated, e.g. "Done when,Out of scope"). ' +
+        "Single-issue only. Returns a JSON envelope { identifier, sections: { name -> text|null } }; missing sections appear as null + a _warnings entry. " +
+        "Sibling of --field (singular). Named --sections rather than --fields because the program already has a global --fields for output-key filtering.")
+        .option("--with <names>", "Comma-separated opt-in includes. Each value fetches an extra " +
+        'block of data and adds it to the JSON envelope. Currently supported: "relations" ' +
+        "(adds an array of cross-issue relations under a top-level `relations` key).")
+        .addHelpText("after", '\nBoth UUID and identifiers like ABC-123 are supported.\nMultiple IDs: el-linear issue get DEV-123 DEV-456 DEV-789\nExtract a section: el-linear issue read DEV-123 --field "Done when"\nMulti-section: el-linear issue read DEV-123 --sections "Done when,Out of scope"\nWith relations: el-linear issue read DEV-123 --with relations')
         .action(handleAsyncCommand(readIssues));
     issues
         .command("update <issueId>")

package/dist/commands/read-shortcut.js

@@ -1,9 +1,12 @@
+import { GET_ISSUE_RELATIONS_QUERY } from "../queries/issues.js";
 import { downloadLinearUploads } from "../utils/download-uploads.js";
-import { extractField } from "../utils/extract-field.js";
+import { extractField, extractFields } from "../utils/extract-field.js";
 import { createFileService } from "../utils/file-service.js";
 import { createIssuesService } from "../utils/issues-service-bootstrap.js";
-import { handleAsyncCommand, outputSuccess } from "../utils/output.js";
+import { handleAsyncCommand, outputSuccess, outputWarning, } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
+import { parseWithIncludes, } from "../utils/with-includes.js";
+import { buildIncomingRelationEntries, buildOutgoingRelationEntries, } from "./issues/relations.js";
 /**
  * Issue ID pattern: 1-5 uppercase letters, dash, 1+ digits (e.g. ADM-652, DEV-12).
  */
@@ -23,7 +26,13 @@ export function setupReadShortcut(program) {
         .option("--field <name>", 'Extract a single named section from the issue description (e.g. "Done when"). ' +
         "Matches H2/H3 headers and bold pseudo-headers case-insensitively. " +
         "Outputs the section text only — no JSON envelope.")
-        .addHelpText("after", '\nExamples:\n  el-linear read ADM-652\n  el-linear get DEV-123 DEV-456\n  el-linear ADM-652          (auto-detected)\n  el-linear read DEV-123 --field "Done when"   (just that section)')
+        .option("--sections <names>", 'Extract multiple named description sections in one call (comma-separated, e.g. "Done when,Out of scope,Steps"). ' +
+        "Single-issue only. Returns a JSON envelope { identifier, sections: { name -> text|null } }; missing sections appear as null + a _warnings entry. " +
+        "Sibling of --field (singular). Named --sections rather than --fields because the program already has a global --fields for output-key filtering.")
+        .option("--with <names>", "Comma-separated opt-in includes. Each value fetches an extra " +
+        'block of data and adds it to the JSON envelope. Currently supported: "relations" ' +
+        "(adds an array of cross-issue relations under a top-level `relations` key).")
+        .addHelpText("after", '\nExamples:\n  el-linear read ADM-652\n  el-linear get DEV-123 DEV-456\n  el-linear ADM-652          (auto-detected)\n  el-linear read DEV-123 --field "Done when"   (just that section)\n  el-linear read DEV-123 --sections "Done when,Out of scope"\n  el-linear read DEV-123 --with relations       (issue + cross-issue links)')
         .action(handleAsyncCommand(readIssues));
     // Catch-all: if argv looks like `el-linear ADM-652 [DEV-123 ...]`, run read
     const originalParse = program.parse.bind(program);
@@ -58,15 +67,43 @@ export function setupReadShortcut(program) {
  */
 export async function readIssues(issueIds, options, command) {
     const rootOpts = getRootOpts(command);
-    const { issuesService } = await createIssuesService(rootOpts);
+    const { graphQLService, issuesService } = await createIssuesService(rootOpts);
     const fileService = await createFileService(rootOpts);
     const fieldName = typeof options.field === "string" ? options.field : null;
-    // --field is single-issue only. With multiple issues, a section
-    // extraction can't sensibly fan out to N different bodies — the
-    // caller almost always wants one section from one issue.
-    if (fieldName && issueIds.length > 1) {
-        throw new Error("--field is single-issue only; pass exactly one issueId. " +
-            "For multiple issues, drop --field and use --jq or --format summary.");
+    const sectionsRaw = typeof options.sections === "string" ? options.sections : null;
+    // DEV-4476: --with opt-in includes (currently `relations`). Throws on
+    // unknown values via parseWithIncludes — fail fast in the CLI per the
+    // deterministic-CLI doctrine.
+    const includes = typeof options.with === "string"
+        ? parseWithIncludes(options.with)
+        : { relations: false };
+    if (fieldName && sectionsRaw) {
+        throw new Error("--field and --sections are mutually exclusive. Use --field for a single section (plain-text output) or --sections for multiple (JSON map).");
+    }
+    // Both --field and --sections are single-issue only — section extraction
+    // can't sensibly fan out to N different bodies, the caller almost always
+    // wants the named sections of one issue.
+    if ((fieldName || sectionsRaw) && issueIds.length > 1) {
+        throw new Error("--field / --sections are single-issue only; pass exactly one issueId. " +
+            "For multiple issues, drop the section flags and use --jq or --format summary.");
+    }
+    // Parse the comma-separated --sections list once. Preserve the caller's
+    // order, trim each entry, and drop empties so trailing commas don't
+    // surface as ghost "" sections.
+    const sectionNames = sectionsRaw
+        ? sectionsRaw
+            .split(",")
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0)
+        : null;
+    if (sectionNames !== null && sectionNames.length === 0) {
+        throw new Error("--sections was empty after trimming. Pass a comma-separated list of section names.");
+    }
+    // --field is also an extract-this-section operation; pairing it with
+    // --with would produce ambiguous output (section text vs. JSON envelope).
+    // Reject up front rather than silently dropping one.
+    if (fieldName && includes.relations) {
+        throw new Error("--field and --with are mutually exclusive (--field outputs raw section text; --with extends the JSON envelope).");
     }
     if (issueIds.length === 1) {
         const issue = await issuesService.getIssueById(issueIds[0]);
@@ -83,13 +120,84 @@ export async function readIssues(issueIds, options, command) {
             process.stdout.write(`${section}\n`);
             return;
         }
-        outputSuccess(resolved);
+        if (sectionNames !== null) {
+            const sectionsMap = extractFields(resolved.description ?? "", sectionNames);
+            const sections = {};
+            const missing = [];
+            for (const [name, text] of sectionsMap) {
+                sections[name] = text;
+                if (text === null)
+                    missing.push(name);
+            }
+            if (missing.length > 0) {
+                // Coalesce: one warning naming every missing section is denser than
+                // N entries and easier for an agent to act on (cycle-1 nit).
+                outputWarning(`sections not found in ${resolved.identifier}'s description: ${missing
+                    .map((n) => `"${n}"`)
+                    .join(", ")}`);
+            }
+            outputSuccess({
+                identifier: resolved.identifier,
+                sections,
+            });
+            return;
+        }
+        // DEV-4476: --with relations (mutually exclusive with --sections, which
+        // returns above). Enrich the single-issue envelope when requested.
+        const envelope = includes.relations
+            ? {
+                ...resolved,
+                relations: await fetchRelations(graphQLService, resolved.id),
+            }
+            : resolved;
+        outputSuccess(envelope);
     }
     else {
-        const results = await Promise.all(issueIds.map(async (id) => {
-            const issue = await issuesService.getIssueById(id);
-            return downloadLinearUploads(issue, fileService);
+        // DEV-4477: one batched GraphQL call instead of N parallel single-issue
+        // queries. The service preserves input order and throws notFoundError
+        // on any missing ref. Attachment download still fans out per-issue —
+        // that's HTTP, not GraphQL, and downloadLinearUploads is a no-op when
+        // there's nothing to download.
+        const issues = await issuesService.getIssuesByRefs(issueIds);
+        const results = await Promise.all(
+        // Apply --with relations over the batch-fetched issues (DEV-4476),
+        // preserving DEV-4477's single batched GraphQL fetch above — don't
+        // re-fetch per id, which would defeat the batch optimization.
+        issues.map(async (issue) => {
+            const resolved = await downloadLinearUploads(issue, fileService);
+            if (!includes.relations) {
+                return resolved;
+            }
+            return {
+                ...resolved,
+                relations: await fetchRelations(graphQLService, resolved.id),
+            };
         }));
         outputSuccess(results);
     }
 }
+/**
+ * Fetch relations for a known-UUID issue and flatten outgoing + incoming
+ * via the shared relations builders. `relatedIssue` / `issue` peers that
+ * Linear omits (rare — deleted-relation edge case) are skipped, matching
+ * the `issues related` command's behavior.
+ *
+ * Race semantics: when `result.issue` is null (the issue existed at the
+ * `getIssueById` call upstream but is missing here — Linear deleted /
+ * unarchived it between the two calls), returns `[]` rather than
+ * throwing. The base issue is still emitted, and the caller sees an
+ * empty `relations` array — preferable to failing the whole envelope
+ * for a rare race. This intentionally diverges from `handleRelatedIssues`
+ * (which throws), because that command's *primary* output is relations,
+ * whereas here relations are an opt-in side dish.
+ */
+async function fetchRelations(graphQLService, issueId) {
+    const result = await graphQLService.rawRequest(GET_ISSUE_RELATIONS_QUERY, { id: issueId });
+    if (!result.issue) {
+        return [];
+    }
+    return [
+        ...buildOutgoingRelationEntries(result.issue.relations.nodes),
+        ...buildIncomingRelationEntries(result.issue.inverseRelations.nodes),
+    ];
+}

package/dist/queries/common.d.ts

@@ -1,2 +1,2 @@
-export declare const COMPLETE_ISSUE_FRAGMENT = "\n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n";
-export declare const COMPLETE_ISSUE_WITH_COMMENTS_FRAGMENT = "\n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n";
+export declare const COMPLETE_ISSUE_FRAGMENT = "\n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n";
+export declare const COMPLETE_ISSUE_WITH_COMMENTS_FRAGMENT = "\n  \n  \n  id\n  identifier\n  title\n  description\n  summary { content generationStatus }\n  branchName\n  priority\n  estimate\n  dueDate\n  url\n  createdAt\n  updatedAt\n\n  \n  state {\n    id\n    name\n    type\n  }\n\n  \n  assignee {\n    id\n    name\n    url\n  }\n\n  \n  delegate {\n    id\n    name\n    url\n  }\n\n  \n  team {\n    id\n    key\n    name\n  }\n\n  \n  project {\n    id\n    name\n  }\n\n  \n  labels {\n    nodes {\n      id\n      name\n    }\n  }\n\n  \n  cycle {\n    id\n    name\n    number\n  }\n\n  \n  projectMilestone {\n    id\n    name\n    targetDate\n  }\n\n  \n  parent {\n    id\n    identifier\n    title\n  }\n\n  \n  children {\n    nodes {\n      id\n      identifier\n      title\n    }\n  }\n\n\n  \n  comments {\n    nodes {\n      id\n      body\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        url\n      }\n    }\n  }\n\n";

package/dist/queries/common.js

@@ -16,6 +16,7 @@ const ISSUE_STATE_FRAGMENT = `
   state {
     id
     name
+    type
   }
 `;
 const ISSUE_ASSIGNEE_FRAGMENT = `

package/dist/queries/issue-tree.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Tree-fetch query builder for `issues tree <ID>` (DEV-4480).
+ *
+ * GraphQL has no native depth-N recursion, so the query is generated by
+ * nesting `children { nodes { ... } }` N times at build time. This keeps
+ * the *fetch* to a single round-trip even for deep trees, at the cost of
+ * a larger query string.
+ *
+ * Each level fetches the minimal field set needed to render a tree entry:
+ * id, identifier, title, state.{name,type}, assignee.name. State.type is
+ * present so the renderer can flag terminal states (Done / Canceled) and
+ * the caller's `--include-closed` filter can be applied client-side after
+ * the fetch (Linear doesn't accept a top-level filter that scopes to the
+ * issue subtree — the children connection is filterless).
+ *
+ * Depth bounds: `1` (just the root + its direct children) through `5`.
+ * Above 5 the query string grows too large to be useful as a single call;
+ * callers wanting deeper walks should iterate `tree` on leaf nodes.
+ */
+export declare const MIN_TREE_DEPTH = 1;
+export declare const MAX_TREE_DEPTH = 5;
+export declare const DEFAULT_TREE_DEPTH = 3;
+export declare function buildIssueTreeQuery(depth: number): string;
+/**
+ * Shape of a single tree node — used for both the GraphQL response and
+ * the post-filter return value (after `--include-closed` is applied
+ * client-side).
+ */
+export interface IssueTreeNode {
+    id: string;
+    identifier: string;
+    title: string;
+    state: {
+        id: string;
+        name: string;
+        type: string;
+    } | null;
+    assignee: {
+        id: string;
+        name: string;
+    } | null;
+    children?: {
+        nodes: IssueTreeNode[];
+    };
+}
+export interface GetIssueTreeResponse {
+    issue: IssueTreeNode | null;
+}