@enrichlayer/el-linear 1.20.0 → 1.22.0

package/README.md

@@ -553,6 +553,38 @@ 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.
 
+### Print the whole description as raw text: `--body`
+
+`issues read --body` prints the issue's **entire** description as raw
+markdown — real newlines, no JSON envelope — instead of one named
+section. Single-issue only; exits 1 with a stderr hint when the issue has
+no description. This is the canonical replacement for
+`... --format json | python3 -c "...['description']"`.
+
+```bash
+el-linear issues read DEV-123 --body
+# ## Why we need this
+# ...full description body...
+```
+
+Mutually exclusive with `--field` / `--sections` / `--with`.
+
+### One-line write confirmations: `-q, --quiet`
+
+`issues create|update` and `comments create|update` accept `-q, --quiet`,
+printing a single confirmation line instead of the full JSON envelope so
+you don't have to `grep` the result:
+
+```bash
+el-linear issues update DEV-123 --status "In Review" --quiet
+# DEV-123  In Review  https://linear.app/acme/issue/DEV-123/...
+
+el-linear comments create DEV-123 --body "..." --quiet
+# comment 6f1c…
+```
+
+`--quiet` overrides `--format` and is independent of `--fields` / `--jq`.
+
 ### Render an issue's tree: `issues tree`
 
 `issues tree <ID>` walks the parent → children graph for an issue in a
@@ -599,6 +631,30 @@ 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

@@ -50,10 +50,20 @@ el-linear projects list --limit 50 2>&1 | head -100
 # ❌ Don't reach for jq just to print title + state
 el-linear issues read DEV-123 --jq '.title + " " + .state.name' 2>&1
 
+# ❌ Don't pipe a read through python just to get the whole description body
+el-linear issues read DEV-123 --format json 2>&1 | python3 -c "import json,sys; print(json.load(sys.stdin)['description'])"
+
+# ❌ Don't grep a write's JSON for the new state / url
+el-linear issues update DEV-123 --status Done 2>&1 | grep -iE 'state|url'
+
 # ✅ Just use --format summary
 el-linear issues search "..." --limit 10 --format summary 2>&1
 el-linear projects list --limit 50 --format summary 2>&1
 el-linear issues read DEV-123 --format summary 2>&1
