@enrichlayer/el-linear 1.32.1 → 1.32.3

package/README.md

@@ -442,7 +442,7 @@ el-linear <command> --help       # detailed help for one command
 | Group | Common commands |
 |-------|-----------------|
 | Issues | `issues {list, search, create, read, update, start, delete, history, related, link-references}` |
-| Comments | `comments {list, create, update}` |
+| Comments | `comments {list, read, create, update, delete}` |
 | Labels | `labels {list, create, retire, restore}` |
 | Projects | `projects {list, add-team, remove-team}` |
 | Cycles | `cycles {list, read}` |
@@ -660,6 +660,29 @@ el-linear issues read DEV-123 --body
 
 Mutually exclusive with `--field` / `--sections` / `--with`.
 
+### Read full comment bodies without JSON parsing
+
+`comments read <comment-id>` reads one comment by full UUID, `comment-<hash>`
+token, or a Linear URL containing `#comment-<hash>`. Use `--body` for the raw
+markdown body with real newlines and no JSON envelope. `comments list --body`
+prints every complete body on an issue as plain text blocks, and
+`comments list --format summary --no-truncate` keeps the summary shape while
+showing full bodies.
+
+```bash
+el-linear comments list DEV-123 --format summary
+# comment c5d15b28-...  Alice  2026-07-01T00:00:00.000Z
+# Short preview...
+
+el-linear comments read comment-c5d15b28 --body
+# Full comment body...
+
+el-linear comments list DEV-123 --body
+# comment c5d15b28-...
+#
+# Full comment body...
+```
+
 ### One-line write confirmations: `-q, --quiet`
 
 `issues create|update`, `issues relate`, and `comments create|update` accept

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

@@ -63,6 +63,9 @@ 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 comments read comment-c5d15b28 --body 2>&1
+el-linear comments list DEV-123 --body 2>&1
+el-linear comments list DEV-123 --format summary --no-truncate 2>&1
 el-linear issues update DEV-123 --status Done --quiet 2>&1
 ```
 
@@ -96,6 +99,28 @@ el-linear issues read DEV-123 --format json 2>&1 | python3 -c "import json,sys;
 
 `--body` is mutually exclusive with `--field` / `--sections` / `--with` (those extract named parts or extend the JSON envelope; `--body` is the whole thing as text).
 
+### Comment reads and full comment bodies
+
+When you need a specific comment, or the full text of a long comment, use the
+comments read/list surfaces instead of dumping JSON:
+
+```bash
+# ✅ Resolve a Linear permalink anchor or full comment UUID
+el-linear comments read comment-c5d15b28 --format summary 2>&1
+el-linear comments read comment-c5d15b28 --body 2>&1
+
+# ✅ Full bodies for every comment on an issue
+el-linear comments list DEV-123 --body 2>&1
+el-linear comments list DEV-123 --format summary --no-truncate 2>&1
+
+# ❌ Don't do this
+el-linear comments list DEV-123 --format json 2>&1 | python3 -c "import json,sys; print(json.load(sys.stdin)['data'][0]['body'])"
+```
+
+`comments read` accepts a full UUID, `comment-<hash>`, or a URL containing
+`#comment-<hash>`. `comments list --format summary` includes each comment id
+so you can copy it straight into `comments read`.
+
 ### 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:
@@ -118,7 +143,7 @@ For tools that aren't `el-linear` (e.g. `gh`, `glab`, `kubectl`), prefer `jq` fo
 
 `--format summary` is implemented for:
 
-- **Single resources:** `issues read`, `projects read`, `cycles read`, `project-milestones read`, `documents read`, `templates read`, releases (`graphql` query results), `users read`
+- **Single resources:** `issues read`, `comments read`, `projects read`, `cycles read`, `project-milestones read`, `documents read`, `templates read`, releases (`graphql` query results), `users read`
 - **Lists:** `issues list`, `issues search`, `projects list`, `comments list`, `cycles list`, `project-milestones list`, `labels list`, `teams list`, `users list`, `documents list`, `templates list`, `attachments list`, `releases list`, and the cross-resource `search` command
 
 Commands without a dedicated formatter (e.g. `config show`, custom `graphql` queries) fall back to a generic key/value rendering of their JSON payload.

package/claude-skills/linear-operations/evals/evals.json

@@ -10,6 +10,28 @@
 				"Selects labels from the known label taxonomy (e.g., bug)",
 				"Description includes a 'Why we need this' section",
 				"Uses el-linear CLI to create the issue, not raw curl"
