Document that Linear archives issues automatically

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Changed
+
+- `issue archive` help, `docs/usage.md`, the README, and the linear-cli skill now explain that Linear archives closed issues automatically and offers no manual archive in its app or official MCP server, quoting and linking Linear's docs, so the command reads as an escape hatch rather than the normal way to retire an issue
+
 ### Added
 
 - `issue archive <id>` archives an issue through Linear's `issueArchive` mutation, distinct from `issue delete`, which trashes it. It resolves identifiers like the other issue commands, prompts with the identifier and title unless `--confirm`/`-y` is passed, reports an already-archived issue instead of silently succeeding, and takes `--bulk`, `--bulk-file`, and `--bulk-stdin` like `issue delete` ([#285](https://github.com/schpet/linear-cli/pull/285); thanks @martin-piliar for the command and the report in [#284](https://github.com/schpet/linear-cli/issues/284))

README.md

@@ -147,7 +147,7 @@ linear issue create --template "Bug report" -t "Login fails"  # create from a te
 linear issue update    # update an issue (interactive prompts)
 linear issue update ENG-123 --milestone "Phase 2"  # set milestone on existing issue
 linear issue update ENG-123 --clear-due-date --clear-parent  # remove values (also --clear-estimate, --clear-project, --clear-milestone, --clear-cycle, --unassign)
-linear issue archive ENG-123 --confirm  # archive an issue
+linear issue archive ENG-123 --confirm  # archive an issue (Linear normally auto-archives closed issues; see docs/usage.md)
 linear issue archive --confirm --bulk ENG-123 ENG-124  # archive several issues
 linear issue delete    # delete an issue
 linear issue comment list          # list comments on current issue

docs/usage.md

@@ -250,6 +250,10 @@ linear issue archive TEAM-123 --confirm
 linear issue archive --confirm --bulk TEAM-123 TEAM-124   # several at once; --bulk-file and --bulk-stdin also work
 ```
 
+Archiving is normally something Linear does for you, not something you do by hand. Linear's [delete and archive issues](https://linear.app/docs/delete-archive-issues) docs state that "archiving happens automatically with no option to manually archive items": closed issues are auto-archived after the period set in Team settings, and the manual action Linear offers is delete, which keeps the issue in the trash for 30 days. Linear removed manual archiving from its app in 2021 because "most users used the archive as a trash can", reasoning that "the archive is something that Linear should manage for you while deleting issues is your own choice" ([changelog](https://linear.app/changelog/2021-04-15-auto-archive-cycles-and-projects-and-deleting-issues)). Its official MCP server has no archive tool either.
+
+`issue archive` calls the `issueArchive` mutation directly, so it skips the checks auto-archive applies (open parent, open sub-issues, active cycle or project), and archived issues disappear from `issue list`, `issue query`, and search unless you pass `--include-archived`. Reach for it only when an issue should leave the active workspace without being canceled or trashed; otherwise close it with `issue update --state` or remove it with `issue delete`. Archived issues can be restored from the team's archives page in Linear.
+
 #### issue comments
 
 ```bash

skills/linear-cli/SKILL.md

@@ -100,6 +100,16 @@ linear issue view ENG-123 --json   # structured output
 linear issue url ENG-123           # print just the URL
 ```
 
+### Close, delete, or archive an issue
+
+```bash
+linear issue update ENG-123 --state Done       # or Canceled; Linear auto-archives closed issues later
+linear issue delete ENG-123                    # trash; restorable in Linear for 30 days
+linear issue archive ENG-123 --confirm         # rarely appropriate, see below
+```
+
+Prefer closing or deleting over archiving. Linear's docs say "archiving happens automatically with no option to manually archive items" (https://linear.app/docs/delete-archive-issues): closed issues are auto-archived after the team's configured period, and Linear removed manual archiving from its app because people used it as a trash can. `issue archive` calls the `issueArchive` mutation directly, bypassing auto-archive's checks for open parents, sub-issues, cycles, and projects, and archived issues vanish from `issue list`, `issue query`, and search unless `--include-archived` is passed. Only archive when the user explicitly asks for it.
+
 ## Best Practices for Markdown Content
 
 When working with issue descriptions or comment bodies that contain markdown, **always prefer using file-based flags** instead of passing content as command-line arguments:

skills/linear-cli/SKILL.template.md

@@ -100,6 +100,16 @@ linear issue view ENG-123 --json   # structured output
 linear issue url ENG-123           # print just the URL
 ```
 
