@enrichlayer/el-linear 1.21.0 → 1.23.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

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,6 +1029,10 @@ 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.")
@@ -1003,7 +1042,7 @@ export function setupIssuesCommands(program) {
         .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')
+        .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>")
@@ -1041,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>")
@@ -1106,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/projects.js

@@ -1,6 +1,6 @@
 import { loadConfig } from "../config/config.js";
 import { resolveTeam } from "../config/resolver.js";
-import { ARCHIVE_PROJECT_MUTATION, CREATE_PROJECT_MUTATION, DELETE_PROJECT_MUTATION, GET_PROJECT_QUERY, GET_PROJECT_TEAM_ISSUES_QUERY, PROJECT_BY_ID_QUERY, SEARCH_PROJECTS_BY_NAME_QUERY, UPDATE_PROJECT_MUTATION, } from "../queries/projects.js";
+import { ARCHIVE_PROJECT_MUTATION, CREATE_PROJECT_MUTATION, DELETE_PROJECT_MUTATION, GET_PROJECT_QUERY, GET_PROJECT_TEAM_ISSUES_QUERY, PROJECT_BY_ID_QUERY, PROJECT_READ_QUERY, SEARCH_PROJECTS_BY_NAME_QUERY, UPDATE_PROJECT_MUTATION, } from "../queries/projects.js";
 import { cached, resolveCacheTTL } from "../utils/disk-cache.js";
 import { createGraphQLService } from "../utils/graphql-service.js";
 import { createLinearService } from "../utils/linear-service.js";
@@ -413,6 +413,30 @@ async function handleDeleteProject(projectNameOrId, _options, command) {
         lastSyncId: payload.lastSyncId,
     });
 }
