Add document, project, and initiative comments with threaded replies

CHANGELOG.md

@@ -4,13 +4,15 @@
 
 ### Added
 
+- `document comment list|add`, `project comment list|add`, and `initiative comment list|add`, mirroring `issue comment`. Documents take a UUID or slug, projects and initiatives a UUID, slug, or name; `add` takes `--body` or `--body-file`. Every comment `add`, including `issue comment add`, now takes `--reply-to <commentId>` to answer in a thread (`-p`/`--parent` remain aliases). Comment lists now fetch every page instead of stopping at 50, and their `--json` nodes, plus the comments in `issue view --json`, carry `quotedText` (the passage an inline comment is anchored to) alongside `parent.id` ([#230](https://github.com/schpet/linear-cli/issues/230))
 - every command that takes a team now accepts its key, name, or UUID, resolved through one shared lookup: `team states`, `team members`, `team delete`, `label list/create/delete --team`, `cycle list/view --team`, `project list/create/update --team`, `document list/create/update --team`, and `issue query/mine/create/update --team`. Keys stay canonical and win over a same-spelled name; an unknown team errors with the list of valid keys instead of an empty result or a raw API error. Previously only keys worked, which is why [#276](https://github.com/schpet/linear-cli/issues/276) asked for `team list --json` as a name-to-key lookup
 - `issue query --state` and `issue mine --state` accept a workflow state name or ID as well as the six state types, looked up within the queried team scope (all teams under `--all-teams`, where a name matches every team's same-named state). An unknown name errors and lists the scope's states, and types and names can be mixed
 - `project update --content <markdown>` and `--content-file <path>` replace a project's long-form overview body, matching the flags `project create` already had. Previously the only way to change the body after creation was a hand-written `projectUpdate` mutation through `linear api`
 - `--json` (`-j`) on `team list`, `cycle list`, `cycle view`, `milestone list`, `milestone view`, and `project view`, the last read commands without machine-readable output. List commands emit the same `{ nodes, pageInfo }` connection shape as the other list commands, after the same filtering and ordering as the table; view commands emit the GraphQL object as fetched, including every issue rather than the ten-item preview, and `milestone view --all --json` includes every page. (A 2.0.0 entry claimed `cycle list --json`; that change never actually landed.) ([#276](https://github.com/schpet/linear-cli/issues/276); thanks @lakardion)
 
 ### Fixed
 
+- an unknown document, project, initiative, or issue passed to `document view` or any `comment` command is reported as `<Type> not found: <reference>` instead of Linear's raw "Could not find referenced …" wording, and `document view` no longer exits with a stack trace for an unknown slug (its not-found branch re-threw instead of reporting, and was unreachable until the not-found detection was fixed)
 - `cycle list` and `milestone list` now paginate instead of taking Linear's default page, so a team with more than 50 cycles or a project with more than 50 milestones is no longer silently truncated
 
 ## [2.6.0] - 2026-09-02

README.md

@@ -148,7 +148,8 @@ linear issue update ENG-123 --milestone "Phase 2"  # set milestone on existing i
 linear issue delete    # delete an issue
 linear issue comment list          # list comments on current issue
 linear issue comment add           # add a comment to current issue
-linear issue comment add -p <id>   # reply to a specific comment
+linear issue comment add --reply-to <id>   # reply to a comment (-p / --parent are aliases)
+linear issue comment list --json   # comments as JSON, with quotedText and parent for inline comments and replies
 linear issue comment update <id>   # update a comment
 linear issue commits               # show all commits for an issue (jj only)
 ```
@@ -201,6 +202,19 @@ linear project view <projectId> --json  # project details as JSON
 linear project create --name "API v2" --team ENG --content-file overview.md
 linear project create --name "Mobile launch" --team APP --priority high --label Launch --member jane@example.com
 linear project update <projectId> --content-file overview.md  # replace the project's overview body
+linear project comment list <project>                         # list the project's discussion thread (UUID, slug, or name)
+linear project comment add <project> --body "Kickoff Monday"  # comment on a project
+linear project comment add <project> --body "+1" --reply-to <commentId>  # reply in a thread
+```
+
+### initiative commands
+
+```bash
+linear initiative list                                            # list initiatives
+linear initiative view <initiative>                               # view an initiative (UUID, slug, or name)
+linear initiative comment list <initiative>                       # list the initiative's discussion thread
+linear initiative comment add <initiative> --body-file note.md   # comment on an initiative
+linear initiative comment add <initiative> --body "+1" --reply-to <commentId>  # reply in a thread
 ```
 
 ### cycle commands
@@ -251,6 +265,12 @@ linear document view <slug> --raw               # output raw markdown (for pipin
 linear document view <slug> --web               # open in browser
 linear document view <slug> --json              # output as JSON, including document comments
 
+# comment on a document
+linear document comment list <slug>             # list comments; inline comments show the text they quote
+linear document comment list <slug> --json      # comments as JSON (quotedText, parent, ...)
+linear document comment add <slug> --body "Looks good"              # add a top-level comment
+linear document comment add <slug> --body-file note.md --reply-to <commentId>  # reply in a thread
+
 # create a document (exactly one attachment target is required)
 linear document create --title "Doc" --project <project>              # attach to project
 linear document create --title "Notes" --issue TC-123                 # attach to issue

docs/usage.md

@@ -213,6 +213,21 @@ delete an issue:
 linear issue delete TEAM-123
 ```
 
+#### issue comments
+
+```bash
+# List comments (threads, newest first); --json keeps the GraphQL connection
+linear issue comment list TEAM-123
+linear issue comment list TEAM-123 --json
+
+# Add a comment; --body-file is preferred for markdown
+linear issue comment add TEAM-123 --body "Reproduced on staging"
+linear issue comment add TEAM-123 --body-file notes.md
+
+# Reply to a top-level comment (-p / --parent are aliases of --reply-to)
+linear issue comment add TEAM-123 --body "Fixed in #42" --reply-to COMMENT-ID
+```
+
 ### teams
 
 wherever a command takes a team, pass its key, its name, or its UUID. keys are canonical; an unknown team errors and lists the valid keys.
@@ -299,6 +314,31 @@ linear project view PROJECT-ID
 linear project view PROJECT-ID --json
 ```
 
+#### project comments
+
+```bash
+# A project is a UUID, slug ID, or exact name
+linear project comment list "Mobile launch"
+linear project comment list PROJECT-ID --json
+
+linear project comment add PROJECT-ID --body "Kickoff is Monday"
+linear project comment add PROJECT-ID --body-file update.md --reply-to COMMENT-ID
+```
+
+### documents and initiatives
+
+Documents and initiatives take the same `comment list` and `comment add` subcommands as issues and projects. A document is a UUID or slug; an initiative is a UUID, slug, or name.
+
+```bash
+linear document comment list DOC-SLUG          # inline comments show the text they quote
+linear document comment list DOC-SLUG --json   # quotedText and parent are in the JSON
+linear document comment add DOC-SLUG --body-file review.md
+linear document comment add DOC-SLUG --body "Agreed" --reply-to COMMENT-ID
+
+linear initiative comment list "Platform"
+linear initiative comment add "Platform" --body "Scope locked for Q3"
+```
+
 ### shell completions
 
 generate shell completions for better command-line experience:

skills/linear-cli/SKILL.md

@@ -182,6 +182,9 @@ linear cycle list
 linear cycle view
 
 linear document
+linear document comment
+linear document comment add
+linear document comment list
 linear document create
 linear document delete
 linear document list
@@ -191,6 +194,9 @@ linear document view
 linear initiative
 linear initiative add-project
 linear initiative archive
+linear initiative comment
+linear initiative comment add
+linear initiative comment list
 linear initiative create
 linear initiative delete
 linear initiative list
@@ -247,6 +253,9 @@ linear milestone update
 linear milestone view
 
 linear project
+linear project comment
+linear project comment add
+linear project comment list
 linear project create
 linear project delete
 linear project list

skills/linear-cli/references/document.md

@@ -23,10 +23,74 @@ Commands:
   create, c                - Create a new document             
   update, u  <documentId>  - Update an existing document       
   delete, d  [documentId]  - Delete a document (moves to trash)
+  comment                  - Manage document comments
 ```
 
 ## Subcommands
 
+### comment
+
+> Manage document comments
+
+```
+Usage:   linear document comment
+
+Description:
+
+  Manage document comments
+
+Options:
+
+  -h, --help           - Show this help.                      
+  --workspace  <slug>  - Target workspace (uses credentials)  
+
+Commands:
+
+  add   <document>  - Add a comment or reply to a document (by ID or slug)
+  list  <document>  - List comments on a document (by ID or slug)
+```
+
+#### comment subcommands
+
+##### add
+
+```
+Usage:   linear document comment add <document>
+
+Description:
+
+  Add a comment or reply to a document (by ID or slug)                            
+
+  Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,  
+  and `[Name](url)` do not. Get a person's URL from the `url` field of            
+  `linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
+  Run `linear markdown` for collapsible sections and the full reference.          
+
+Options:
+
+  -h, --help                             - Show this help.                                                   
+  --workspace               <slug>       - Target workspace (uses credentials)                               
+  -b, --body                <text>       - Comment body text                                                 
+  --body-file               <path>       - Read comment body from a file (preferred for markdown content)    
+  -p, --parent, --reply-to  <commentId>  - Reply to a top-level comment by ID (the reply joins that thread)
+```
+
+##### list
+
+```
+Usage:   linear document comment list <document>
+
+Description:
+
+  List comments on a document (by ID or slug)
+
+Options:
+
+  -h, --help           - Show this help.                      
+  --workspace  <slug>  - Target workspace (uses credentials)  
+  -j, --json           - Output as JSON
+```
+
 ### create
 
 > Create a new document

skills/linear-cli/references/initiative.md

@@ -26,7 +26,8 @@ Commands:
   unarchive       <initiativeId>          - Unarchive a Linear initiative         
   delete          [initiativeId]          - Permanently delete a Linear initiative
   add-project     <initiative> <project>  - Link a project to an initiative       
-  remove-project  <initiative> <project>  - Unlink a project from an initiative
+  remove-project  <initiative> <project>  - Unlink a project from an initiative   
+  comment                                 - Manage initiative comments
 ```
 
 ## Subcommands
@@ -70,6 +71,69 @@ Options:
   --bulk-stdin            - Read initiative IDs from stdin
 ```
 
+### comment
+
+> Manage initiative comments
+
+```
+Usage:   linear initiative comment
+
+Description:
+
+  Manage initiative comments
+
+Options:
+
+  -h, --help           - Show this help.                      
+  --workspace  <slug>  - Target workspace (uses credentials)  
+
+Commands:
+
+  add   <initiative>  - Add a comment or reply to an initiative's discussion (by ID, slug, or name)
+  list  <initiative>  - List comments on an initiative (by ID, slug, or name)
+```
+
+#### comment subcommands
+
+##### add
+
+```
+Usage:   linear initiative comment add <initiative>
+
+Description:
+
+  Add a comment or reply to an initiative's discussion (by ID, slug, or name)     
+
+  Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,  
+  and `[Name](url)` do not. Get a person's URL from the `url` field of            
+  `linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
+  Run `linear markdown` for collapsible sections and the full reference.          
+
+Options:
+
+  -h, --help                             - Show this help.                                                   
+  --workspace               <slug>       - Target workspace (uses credentials)                               
+  -b, --body                <text>       - Comment body text                                                 
+  --body-file               <path>       - Read comment body from a file (preferred for markdown content)    
+  -p, --parent, --reply-to  <commentId>  - Reply to a top-level comment by ID (the reply joins that thread)
+```
+
+##### list
+
+```
+Usage:   linear initiative comment list <initiative>
+
+Description:
+
+  List comments on an initiative (by ID, slug, or name)
+
+Options:
+
+  -h, --help           - Show this help.                      
+  --workspace  <slug>  - Target workspace (uses credentials)  
+  -j, --json           - Output as JSON
+```
+
 ### create
 
 > Create a new Linear initiative

skills/linear-cli/references/issue.md

@@ -161,15 +161,15 @@ Description:
 
 Options:
 
-  -h, --help                - Show this help.                                                                
-  --workspace   <slug>      - Target workspace (uses credentials)                                            
-  -b, --body    <text>      - Comment body text                                                              
-  --body-file   <path>      - Read comment body from a file (preferred for markdown content)                 
-  -p, --parent  <id>        - Parent comment ID for replies                                                  
-  -a, --attach  <filepath>  - Upload a file and add its Markdown link to the comment (images render inline;  
-                              repeatable)                                                                    
-  --public                  - Upload attached images to a public, unauthenticated URL (default: private,     
-                              workspace-members only)
+  -h, --help                             - Show this help.                                                                
+  --workspace               <slug>       - Target workspace (uses credentials)                                            
+  -b, --body                <text>       - Comment body text                                                              
+  --body-file               <path>       - Read comment body from a file (preferred for markdown content)                 
+  -p, --parent, --reply-to  <commentId>  - Reply to a top-level comment by ID (the reply joins that thread)               
+  -a, --attach              <filepath>   - Upload a file and add its Markdown link to the comment (images render inline;  
+                                           repeatable)                                                                    
+  --public                               - Upload attached images to a public, unauthenticated URL (default: private,     
+                                           workspace-members only)
 ```
 
 ##### delete

skills/linear-cli/references/project.md

@@ -23,10 +23,74 @@ Commands:
   create                - Create a new Linear project    
   update   <projectId>  - Update a Linear project        
   delete   <projectId>  - Delete (trash) a Linear project
+  comment               - Manage project comments
 ```
 
 ## Subcommands
 
+### comment
+
+> Manage project comments
+
+```
+Usage:   linear project comment
+
+Description:
+
+  Manage project comments
+
+Options:
+
+  -h, --help           - Show this help.                      
+  --workspace  <slug>  - Target workspace (uses credentials)  
+
+Commands:
+
+  add   <project>  - Add a comment or reply to a project's discussion (by ID, slug, or name)
+  list  <project>  - List comments on a project (by ID, slug, or name)
+```
+
+#### comment subcommands
+
+##### add
+
+```
+Usage:   linear project comment add <project>
+
+Description:
+
+  Add a comment or reply to a project's discussion (by ID, slug, or name)         
+
+  Linear Markdown: a plain Linear URL creates a mention; `@name`, `@[Name](id)`,  
+  and `[Name](url)` do not. Get a person's URL from the `url` field of            
+  `linear team members <TEAM> --json`, or an issue's from `linear issue url <ID>`.
+  Run `linear markdown` for collapsible sections and the full reference.          
+
+Options:
+
+  -h, --help                             - Show this help.                                                   
+  --workspace               <slug>       - Target workspace (uses credentials)                               
+  -b, --body                <text>       - Comment body text                                                 
+  --body-file               <path>       - Read comment body from a file (preferred for markdown content)    
+  -p, --parent, --reply-to  <commentId>  - Reply to a top-level comment by ID (the reply joins that thread)
+```
+
+##### list
+
+```
+Usage:   linear project comment list <project>
+
+Description:
+
+  List comments on a project (by ID, slug, or name)
+
+Options:
+
+  -h, --help           - Show this help.                      
+  --workspace  <slug>  - Target workspace (uses credentials)  
+  -j, --json           - Output as JSON
+```
+
 ### create
 
 > Create a new Linear project