+
+# ✅ Whole description as raw text → --body. Terse write confirmation → --quiet
+el-linear issues read DEV-123 --body 2>&1
+el-linear issues update DEV-123 --status Done --quiet 2>&1
 ```
 
 The summary formatter exists exactly because every consumer (humans and LLMs) was reinventing the same `python -c` / `jq` extraction in shell. Pick the canonical path; the per-resource format is a stable contract.
@@ -72,6 +82,34 @@ el-linear issues read DEV-123 2>&1 | python3 -c "import json,sys; print(json.loa
 
 `--field` is single-issue only — for batch extraction, fall back to `--jq` on the full JSON.
 
+### The whole description as raw text: `--body`
+
+When you want the **entire** description (not one section) as plain markdown — to read it, diff it, or pipe it to a file — use `issues read --body`. It prints the raw description with real newlines and no JSON envelope, single-issue only, and exits non-zero when the issue has no description. This is the canonical replacement for `... --format json | python3 -c "...['description']"` and the `sed 's/\\n/\n/g'` newline-unescaping hack.
+
+```bash
+# ✅ Full description, raw markdown, scriptable
+el-linear issues read DEV-123 --body 2>&1
+
+# ❌ Don't do this
+el-linear issues read DEV-123 --format json 2>&1 | python3 -c "import json,sys; print(json.load(sys.stdin)['description'])"
+```
+
+`--body` is mutually exclusive with `--field` / `--sections` / `--with` (those extract named parts or extend the JSON envelope; `--body` is the whole thing as text).
+
+### Terse write confirmations: `-q, --quiet`
+
+`issues create|update` and `comments create|update` accept `-q, --quiet`, which prints a single machine-stable confirmation line instead of the full JSON envelope — no need to `grep` the result for the identifier / state / url:
+
+```bash
+el-linear issues update DEV-123 --status "In Review" --quiet 2>&1
+# DEV-123  In Review  https://linear.app/acme/issue/DEV-123/...
+
+el-linear comments create DEV-123 --body "..." --quiet 2>&1
+# comment <id>
+```
+
+`--quiet` overrides `--format` (it's the whole point) and is independent of `--fields`/`--jq`.
+
 ### When you must reach outside el-linear: prefer `jq` over `python3 -c`
 
 For tools that aren't `el-linear` (e.g. `gh`, `glab`, `kubectl`), prefer `jq` for JSON extraction in one-shot shell commands. `python3 -c "import json,sys; ..."` produces longer, harder-to-read pipelines, and tends to attract incremental complexity (try/except, fallbacks) that `jq` handles inline. Reach for python only when the transformation genuinely needs control flow that's painful in `jq` (e.g. multi-step assembly with intermediate state).
@@ -201,11 +239,11 @@ el-linear issues link-references ENG-123 --dry-run            # preview
 
 When starting work on an existing issue (`el-linear issues read ENG-123`):
 
-- [ ] **Assignee set** — if missing, ask user and update: `el-linear issues update ENG-123 --assignee <name>`.
+- [ ] **Branch claim path used** — `el-linear issues create --checkout` and `el-linear issues mark-branch ENG-123` automatically claim the issue by assigning it to the current Linear user and moving it to the team's first started state. Use `--no-claim` only when intentionally creating/marking a branch on someone else's behalf.
 - [ ] **Project set** — if missing, ask user and update: `el-linear issues update ENG-123 --project "<name>"`.
-- [ ] **Status appropriate** — move to "In Progress" or your team's equivalent.
+- [ ] **Status appropriate** — if you did not use one of the branch claim paths, move the issue to "In Progress" or your team's equivalent.
 
-Don't start implementation work on an unassigned issue. The assignee is the person accountable.
+Don't start implementation work on an unassigned issue — the assignee is the person accountable. If you did not use one of the branch claim paths (or used `--no-claim`), assign the issue before proceeding.
 
 ---
 

package/dist/commands/comments.js

@@ -291,6 +291,7 @@ export function setupCommentsCommands(program) {
         .option("--no-auto-link", "skip wrapping issue refs as markdown links and creating sidebar relations")
         .option("--footer <text>", "text appended to the comment body (overrides config.messageFooter)")
         .option("--no-footer", "skip the configured messageFooter for this comment")
+        .option("-q, --quiet", "print one confirmation line (comment <id>) instead of the full JSON")
         .action(handleAsyncCommand(handleCreateComment));
     comments
         .command("update <commentId>")
@@ -299,6 +300,7 @@ export function setupCommentsCommands(program) {
         .option("--body-file <path>", "read new comment body from file")
         .option("--no-auto-mention", "do not auto-convert bare team-member names to @mentions")
         .option("--no-auto-link", "skip wrapping issue refs as markdown links and creating sidebar relations")
+        .option("-q, --quiet", "print one confirmation line (comment <id>) instead of the full JSON")
         .action(handleAsyncCommand(handleUpdateComment));
     comments
         .command("list <issueId>")

package/dist/commands/issues.js

@@ -37,6 +37,24 @@ function isImageFile(filename) {
     const ext = filename.lastIndexOf(".");
     return ext !== -1 && IMAGE_EXTENSIONS.has(filename.slice(ext).toLowerCase());
 }
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function warnClaimFailure(issueId, error) {
+    outputWarning(`Branch operation succeeded for ${issueId}, but auto-claim failed: ${errorMessage(error)}`);
+}
+async function maybeClaimBranchIssue(issueId, options, issuesService) {
+    if (options.claim === false) {
+        return undefined;
+    }
+    try {
+        return await issuesService.claimIssue(issueId);
+    }
+    catch (error) {
+        warnClaimFailure(issueId, error);
+        return undefined;
+    }
+}
 function validateUpdateOptions(options) {
     if (options.delegate && options.clearDelegate) {
         throw new Error("Cannot use --delegate and --clear-delegate together");
@@ -497,6 +515,7 @@ async function handleCreateIssue(title, options, command) {
         }
     }
     let branch;
+    let claim;
     if (options.checkout && result.branchName) {
         const branchName = toBranchName(result.branchName);
         // Only treat the branch as created (and surface it in the output) when
@@ -516,11 +535,13 @@ async function handleCreateIssue(title, options, command) {
                 outputWarning(`Created branch ${branch} but could not record its Linear issue marker. ` +
                     `Run 'el-linear issues mark-branch ${result.identifier}' from the branch to set it.`);
             }
+            claim = await maybeClaimBranchIssue(result.identifier, options, issuesService);
         }
     }
     const output = {
         ...result,
         ...(branch ? { branch } : {}),
+        ...(claim ? { claim } : {}),
         ...(relations.length > 0 ? { relations } : {}),
         ...(autoLinked ? { autoLinked } : {}),
         ...(attachments.length === 1
@@ -852,7 +873,7 @@ async function handleRetrolink(options, command) {
         ...(newBranch ? { branch: newBranch } : {}),
     });
 }
-async function handleMarkBranch(issueId, _options, _command) {
+async function handleMarkBranch(issueId, options, command) {
     const branch = currentGitBranch();
     if (!branch) {
         throw new Error("Not on a named git branch (detached HEAD or not in a repository).");
@@ -882,10 +903,22 @@ async function handleMarkBranch(issueId, _options, _command) {
     }
     const previous = getBranchLinearIssue(branch);
     setBranchLinearIssue(branch, identifier);
+    let claim;
+    if (options.claim !== false) {
+        try {
+            const rootOpts = getRootOpts(command);
+            const { issuesService } = await createIssuesService(rootOpts);
+            claim = await issuesService.claimIssue(identifier);
+        }
+        catch (error) {
+            warnClaimFailure(identifier, error);
+        }
+    }
     outputSuccess({
         branch,
         linearIssue: identifier,
         ...(previous && previous !== identifier ? { previous } : {}),
+        ...(claim ? { claim } : {}),
         marked: true,
     });
 }
@@ -965,10 +998,12 @@ export function setupIssuesCommands(program) {
         .option("--attachment <path>", "attach a file (image, PDF, etc.) to the created issue (repeatable)", (value, prev) => prev ? [...prev, value] : [value])
         .option("--due-date <date>", "due date (YYYY-MM-DD)")
         .option("--checkout", "create and checkout a git branch named after the issue")
+        .option("--no-claim", "with --checkout, skip assigning the issue to the current Linear user and moving it to the first started state")
         .option("--skip-validation", "skip all validation (labels, description, assignee, project)")
         .option("--no-auto-link", "skip auto-linking issue references found in the description")
         .option("--footer <text>", "text appended to the description (overrides config.messageFooter)")
         .option("--no-footer", "skip the configured messageFooter for this issue")
+        .option("-q, --quiet", "print one confirmation line (IDENTIFIER  STATE  URL) instead of the full JSON")
         .action(handleAsyncCommand((titleArg, options, command) => {
         // Normalize --label alias to --labels
         if (options.label && !options.labels) {
@@ -994,13 +1029,20 @@ export function setupIssuesCommands(program) {
         .alias("get")
         .alias("show")
         .description("Get issue details. Accepts multiple IDs for batch retrieval.")
+        .option("--body", "Print the issue's full description as raw markdown text — no JSON " +
+        "envelope, single-issue only. Exits non-zero if the issue has no " +
+        "description. The whole-body sibling of --field; mutually exclusive " +
+        "with --field / --sections / --with.")
         .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.")
         .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.")
-        .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"')
+        .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\nFull description: el-linear issue read DEV-123 --body\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>")
@@ -1038,6 +1080,7 @@ export function setupIssuesCommands(program) {
         .option("--blocks <issues>", "issues this blocks (comma-separated)")
         .option("--blocked-by <issues>", "issues blocking this (comma-separated)")
         .option("--duplicate-of <issue>", "mark as duplicate of another issue")
+        .option("-q, --quiet", "print one confirmation line (IDENTIFIER  STATE  URL) instead of the full JSON")
         .action(handleAsyncCommand(handleUpdateIssue));
     issues
         .command("archive <issueId>")
@@ -1103,6 +1146,8 @@ export function setupIssuesCommands(program) {
         .description("Record the current branch's Linear issue as git metadata (branch.<branch>.linearIssue).")
         .addHelpText("after", "\nManual recovery for branches not created via 'issues create --checkout' / 'retrolink'.\n" +
         "With no argument, infers the identifier from the branch name (e.g. dev-4293-slug -> DEV-4293).\n" +
-        "Accepts a bare identifier (DEV-123), a branch-style token, or a Linear URL.")
+        "Accepts a bare identifier (DEV-123), a branch-style token, or a Linear URL.\n" +
+        "By default, also claims the issue (assignee = current Linear user; status = first started state). Pass --no-claim to only write git metadata.")
+        .option("--no-claim", "only record git metadata; skip assigning the issue to the current Linear user and moving it to the first started state")
         .action(handleAsyncCommand(handleMarkBranch));
 }

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, extractFields } from "../utils/extract-field.js";
 import { createFileService } from "../utils/file-service.js";
 import { createIssuesService } from "../utils/issues-service-bootstrap.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).
  */
@@ -20,13 +23,20 @@ export function setupReadShortcut(program) {
         .alias("view")
         .alias("show")
         .description("Shortcut for `issues read`. Get issue details by identifier.")
+        .option("--body", "Print the issue's full description as raw markdown text — no JSON " +
+        "envelope, single-issue only. Exits non-zero if the issue has no " +
+        "description. The whole-body sibling of --field; mutually exclusive " +
+        "with --field / --sections / --with.")
         .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.")
         .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.")
-        .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"')
+        .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 --body                 (full description, raw text)\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);
@@ -61,19 +71,33 @@ 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;
+    const bodyOnly = options.body === true;
     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.");
+    // --body prints the WHOLE description as raw text (no envelope) — it's the
+    // "all sections" sibling of --field. Pairing it with section extraction or
+    // --with would produce two conflicting output shapes, so reject up front.
+    if (bodyOnly && (fieldName || sectionsRaw || includes.relations)) {
+        throw new Error("--body is mutually exclusive with --field / --sections / --with. " +
+            "Use --body for the entire description, --field/--sections for named parts.");
+    }
+    // --field / --sections / --body are single-issue only — raw text extraction
+    // can't sensibly fan out to N different bodies; the caller almost always
+    // wants the named sections (or full body) of one issue.
+    if ((fieldName || sectionsRaw || bodyOnly) && issueIds.length > 1) {
+        throw new Error("--field / --sections / --body are single-issue only; pass exactly one issueId. " +
+            "For multiple issues, drop those 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
@@ -87,9 +111,26 @@ export async function readIssues(issueIds, options, command) {
     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]);
         const resolved = await downloadLinearUploads(issue, fileService);
+        if (bodyOnly) {
+            const description = resolved.description ?? "";
+            if (description.trim() === "") {
+                // Mirror --field's "not found" contract: nothing on stdout,
+                // exit non-zero with a stderr hint so scripts can branch.
+                process.stderr.write(`el-linear: ${resolved.identifier} has no description\n`);
+                process.exit(1);
+            }
+            process.stdout.write(`${description}\n`);
+            return;
+        }
         if (fieldName) {
             const section = extractField(resolved.description ?? "", fieldName);
             if (section === null) {
@@ -124,7 +165,15 @@ export async function readIssues(issueIds, options, command) {
             });
             return;
         }
-        outputSuccess(resolved);
+        // 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 {
         // DEV-4477: one batched GraphQL call instead of N parallel single-issue
@@ -133,7 +182,45 @@ export async function readIssues(issueIds, options, command) {
         // 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(issues.map((issue) => downloadLinearUploads(issue, fileService)));
+        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/main.js

@@ -31,7 +31,7 @@ import { setActiveProfileForSession } from "./config/paths.js";
 import { initCliSentry } from "./sentry.js";
 import { logger } from "./utils/logger.js";
 import { applyIpv4Preference } from "./utils/network-preference.js";
-import { setFieldsFilter, setJqFilter, setOutputFormat, setRawMode, } from "./utils/output.js";
+import { setFieldsFilter, setJqFilter, setOutputFormat, setQuietMode, setRawMode, } from "./utils/output.js";
 import { outputUsageInfo } from "./utils/usage.js";
 import { splitList } from "./utils/validators.js";
 // Prefer IPv4 for outbound API calls before any network I/O (Sentry init or a
@@ -79,6 +79,12 @@ program.hook("preAction", (_thisCommand, actionCommand) => {
     if (rootOpts.fields) {
         setFieldsFilter(splitList(rootOpts.fields));
     }
+    // --quiet is registered only on the write commands (issues/comments
+    // create|update); it surfaces here via optsWithGlobals. One confirmation
+    // line instead of the full envelope — see setQuietMode.
+    if (rootOpts.quiet) {
+        setQuietMode(true);
+    }
     // Subcommand --format wins over the global flag (commander resolves
     // options closest to the action), so `optsWithGlobals` returns the
     // subcommand value when one is set. We accept any of the per-command

package/dist/queries/issues-types.d.ts

@@ -214,6 +214,29 @@ export interface IssueStartContextResponse {
         delegate: AssigneeNode | null;
     } | null;
 }
+export interface IssueClaimContextResponse {
+    viewer: {
+        id: string;
+        name: string;
+        displayName: string;
+        email: string;
+    } | null;
+    issue: {
+        id: string;
+        identifier: string;
+        state: {
+            id: string;
+            name: string;
+            type: WorkflowStateType;
+        } | null;
+        assignee: AssigneeNode | null;
+        team: {
+            id: string;
+            key: string;
+            name: string;
+        } | null;
+    } | null;
+}
 export interface TeamStartedStatusesResponse {
     team: {
         states: {

package/dist/queries/issues.d.ts

@@ -80,6 +80,12 @@ export declare function buildResolveLabelsByNameQuery(labelNames: string[]): {
 export declare const GET_ISSUE_STATE_HISTORY_QUERY = "\n  query GetIssueStateHistory($id: String!) {\n    issue(id: $id) {\n      id\n      identifier\n      title\n      stateHistory {\n        nodes {\n          state { id name type }\n          startedAt\n          endedAt\n        }\n      }\n    }\n  }\n";
 export declare const GET_ISSUE_TEAM_QUERY = "\n  query GetIssueTeam($issueId: String!) {\n    issue(id: $issueId) {\n      team { id }\n    }\n  }\n";
 export declare const GET_ISSUE_START_CONTEXT_QUERY = "\n  query GetIssueStartContext($id: String!) {\n    issue(id: $id) {\n      id\n      identifier\n      state { id name type }\n      team { id key name }\n      delegate { id name url }\n    }\n  }\n";
+/**
+ * Batch issue lifecycle/assignee context with the authenticated viewer for the
+ * branch auto-claim flow. Raw GraphQL is used because this needs `viewer` plus
+ * issue fields in one round-trip; the SDK would make separate calls.
+ */
+export declare const GET_ISSUE_CLAIM_CONTEXT_QUERY = "\n  query GetIssueClaimContext($id: String!) {\n    viewer {\n      id\n      name\n      displayName\n      email\n    }\n    issue(id: $id) {\n      id\n      identifier\n      state { id name type }\n      assignee { id name url }\n      team { id key name }\n    }\n  }\n";
 export declare const TEAM_STARTED_STATUSES_QUERY = "\n  query TeamStartedStatuses($teamId: String!) {\n    team(id: $teamId) {\n      states(filter: { type: { eq: \"started\" } }) {\n        nodes {\n          id\n          name\n          position\n        }\n      }\n    }\n  }\n";
 export declare const ISSUE_RELATION_CREATE_MUTATION = "\n  mutation IssueRelationCreate($input: IssueRelationCreateInput!) {\n    issueRelationCreate(input: $input) {\n      success\n      issueRelation {\n        id\n        type\n        issue {\n          id\n          identifier\n          title\n        }\n        relatedIssue {\n          id\n          identifier\n          title\n        }\n      }\n    }\n  }\n";
 export declare const GET_ISSUE_RELATIONS_QUERY = "\n  query GetIssueRelations($id: String!) {\n    issue(id: $id) {\n      id\n      identifier\n      title\n      description\n      relations {\n        nodes {\n          id\n          type\n          relatedIssue {\n            id\n            identifier\n            title\n            state { id name }\n            priority\n            assignee { id name }\n            team { id key name }\n          }\n        }\n      }\n      inverseRelations {\n        nodes {\n          id\n          type\n          issue {\n            id\n            identifier\n            title\n            state { id name }\n            priority\n            assignee { id name }\n            team { id key name }\n          }\n        }\n      }\n    }\n  }\n";

package/dist/queries/issues.js

@@ -472,6 +472,28 @@ export const GET_ISSUE_START_CONTEXT_QUERY = `
     }
   }
 `;
+/**
+ * Batch issue lifecycle/assignee context with the authenticated viewer for the
+ * branch auto-claim flow. Raw GraphQL is used because this needs `viewer` plus
+ * issue fields in one round-trip; the SDK would make separate calls.
+ */
+export const GET_ISSUE_CLAIM_CONTEXT_QUERY = `
+  query GetIssueClaimContext($id: String!) {
+    viewer {
+      id
+      name
+      displayName
+      email
+    }
+    issue(id: $id) {
+      id
+      identifier
+      state { id name type }
+      assignee { id name url }
+      team { id key name }
+    }
+  }
+`;
 export const TEAM_STARTED_STATUSES_QUERY = `
   query TeamStartedStatuses($teamId: String!) {
     team(id: $teamId) {

package/dist/utils/formatters/summary.d.ts

@@ -60,3 +60,21 @@ export declare function inferKindFromPayload(value: unknown): ResourceKind;
  * array or a `{ data: [...] }` envelope — both are handled.
  */
 export declare function dispatch(kind: ResourceKind, payload: unknown): string;
+/**
+ * One-line confirmation render for the `--quiet` write path.
+ *
+ * Writes (`issues create|update`, `comments create|update`) otherwise emit
+ * the full JSON envelope; agents then `grep` it for the identifier / state /
+ * url. `--quiet` routes the same payload here so the caller gets exactly one
+ * machine-stable line and nothing else.
+ *
+ * - issue   → `IDENTIFIER  STATE  URL` (two-space separated, matching the
+ *             summary header style). Empty fields collapse to `-`.
+ * - comment → `comment <id>` (the create/update mutation doesn't fetch a url
+ *             or the parent identifier, so the id — what you need to edit or
+ *             reference the comment — is the stable handle).
+ * - anything else → compact single-line JSON, so the contract ("one line,
+ *             always parseable") holds even for payloads with no dedicated
+ *             shape.
+ */
+export declare function formatLine(payload: unknown): string;

package/dist/utils/formatters/summary.js

@@ -758,3 +758,33 @@ export function dispatch(kind, payload) {
             return formatGenericSummary(payload);
     }
 }
+/**
+ * One-line confirmation render for the `--quiet` write path.
+ *
+ * Writes (`issues create|update`, `comments create|update`) otherwise emit
+ * the full JSON envelope; agents then `grep` it for the identifier / state /
+ * url. `--quiet` routes the same payload here so the caller gets exactly one
+ * machine-stable line and nothing else.
+ *
+ * - issue   → `IDENTIFIER  STATE  URL` (two-space separated, matching the
+ *             summary header style). Empty fields collapse to `-`.
+ * - comment → `comment <id>` (the create/update mutation doesn't fetch a url
+ *             or the parent identifier, so the id — what you need to edit or
+ *             reference the comment — is the stable handle).
+ * - anything else → compact single-line JSON, so the contract ("one line,
+ *             always parseable") holds even for payloads with no dedicated
+ *             shape.
+ */
+export function formatLine(payload) {
+    const kind = inferKindFromPayload(payload);
+    const obj = asObj(payload);
+    if (kind === "issue" && obj) {
+        // s()/getName() already render missing values as the em-dash placeholder
+        // used throughout the summary formatter, keeping --quiet consistent.
+        return `${s(obj.identifier)}  ${getName(obj.state)}  ${s(obj.url)}`;
+    }
+    if (kind === "comment" && obj) {
+        return `comment ${s(obj.id)}`;
+    }
+    return JSON.stringify(payload);
+}

package/dist/utils/graphql-issues-service.d.ts

@@ -151,6 +151,33 @@ export interface StartIssueResult {
         name: string;
     };
 }