+### Close, delete, or archive an issue
+
+```bash
+linear issue update ENG-123 --state Done       # or Canceled; Linear auto-archives closed issues later
+linear issue delete ENG-123                    # trash; restorable in Linear for 30 days
+linear issue archive ENG-123 --confirm         # rarely appropriate, see below
+```
+
+Prefer closing or deleting over archiving. Linear's docs say "archiving happens automatically with no option to manually archive items" (https://linear.app/docs/delete-archive-issues): closed issues are auto-archived after the team's configured period, and Linear removed manual archiving from its app because people used it as a trash can. `issue archive` calls the `issueArchive` mutation directly, bypassing auto-archive's checks for open parents, sub-issues, cycles, and projects, and archived issues vanish from `issue list`, `issue query`, and search unless `--include-archived` is passed. Only archive when the user explicitly asks for it.
+
 ## Best Practices for Markdown Content
 
 When working with issue descriptions or comment bodies that contain markdown, **always prefer using file-based flags** instead of passing content as command-line arguments:

skills/linear-cli/references/issue.md

@@ -108,7 +108,12 @@ Usage:   linear issue archive [issueId]
 
 Description:
 
-  Archive an issue
+  Archive an issue                                                                                                                      
+
+  Linear archives closed issues on its own, and its docs say "archiving happens automatically with no option to manually archive items".
+  Prefer closing (issue update --state) and letting auto-archive run, or issue delete to trash. This command calls the issueArchive     
+  mutation, which the Linear app and its official MCP server do not expose; archived issues drop out of list, query, and search results 
+  unless --include-archived is passed. See https://linear.app/docs/delete-archive-issues                                                
 
 Options:
 

src/commands/issue/issue-archive.ts

@@ -27,7 +27,11 @@ interface IssueArchiveResult extends BulkOperationResult {
 
 export const archiveCommand = new Command()
   .name("archive")
-  .description("Archive an issue")
+  .description(
+    `Archive an issue
+
+Linear archives closed issues on its own, and its docs say "archiving happens automatically with no option to manually archive items". Prefer closing (issue update --state) and letting auto-archive run, or issue delete to trash. This command calls the issueArchive mutation, which the Linear app and its official MCP server do not expose; archived issues drop out of list, query, and search results unless --include-archived is passed. See https://linear.app/docs/delete-archive-issues`,
+  )
   .arguments("[issueId:string]")
   .option("-y, --confirm", "Skip confirmation prompt")
   .option(

test/commands/issue/__snapshots__/issue-archive.test.ts.snap

@@ -2,12 +2,17 @@ export const snapshot = {};
 
 snapshot[`Issue Archive Command - Help Text 1`] = `
 stdout:
-"
+'
 Usage: archive [issueId]
 
 Description:
 
-  Archive an issue
+  Archive an issue                                                                                                                      
+
+  Linear archives closed issues on its own, and its docs say "archiving happens automatically with no option to manually archive items".
+  Prefer closing (issue update --state) and letting auto-archive run, or issue delete to trash. This command calls the issueArchive     
+  mutation, which the Linear app and its official MCP server do not expose; archived issues drop out of list, query, and search results 
+  unless --include-archived is passed. See https://linear.app/docs/delete-archive-issues                                                
 
 Options:
 
@@ -17,7 +22,7 @@ Options:
   --bulk-file    <file>    - Read issue identifiers from a file (one per line)            
   --bulk-stdin             - Read issue identifiers from stdin                            
 
-"
+'
 stderr:
 ""
 `;