From 4b6f99907b128f57d291ca3275fa1346ed954602 Mon Sep 17 00:00:00 2001 From: Peter Schilling Date: Tue, 15 Sep 2026 11:16:44 -0700 Subject: [PATCH] Document that Linear archives issues automatically issue archive (#285) exposes an action Linear's own product hides. Linear's docs state that archiving happens automatically with no option to manually archive items, and the 2021 changelog explains the manual option was removed because most people used the archive as a trash can: the archive is Linear's to manage, deleting is the user's choice. The official Linear MCP server exposes no archive tool either. Nothing in our help or skill said any of this, so an agent reading the command list would treat archive as a normal way to retire an issue. The command's help, docs/usage.md, the README line, and the skill template now say to prefer closing or deleting, quote and link the Linear docs, and note the two practical hazards of calling issueArchive directly: it skips auto-archive's checks for open parents, sub-issues, cycles, and projects, and archived issues drop out of list, query, and search unless --include-archived is passed. The generated skill reference and help snapshot follow from the new description. --- CHANGELOG.md | 4 ++++ README.md | 2 +- docs/usage.md | 4 ++++ skills/linear-cli/SKILL.md | 10 ++++++++++ skills/linear-cli/SKILL.template.md | 10 ++++++++++ skills/linear-cli/references/issue.md | 7 ++++++- src/commands/issue/issue-archive.ts | 6 +++++- .../issue/__snapshots__/issue-archive.test.ts.snap | 11 ++++++++--- 8 files changed, 48 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3dcb769d..0f96695e 100644 --- a/CHANGELOG.md +++ b/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 ` 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)) diff --git a/README.md b/README.md index 85f0184e..21eff0d7 100644 --- a/README.md +++ b/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 diff --git a/docs/usage.md b/docs/usage.md index d731e460..702b87ae 100644 --- a/docs/usage.md +++ b/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 diff --git a/skills/linear-cli/SKILL.md b/skills/linear-cli/SKILL.md index 2872a2f5..70065b0b 100644 --- a/skills/linear-cli/SKILL.md +++ b/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: diff --git a/skills/linear-cli/SKILL.template.md b/skills/linear-cli/SKILL.template.md index 98400153..3374a637 100644 --- a/skills/linear-cli/SKILL.template.md +++ b/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: diff --git a/skills/linear-cli/references/issue.md b/skills/linear-cli/references/issue.md index 55891413..7ef7813f 100644 --- a/skills/linear-cli/references/issue.md +++ b/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: diff --git a/src/commands/issue/issue-archive.ts b/src/commands/issue/issue-archive.ts index 0b287882..7a325c15 100644 --- a/src/commands/issue/issue-archive.ts +++ b/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( diff --git a/test/commands/issue/__snapshots__/issue-archive.test.ts.snap b/test/commands/issue/__snapshots__/issue-archive.test.ts.snap index 7553447e..9d0bc1ec 100644 --- a/test/commands/issue/__snapshots__/issue-archive.test.ts.snap +++ b/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 - Read issue identifiers from a file (one per line) --bulk-stdin - Read issue identifiers from stdin -" +' stderr: "" `;