+export interface ClaimIssueResult {
+    issue: LinearIssue;
+    claimed: boolean;
+    /** True when the issue was already started and assigned to the viewer, so the claim was a no-op. */
+    alreadyClaimed: boolean;
+    assigned: boolean;
+    started: boolean;
+    assignee: {
+        id: string;
+        name: string;
+        displayName: string;
+        email: string;
+    };
+    previousAssignee?: {
+        id: string;
+        name: string;
+    };
+    previousState?: {
+        id: string;
+        name: string;
+        type: string;
+    };
+    targetState?: {
+        id: string;
+        name: string;
+    };
+}
 export declare class GraphQLIssuesService {
     private readonly graphQLService;
     private readonly linearService;
@@ -175,7 +202,9 @@ export declare class GraphQLIssuesService {
      * for the read handler — the JSON envelope is a positional array.
      */
     getIssuesByRefs(refs: string[]): Promise<LinearIssue[]>;
+    private getFirstStartedStatus;
     startIssue(issueId: string): Promise<StartIssueResult>;
+    claimIssue(issueId: string): Promise<ClaimIssueResult>;
     updateIssue(args: UpdateIssueArgs, labelMode?: string): Promise<LinearIssue>;
     archiveIssue(issueId: string): Promise<IssueArchiveOperationResult>;
     deleteIssue(issueId: string, options?: {

package/dist/utils/graphql-issues-service.js

@@ -1,5 +1,5 @@
 import { resolveUserDisplayName } from "../config/resolver.js";
-import { ARCHIVE_ISSUE_MUTATION, BATCH_GET_ISSUES_QUERY, BATCH_RESOLVE_FOR_CREATE_QUERY, BATCH_RESOLVE_FOR_SEARCH_QUERY, BATCH_RESOLVE_FOR_UPDATE_QUERY, buildResolveLabelsByNameQuery, CREATE_ISSUE_MUTATION, DELETE_ISSUE_MUTATION, FILTERED_SEARCH_ISSUES_QUERY, GET_ISSUE_BY_ID_QUERY, GET_ISSUE_BY_IDENTIFIER_QUERY, GET_ISSUE_START_CONTEXT_QUERY, GET_ISSUE_TEAM_QUERY, GET_ISSUES_QUERY, SEARCH_ISSUES_QUERY, TEAM_STARTED_STATUSES_QUERY, UPDATE_ISSUE_MUTATION, } from "../queries/issues.js";
+import { ARCHIVE_ISSUE_MUTATION, BATCH_GET_ISSUES_QUERY, BATCH_RESOLVE_FOR_CREATE_QUERY, BATCH_RESOLVE_FOR_SEARCH_QUERY, BATCH_RESOLVE_FOR_UPDATE_QUERY, buildResolveLabelsByNameQuery, CREATE_ISSUE_MUTATION, DELETE_ISSUE_MUTATION, FILTERED_SEARCH_ISSUES_QUERY, GET_ISSUE_BY_ID_QUERY, GET_ISSUE_BY_IDENTIFIER_QUERY, GET_ISSUE_CLAIM_CONTEXT_QUERY, GET_ISSUE_START_CONTEXT_QUERY, GET_ISSUE_TEAM_QUERY, GET_ISSUES_QUERY, SEARCH_ISSUES_QUERY, TEAM_STARTED_STATUSES_QUERY, UPDATE_ISSUE_MUTATION, } from "../queries/issues.js";
 import { CREATE_LABEL_MUTATION } from "../queries/labels.js";
 import { toISOStringOrNow } from "./date-format.js";
 import { extractEmbeds } from "./embed-parser.js";
@@ -150,6 +150,16 @@ export class GraphQLIssuesService {
         }
         return ordered.map((issue) => this.transformIssueData(issue));
     }
+    async getFirstStartedStatus(team) {
+        const statuses = await this.graphQLService.rawRequest(TEAM_STARTED_STATUSES_QUERY, { teamId: team.id });
+        const startedStatus = statuses.team?.states.nodes
+            .slice()
+            .sort((a, b) => a.position - b.position)[0];
+        if (!startedStatus) {
+            throw new Error(`Team ${team.key} has no workflow status of type "started".`);
+        }
+        return { id: startedStatus.id, name: startedStatus.name };
+    }
     async startIssue(issueId) {
         const resolvedIssueId = await this.linearService.resolveIssueId(issueId);
         const context = await this.graphQLService.rawRequest(GET_ISSUE_START_CONTEXT_QUERY, { id: resolvedIssueId });
@@ -175,13 +185,7 @@ export class GraphQLIssuesService {
         if (!issue.team?.id) {
             throw new Error(`Issue ${issue.identifier} has no team; cannot start it.`);
         }
-        const statuses = await this.graphQLService.rawRequest(TEAM_STARTED_STATUSES_QUERY, { teamId: issue.team.id });
-        const startedStatus = statuses.team?.states.nodes
-            .slice()
-            .sort((a, b) => a.position - b.position)[0];
-        if (!startedStatus) {
-            throw new Error(`Team ${issue.team.key} has no workflow status of type "started".`);
-        }
+        const startedStatus = await this.getFirstStartedStatus(issue.team);
         const updated = await this.updateIssue({ id: resolvedIssueId, statusId: startedStatus.id }, "adding");
         return {
             issue: updated,
@@ -190,6 +194,68 @@ export class GraphQLIssuesService {
             targetState: { id: startedStatus.id, name: startedStatus.name },
         };
     }
+    async claimIssue(issueId) {
+        const resolvedIssueId = await this.linearService.resolveIssueId(issueId);
+        const context = await this.graphQLService.rawRequest(GET_ISSUE_CLAIM_CONTEXT_QUERY, { id: resolvedIssueId });
+        const issue = context.issue;
+        if (!issue) {
+            throw notFoundError("Issue", issueId);
+        }
+        const viewer = context.viewer;
+        if (!viewer?.id) {
+            throw new Error("Could not resolve the authenticated Linear viewer.");
+        }
+        const previousState = issue.state
+            ? {
+                id: issue.state.id,
+                name: issue.state.name,
+                type: issue.state.type,
+            }
+            : undefined;
+        const previousAssignee = issue.assignee
+            ? { id: issue.assignee.id, name: issue.assignee.name }
+            : undefined;
+        const terminalState = previousState && ["completed", "canceled"].includes(previousState.type);
+        const needsStartedState = !terminalState && previousState?.type !== "started";
+        const needsAssignee = issue.assignee?.id !== viewer.id;
+        if (!needsStartedState && !needsAssignee) {
+            // This path is only reachable when the viewer is already the assignee
+            // (`needsAssignee` is false), so `assignee: viewer` is the current assignee.
+            return {
+                issue: await this.getIssueById(resolvedIssueId),
+                previousState,
+                previousAssignee,
+                claimed: false,
+                alreadyClaimed: true,
+                assigned: false,
+                started: false,
+                assignee: viewer,
+            };
+        }
+        let targetState;
+        if (needsStartedState) {
+            if (!issue.team?.id) {
+                throw new Error(`Issue ${issue.identifier} has no team; cannot start it.`);
+            }
+            targetState = await this.getFirstStartedStatus(issue.team);
+        }
+        const updated = await this.updateIssue({
+            id: resolvedIssueId,
+            ...(targetState ? { statusId: targetState.id } : {}),
+            ...(needsAssignee ? { assigneeId: viewer.id } : {}),
+        }, "adding");
+        return {
+            issue: updated,
+            previousState,
+            previousAssignee,
+            ...(targetState ? { targetState } : {}),
+            claimed: true,
+            alreadyClaimed: false,
+            assigned: needsAssignee,
+            started: Boolean(targetState),
+            assignee: viewer,
+        };
+    }
     async updateIssue(args, labelMode = "overwriting") {
         // Normalize URL/slug-id --project inputs to UUIDs before the batch
         // resolver runs; see comment on `withNormalizedProjectId`.

package/dist/utils/output.d.ts

@@ -1,5 +1,11 @@
 type OutputFormat = "json" | "summary";
 export declare function setRawMode(enabled: boolean): void;
+/**
+ * `--quiet` (write commands only): collapse the success payload to a single
+ * confirmation line via `formatLine`, bypassing both the JSON envelope and
+ * the summary block. Set in main.ts's preAction when the flag is present.
+ */
+export declare function setQuietMode(enabled: boolean): void;
 export declare function setJqFilter(filter: string | null): void;
 export declare function setFieldsFilter(fields: string[] | null): void;
 export declare function setOutputFormat(format: OutputFormat): void;

package/dist/utils/output.js

@@ -1,15 +1,24 @@
 import { execFileSync } from "node:child_process";
-import { dispatch as dispatchSummary, inferKindFromPayload, } from "./formatters/summary.js";
+import { dispatch as dispatchSummary, formatLine, inferKindFromPayload, } from "./formatters/summary.js";
 import { logger } from "./logger.js";
 import { sanitizeForLog } from "./sanitize-for-log.js";
 const warningBuffer = [];
 let rawMode = false;
+let quietMode = false;
 let jqFilter = null;
 let fieldsFilter = null;
 let outputFormat = "json";
 export function setRawMode(enabled) {
     rawMode = enabled;
 }
+/**
+ * `--quiet` (write commands only): collapse the success payload to a single
+ * confirmation line via `formatLine`, bypassing both the JSON envelope and
+ * the summary block. Set in main.ts's preAction when the flag is present.
+ */
+export function setQuietMode(enabled) {
+    quietMode = enabled;
+}
 export function setJqFilter(filter) {
     jqFilter = filter;
 }
@@ -102,6 +111,15 @@ export function outputSuccess(data) {
     // `title` on an issue) breaks shape inference and the summary
     // formatter falls back to the generic key-value dump.
     const inferredKind = outputFormat === "summary" ? inferKindFromPayload(output) : "generic";
+    // --quiet: one machine-stable confirmation line, nothing else. Highest
+    // precedence on the write path and independent of --raw / --fields / --jq
+    // (those reshape the payload the flag exists to avoid) — so we emit from
+    // the full pre-filter object, otherwise `--fields identifier` would strip
+    // the state/url formatLine needs and break shape inference.
+    if (quietMode) {
+        logger.info(formatLine(output));
+        return;
+    }
     // --raw: unwrap { data: [...] } to just the array
     if (rawMode &&
         output !== null &&

package/dist/utils/with-includes.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `issues read --with` parser (DEV-4476).
+ *
+ * Opt-in includes for `issues read`. Each value names an additional block
+ * of data to fetch alongside the base issue and inject into the JSON
+ * envelope. Comma-separated; whitespace tolerated; unknown values rejected
+ * with a structured error naming the candidates (deterministic-CLI
+ * doctrine — fail fast in the CLI, not in the consumer's script).
+ *
+ * Currently supported:
+ *   - `relations` — fetches `Issue.relations` + `Issue.inverseRelations`
+ *                   and adds a `relations` array to the envelope.
+ *
+ * Reserved for future MRs (the value space is a closed set so adding more
+ * later is back-compat):
+ *   - `children`  — refetch with expanded sub-issue fragment (state,
+ *                   assignee, priority — beyond the default id/identifier/
+ *                   title trio that's already in the envelope).
+ *   - `comments`  — no-op for fetching (comments are already in the
+ *                   default envelope via `_WITH_COMMENTS` fragment) but
+ *                   would gate explicit summary-format rendering.
+ *
+ * Doctrine note: comments are intentionally NOT included today because
+ * adding `--with comments` would imply that comments are *off* by default,
+ * which would be a breaking JSON-shape change.
+ */
+export declare const WITH_INCLUDE_VALUES: readonly ["relations"];
+export type WithInclude = (typeof WITH_INCLUDE_VALUES)[number];
+export interface ParsedWithIncludes {
+    relations: boolean;
+}
+/**
+ * Parse a `--with <names>` argument. Returns a flag object so call sites
+ * read `if (includes.relations)` instead of `Set.has("relations")`.
+ *
+ * Empty / whitespace-only values are caller errors (commander allows
+ * `--with ""` through) — reject with the same message as unknown values
+ * so the user gets one consistent failure mode.
+ */
+export declare function parseWithIncludes(raw: string): ParsedWithIncludes;

package/dist/utils/with-includes.js

@@ -0,0 +1,55 @@
+/**
+ * `issues read --with` parser (DEV-4476).
+ *
+ * Opt-in includes for `issues read`. Each value names an additional block
+ * of data to fetch alongside the base issue and inject into the JSON
+ * envelope. Comma-separated; whitespace tolerated; unknown values rejected
+ * with a structured error naming the candidates (deterministic-CLI
+ * doctrine — fail fast in the CLI, not in the consumer's script).
+ *
+ * Currently supported:
+ *   - `relations` — fetches `Issue.relations` + `Issue.inverseRelations`
+ *                   and adds a `relations` array to the envelope.
+ *
+ * Reserved for future MRs (the value space is a closed set so adding more
+ * later is back-compat):
+ *   - `children`  — refetch with expanded sub-issue fragment (state,
+ *                   assignee, priority — beyond the default id/identifier/
+ *                   title trio that's already in the envelope).
+ *   - `comments`  — no-op for fetching (comments are already in the
+ *                   default envelope via `_WITH_COMMENTS` fragment) but
+ *                   would gate explicit summary-format rendering.
+ *
+ * Doctrine note: comments are intentionally NOT included today because
+ * adding `--with comments` would imply that comments are *off* by default,
+ * which would be a breaking JSON-shape change.
+ */
+export const WITH_INCLUDE_VALUES = ["relations"];
+/**
+ * Parse a `--with <names>` argument. Returns a flag object so call sites
+ * read `if (includes.relations)` instead of `Set.has("relations")`.
+ *
+ * Empty / whitespace-only values are caller errors (commander allows
+ * `--with ""` through) — reject with the same message as unknown values
+ * so the user gets one consistent failure mode.
+ */
+export function parseWithIncludes(raw) {
+    const names = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (names.length === 0) {
+        throw new Error(`--with requires at least one include name. Supported: ${WITH_INCLUDE_VALUES.join(", ")}`);
+    }
+    const includes = { relations: false };
+    for (const name of names) {
+        if (!WITH_INCLUDE_VALUES.includes(name)) {
+            throw new Error(`--with: unknown include "${name}". Supported: ${WITH_INCLUDE_VALUES.join(", ")}`);
+        }
+        // Narrowing: only assignable members of ParsedWithIncludes.
+        if (name === "relations") {
+            includes.relations = true;
+        }
+    }
+    return includes;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "description": "A pragmatic CLI for Linear.app — deterministic team/label/member resolution, structured issue validation, configurable term enforcement, and a GraphQL escape hatch.",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",