+			],
+			"assertions": [
+				{
+					"type": "skill_used",
+					"name": "linear-operations",
+					"description": "Issue creation must route through the Linear operations skill."
+				},
+				{
+					"type": "command_matches",
+					"pattern": "el-linear\\s+issues?\\s+search",
+					"description": "Duplicate checking runs before creating the issue."
+				},
+				{
+					"type": "command_matches",
+					"pattern": "el-linear\\s+issues?\\s+create",
+					"description": "The issue is created through el-linear."
+				},
+				{
+					"type": "output_contains",
+					"value": "Why we need this",
+					"description": "The issue body includes the required intent section."
+				}
 			]
 		},
 		{
@@ -20,6 +42,23 @@
 				"Uses el-linear search command with appropriate query",
 				"Does not attempt to use curl against api.linear.app",
 				"Returns formatted results with issue IDs and titles"
+			],
+			"assertions": [
+				{
+					"type": "skill_used",
+					"name": "linear-operations",
+					"description": "Linear search should use the Linear operations skill."
+				},
+				{
+					"type": "command_matches",
+					"pattern": "el-linear\\s+issues?\\s+search\\s+.*auth",
+					"description": "Searches Linear with the requested auth query."
+				},
+				{
+					"type": "output_not_contains",
+					"value": "api.linear.app",
+					"description": "Does not bypass el-linear with raw Linear API calls."
+				}
 			]
 		},
 		{
@@ -30,6 +69,23 @@
 				"Uses el-linear update command with the issue identifier DEV-123",
 				"Sets the status to In Progress",
 				"Does not create a new issue"
+			],
+			"assertions": [
+				{
+					"type": "skill_used",
+					"name": "linear-operations",
+					"description": "Issue mutation should use the Linear operations skill."
+				},
+				{
+					"type": "command_matches",
+					"pattern": "el-linear\\s+issues?\\s+update\\s+DEV-123\\b.*--status\\s+['\\\"]?In Progress",
+					"description": "Updates DEV-123 to In Progress through el-linear."
+				},
+				{
+					"type": "command_matches",
+					"pattern": "el-linear\\s+issues?\\s+read\\s+DEV-123",
+					"description": "Reads the existing issue before mutation."
+				}
 			]
 		},
 		{
@@ -40,6 +96,33 @@
 				"Does NOT trigger linear-operations skill",
 				"Routes to git-branch-from-linear instead",
 				"No el-linear create or update commands are issued"
+			],
+			"assertions": [
+				{
+					"type": "skill_not_used",
+					"name": "linear-operations",
+					"description": "Branch creation is outside linear-operations scope."
+				},
+				{
+					"type": "skill_used",
+					"name": "git-branch-from-linear",
+					"description": "Branch creation should route to the branch skill."
+				},
+				{
+					"type": "command_matches",
+					"pattern": "el-linear\\s+issues?\\s+read\\s+DEV-456",
+					"description": "Reading issue metadata is allowed for branch creation."
+				},
+				{
+					"type": "output_not_contains",
+					"value": "el-linear issues create",
+					"description": "Does not create a new issue for branch creation."
+				},
+				{
+					"type": "output_not_contains",
+					"value": "el-linear issues update",
+					"description": "Does not update issue fields for branch creation."
+				}
 			]
 		}
 	]

package/dist/commands/comments.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolveUserDisplayName } from "../config/resolver.js";
-import { CREATE_COMMENT_MUTATION, DELETE_COMMENT_MUTATION, LIST_COMMENTS_QUERY, UPDATE_COMMENT_MUTATION, } from "../queries/comments.js";
+import { CREATE_COMMENT_MUTATION, DELETE_COMMENT_MUTATION, GET_COMMENT_QUERY, LIST_COMMENTS_QUERY, UPDATE_COMMENT_MUTATION, } from "../queries/comments.js";
 import { autoLinkReferences, } from "../utils/auto-link-references.js";
 import { applyFooter } from "../utils/footer.js";
 import { createGraphQLService, } from "../utils/graphql-service.js";
@@ -9,7 +9,7 @@ import { wrapIssueReferencesAsLinks } from "../utils/issue-reference-wrapper.js"
 import { createLinearService, } from "../utils/linear-service.js";
 import { logger } from "../utils/logger.js";
 import { resolveMentions, } from "../utils/mention-resolver.js";
-import { getQuietMode, handleAsyncCommand, outputSuccess, } from "../utils/output.js";
+import { getOutputFormat, getQuietMode, handleAsyncCommand, outputSuccess, } from "../utils/output.js";
 import { getRootOpts } from "../utils/root-opts.js";
 import { validateReferences } from "../utils/validate-references.js";
 import { parsePositiveInt } from "../utils/validators.js";