+/**
+ * Read a single project (DEV-4610). Resolves the identifier through the same
+ * `resolveProjectId` path the `--project` flags use (UUID / slug / URL / name),
+ * fetches the full project, and emits it. `teams.nodes` is flattened to a plain
+ * array so the `--format summary` project renderer (and the JSON shape) match
+ * `projects list` — the formatter expects a flat team list, not a `{ nodes }`
+ * connection. Replaces the raw-`graphql` workaround for grabbing a project's
+ * url / content / lead.
+ */
+async function handleReadProject(projectNameOrId, _options, command) {
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const linearService = await createLinearService(rootOpts);
+    const projectId = await linearService.resolveProjectId(projectNameOrId);
+    const result = await graphQLService.rawRequest(PROJECT_READ_QUERY, { id: projectId });
+    if (!result.project) {
+        throw new Error(`Project "${projectNameOrId}" not found`);
+    }
+    const { teams, ...rest } = result.project;
+    outputSuccess({
+        ...rest,
+        teams: teams.nodes.map((t) => ({ id: t.id, key: t.key, name: t.name })),
+    });
+}
 export function setupProjectsCommands(program) {
     const projects = program
         .command("projects")
@@ -435,6 +459,10 @@ export function setupProjectsCommands(program) {
         .command("delete <project>")
         .description("Delete (trash) a project (resolves names)")
         .action(handleAsyncCommand(handleDeleteProject));
+    projects
+        .command("read <project>")
+        .description("Read one project's full details (resolves name/slug/URL/ID). `--format summary` shows state, lead, teams, target, progress, url; JSON includes description/content.")
+        .action(handleAsyncCommand(handleReadProject));
     projects
         .command("list")
         .description("List projects")

package/dist/commands/read-shortcut.js

@@ -23,6 +23,10 @@ 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.")
@@ -32,7 +36,7 @@ export function setupReadShortcut(program) {
         .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)')
+        .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);
@@ -70,6 +74,7 @@ export async function readIssues(issueIds, options, command) {
     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
@@ -80,12 +85,19 @@ export async function readIssues(issueIds, options, command) {
     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
@@ -108,6 +120,17 @@ export async function readIssues(issueIds, options, command) {
     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) {

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/queries/projects-types.d.ts

@@ -34,6 +34,24 @@ interface ProjectWithIssuesNode extends ProjectBaseNode {
 export interface ProjectByIdResponse {
     project: ProjectBaseNode | null;
 }
+/** Full project read (`PROJECT_READ_QUERY`) — base fields + summary/JSON fields. */
+interface ProjectReadNode extends ProjectBaseNode {
+    state: string;
+    progress: number;
+    url: string;
+    startDate: string | null;
+    targetDate: string | null;
+    description: string | null;
+    content: string | null;
+    lead: {
+        id: string;
+        name: string;
+        displayName: string;
+    } | null;
+}
+export interface ProjectReadResponse {
+    project: ProjectReadNode | null;
+}
 export interface GetProjectResponse {
     projects: {
         nodes: ProjectBaseNode[];

package/dist/queries/projects.d.ts

@@ -1,5 +1,14 @@
 export declare const TEAM_LOOKUP_QUERY = "\n  query TeamLookup($key: String) {\n    teams(filter: { or: [{ key: { eq: $key } }, { name: { eq: $key } }] }, first: 1) {\n      nodes { id key name }\n    }\n  }\n";
 export declare const PROJECT_BY_ID_QUERY = "\n  query ProjectById($id: String!) {\n    project(id: $id) {\n      id\n      name\n      teams {\n        nodes { id key name }\n      }\n    }\n  }\n";
+/**
+ * Full single-project read for `el-linear projects read` (DEV-4610). Carries
+ * everything the `--format summary` project renderer shows (name, state, lead,
+ * teams, target, progress, url) plus the long-form `description`/`content` the
+ * JSON envelope exposes — so callers no longer fall back to a raw `graphql`
+ * query for a project URL or its content. The `progress` + `teams` fields also
+ * make the payload self-describing to the summary kind-inference.
+ */
+export declare const PROJECT_READ_QUERY = "\n  query ProjectRead($id: String!) {\n    project(id: $id) {\n      id\n      name\n      state\n      progress\n      url\n      startDate\n      targetDate\n      description\n      content\n      lead { id name displayName }\n      teams {\n        nodes { id key name }\n      }\n    }\n  }\n";
 export declare const GET_PROJECT_QUERY = "\n  query GetProject($name: String!) {\n    projects(filter: { name: { eqIgnoreCase: $name } }, first: 1) {\n      nodes {\n        id\n        name\n        teams {\n          nodes {\n            id\n            key\n            name\n          }\n        }\n      }\n    }\n  }\n";
 export declare const GET_PROJECT_TEAM_ISSUES_QUERY = "\n  query GetProjectTeamIssues($projectId: String!, $teamId: String!) {\n    project(id: $projectId) {\n      id\n      name\n      teams {\n        nodes {\n          id\n          key\n          name\n        }\n      }\n      issues(filter: { team: { id: { eq: $teamId } } }, first: 50) {\n        nodes {\n          id\n          identifier\n          title\n        }\n      }\n    }\n  }\n";
 export declare const SEARCH_PROJECTS_BY_NAME_QUERY = "\n  query SearchProjectsByName($name: String!) {\n    projects(filter: { name: { containsIgnoreCase: $name } }, first: 10) {\n      nodes {\n        id\n        name\n        state\n        teams {\n          nodes { id key name }\n        }\n      }\n    }\n  }\n";

package/dist/queries/projects.js

@@ -16,6 +16,33 @@ export const PROJECT_BY_ID_QUERY = `
     }
   }
 `;
+/**
+ * Full single-project read for `el-linear projects read` (DEV-4610). Carries
+ * everything the `--format summary` project renderer shows (name, state, lead,
+ * teams, target, progress, url) plus the long-form `description`/`content` the
+ * JSON envelope exposes — so callers no longer fall back to a raw `graphql`
+ * query for a project URL or its content. The `progress` + `teams` fields also
+ * make the payload self-describing to the summary kind-inference.
+ */
+export const PROJECT_READ_QUERY = `
+  query ProjectRead($id: String!) {
+    project(id: $id) {
+      id
+      name
+      state
+      progress
+      url
+      startDate
+      targetDate
+      description
+      content
+      lead { id name displayName }
+      teams {
+        nodes { id key name }
+      }
+    }
+  }
+`;
 export const GET_PROJECT_QUERY = `
   query GetProject($name: String!) {
     projects(filter: { name: { eqIgnoreCase: $name } }, first: 1) {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enrichlayer/el-linear",
-  "version": "1.21.0",
+  "version": "1.23.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",