@@ -18,6 +18,8 @@ import { getWorkspaceUrlKey } from "../utils/workspace-url.js";
 // tweak on their side doesn't silently regress the fallback path.
 const BODY_DATA_ERROR_RE = /prosemirror|bodydata|invalid.*body/i;
 const ISSUE_IDENTIFIER_REGEX = /^[A-Z][A-Z0-9]*-\d+$/;
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const COMMENT_ANCHOR_REGEX = /(?:^|[#/])comment-([A-Za-z0-9-]+)/;
 /**
  * Turn a {@link MentionReport} into the `mentions` output field, or `undefined`
  * when there is nothing to report. `delivered=false` records a bodyData→plain
@@ -90,10 +92,11 @@ async function fetchSelfUserId(graphQLService) {
         return;
     }
 }
-function transformComment(comment) {
+function transformComment(comment, options = {}) {
     return {
         id: comment.id,
         body: comment.body,
+        url: comment.url ?? undefined,
         user: {
             id: comment.user.id,
             name: resolveUserDisplayName(comment.user.id, comment.user.name),
@@ -101,8 +104,35 @@ function transformComment(comment) {
         },
         createdAt: comment.createdAt,
         updatedAt: comment.updatedAt,
+        ...(options.fullBodySummary ? { _summaryFullBody: true } : {}),
     };
 }
+function normalizeCommentRef(input) {
+    const trimmed = input.trim();
+    const anchorMatch = COMMENT_ANCHOR_REGEX.exec(trimmed);
+    const candidate = anchorMatch?.[1] ?? trimmed.replace(/^#?comment-/, "");
+    if (UUID_REGEX.test(candidate)) {
+        return { id: candidate.toLowerCase() };
+    }
+    return { hash: candidate };
+}
+function printRawCommentBody(comment, label) {
+    const body = typeof comment.body === "string" ? comment.body : "";
+    if (body.trim() === "") {
+        process.stderr.write(`el-linear: comment ${label} has no body\n`);
+        process.exit(1);
+    }
+    process.stdout.write(`${body}\n`);
+}
+function formatCommentBodyBlocks(comments) {
+    return comments
+        .map((comment) => {
+        const id = typeof comment.id === "string" ? comment.id : "-";
+        const body = typeof comment.body === "string" ? comment.body : "";
+        return `comment ${id}\n\n${body}`;
+    })
+        .join("\n\n---\n\n");
+}
 /**
  * Wrap valid issue references in a comment body as markdown links — same logic as for
  * issue descriptions. Returns the rewritten body plus the validated identifier→UUID map
@@ -324,7 +354,12 @@ async function handleListComments(issueId, options, command) {
     if (!result.issue) {
         throw new Error(`Issue "${issueId}" not found`);
     }
-    const nodes = result.issue.comments.nodes.map(transformComment);
+    const fullBodySummary = options.truncate === false && getOutputFormat() === "summary";
+    const nodes = result.issue.comments.nodes.map((comment) => transformComment(comment, { fullBodySummary }));
+    if (options.body === true) {
+        process.stdout.write(`${formatCommentBodyBlocks(nodes)}\n`);
+        return;
+    }
     outputSuccess({
         data: nodes,
         meta: {
@@ -333,6 +368,23 @@ async function handleListComments(issueId, options, command) {
         },
     });
 }
+async function handleReadComment(commentRef, options, command) {
+    const rootOpts = getRootOpts(command);
+    const graphQLService = await createGraphQLService(rootOpts);
+    const ref = normalizeCommentRef(commentRef);
+    const result = await graphQLService.rawRequest(GET_COMMENT_QUERY, ref);
+    if (!result.comment) {
+        throw new Error(`Comment "${commentRef}" not found`);
+    }
+    const comment = transformComment(result.comment, {
+        fullBodySummary: getOutputFormat() === "summary",
+    });
+    if (options.body === true) {
+        printRawCommentBody(comment, commentRef);
+        return;
+    }
+    outputSuccess(comment);
+}
 async function handleDeleteComment(commentId, _options, command) {
     const rootOpts = getRootOpts(command);
     const graphQLService = await createGraphQLService(rootOpts);
@@ -374,7 +426,18 @@ export function setupCommentsCommands(program) {
         .description("List comments on an issue.")
         .addHelpText("after", "\nBoth UUID and identifiers like ABC-123 are supported.")
         .option("-l, --limit <number>", "limit results", "25")
+        .option("--body", "print complete comment bodies as plain text blocks instead of JSON")
+        .option("--no-truncate", "do not truncate comment bodies in --format summary output")
         .action(handleAsyncCommand(handleListComments));
+    comments
+        .command("read <commentId>")
+        .alias("get")
+        .alias("show")
+        .description("Read a comment by id or Linear #comment-<hash> anchor.")
+        .addHelpText("after", "\nAccepts a full comment UUID, a comment-<hash> token, or a URL containing #comment-<hash>.")
+        .option("--body", "print the raw comment body with no JSON envelope")
+        .option("-q, --quiet", "print one confirmation line (comment <id>) instead of the full JSON")
+        .action(handleAsyncCommand(handleReadComment));
     comments
         .command("delete <commentId>")
         .alias("remove")

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

@@ -21,6 +21,7 @@ interface CommentUserRef {
 export interface CommentResourceNode {
     id: string;
     body: string;
+    url?: string | null;
     createdAt: string;
     updatedAt: string;
     user: CommentUserRef;
@@ -31,6 +32,12 @@ interface UpdatedCommentResourceNode extends CommentResourceNode {
         identifier: string;
     } | null;
 }
+interface ReadCommentResourceNode extends CommentResourceNode {
+    issue: {
+        id: string;
+        identifier: string;
+    } | null;
+}
 export interface ListCommentsResponse {
     issue: {
         id: string;
@@ -40,6 +47,9 @@ export interface ListCommentsResponse {
         };
     } | null;
 }
+export interface GetCommentResponse {
+    comment: ReadCommentResourceNode | null;
+}
 export interface CreateCommentResponse {
     commentCreate: {
         success: boolean;

package/dist/queries/comments.d.ts

@@ -1,4 +1,5 @@
 export declare const LIST_COMMENTS_QUERY = "\n  query ListComments($issueId: String!, $first: Int) {\n    issue(id: $issueId) {\n      id\n      identifier\n      comments(first: $first, orderBy: createdAt) {\n        nodes {\n          id\n          body\n          createdAt\n          updatedAt\n          user {\n            id\n            name\n            displayName\n            url\n          }\n        }\n      }\n    }\n  }\n";
+export declare const GET_COMMENT_QUERY = "\n  query GetComment($id: String, $hash: String) {\n    comment(id: $id, hash: $hash) {\n      id\n      body\n      url\n      createdAt\n      updatedAt\n      user {\n        id\n        name\n        displayName\n        url\n      }\n      issue {\n        id\n        identifier\n      }\n    }\n  }\n";
 export declare const CREATE_COMMENT_MUTATION = "\n  mutation CreateComment($input: CommentCreateInput!) {\n    commentCreate(input: $input) {\n      success\n      comment {\n        id\n        body\n        createdAt\n        updatedAt\n        user {\n          id\n          name\n          displayName\n          url\n        }\n      }\n    }\n  }\n";
 export declare const UPDATE_COMMENT_MUTATION = "\n  mutation UpdateComment($id: String!, $input: CommentUpdateInput!) {\n    commentUpdate(id: $id, input: $input) {\n      success\n      comment {\n        id\n        body\n        createdAt\n        updatedAt\n        user {\n          id\n          name\n          displayName\n          url\n        }\n        issue {\n          id\n          identifier\n        }\n      }\n    }\n  }\n";
 export declare const DELETE_COMMENT_MUTATION = "\n  mutation DeleteComment($id: String!) {\n    commentDelete(id: $id) {\n      success\n    }\n  }\n";

package/dist/queries/comments.js

@@ -20,6 +20,27 @@ export const LIST_COMMENTS_QUERY = `
     }
   }
 `;
+export const GET_COMMENT_QUERY = `
+  query GetComment($id: String, $hash: String) {
+    comment(id: $id, hash: $hash) {
+      id
+      body
+      url
+      createdAt
+      updatedAt
+      user {
+        id
+        name
+        displayName
+        url
+      }
+      issue {
+        id
+        identifier
+      }
+    }
+  }
+`;
 export const CREATE_COMMENT_MUTATION = `
   mutation CreateComment($input: CommentCreateInput!) {
     commentCreate(input: $input) {

package/dist/utils/formatters/summary.js

@@ -567,8 +567,10 @@ export function formatProjectList(projects, fields) {
 export function formatCommentSummary(comment) {
     const author = getName(comment.user);
     const createdAt = s(comment.createdAt);
-    const body = clipDescription(comment.body);
-    const headerLine = `${author}  ${createdAt}`;
+    const body = comment._summaryFullBody === true
+        ? s(comment.body)
+        : clipDescription(comment.body);
+    const headerLine = `comment ${s(comment.id)}  ${author}  ${createdAt}`;
     const parts = [headerLine];
     if (body)
         parts.push("", body);

package/package.json

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