@kyaukyuai/linear-cli 2.7.1 → 2.8.1

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [2.8.1] - 2026-03-24
+
+### Added
+
+- added `--dry-run` support to `issue start` so agents and scripts can preview branch naming and target state transitions before mutating Linear or local VCS state
+
+## [2.8.0] - 2026-03-24
+
+### Added
+
+- added a shared `--dry-run` contract and preview output for automation-safe write workflows
+- added `--dry-run` support to issue, project, milestone, document, and webhook write commands
+- added Automation Contract v2 coverage for `project list/view --json`
+- added Automation Contract v2 coverage for `cycle list/view/current/next --json`
+- added Automation Contract v2 coverage for `milestone list/view --json`
+
+### Changed
+
+- structured `issue create-batch --json` partial-failure responses with created identifiers, retry hints, and failure-step metadata for safer retries
+
 ## [2.7.1] - 2026-03-23
 
 ### Added

package/README.md

@@ -100,15 +100,18 @@ compared to upstream, this fork adds and maintains several capabilities aimed at
 - workspace-aware auth management with keyring migration and default workspace support
 - generated AI-agent skill docs, Claude plugin metadata, npm publishing, and Homebrew tap release plumbing
 
-## automation contract v1
+## automation contract
 
 for bot and org-wide automation use cases, `linear-cli` defines a stable JSON contract for a focused automation tier.
 
-- in scope: `issue list/view/create/update --json`, `issue relation add/delete/list --json`, `issue comment add --json`, `team members --json`, `issue parent/children/create-batch --json`
+- v1 in scope: `issue list/view/create/update --json`, `issue relation add/delete/list --json`, `issue comment add --json`, `team members --json`, `issue parent/children/create-batch --json`
+- v2 additions: `project list/view --json`, `cycle list/view/current/next --json`, `milestone list/view --json`
 - out of scope: non-JSON terminal output, `linear api`, and other `--json` commands that are not listed above
 
 the contract fixes top-level success payload shapes and requires machine-readable failure payloads for the automation tier. see [docs/json-contracts.md](docs/json-contracts.md) for the full contract, compatibility rules, and example payloads. that guarantee also covers parser and argument validation failures when `--json` is present.
 
+the same document also defines the shared preview contract for future `--dry-run` write commands. those commands are not all implemented yet, but the contract now fixes the expected `stdout`, `exit code`, and `--json --dry-run` envelope shape ahead of rollout.
+
 ## differences from upstream
 
 this fork is intentionally diverging from upstream in a few ways:
@@ -176,16 +179,20 @@ linear issue list --parent ENG-100 --json  # filter sub-issues of a parent issue
 linear issue list -w   # open issue list in web browser
 linear issue list -a   # open issue list in Linear.app
 linear issue start     # create/switch to issue branch and mark as started
+linear issue start ENG-123 --dry-run  # preview the branch and target state
 linear issue create    # create a new issue (interactive prompts)
 linear issue create -t "title" -d "description"  # create with flags
 linear issue create -t "title" --team ENG --json  # emit machine-readable created issue data
+linear issue create -t "title" --team ENG --dry-run --json  # preview the created issue payload
 linear issue create-batch --file ./issue-batch.json --json  # create a parent issue and child issues from JSON
+linear issue create-batch --file ./issue-batch.json --dry-run --json  # preview a batch without creating issues
 linear issue create --project "My Project" --milestone "Phase 1"  # create with milestone
 linear issue update    # update an issue (interactive prompts)
 linear issue update ENG-123 --due-date 2026-03-31  # set an issue due date
 linear issue update ENG-123 --clear-due-date       # clear an issue due date
 linear issue update ENG-123 --assignee self --json  # emit machine-readable updated issue data
 linear issue update ENG-123 --state started --comment "Work has started"  # update and comment in one command
+linear issue update ENG-123 --state started --comment "Work has started" --dry-run  # preview issue updates
 linear issue update ENG-123 --milestone "Phase 2"  # set milestone on existing issue
 linear issue delete    # delete an issue
 linear issue comment list          # list comments on current issue
@@ -193,8 +200,11 @@ linear issue comment add           # add a comment to current issue
 linear issue comment add ENG-123 "follow-up"  # add a comment with positional body
 linear issue comment add -p <id>   # reply to a specific comment
 linear issue comment add ENG-123 --body "follow-up" --json  # emit created comment data
+linear issue comment add ENG-123 --body "follow-up" --dry-run --json  # preview comment creation
 linear issue relation add ENG-123 blocked-by ENG-100 --json  # emit machine-readable relation creation data
+linear issue relation add ENG-123 blocked-by ENG-100 --dry-run --json  # preview relation creation
 linear issue relation delete ENG-123 blocked-by ENG-100 --json  # emit machine-readable relation deletion data
+linear issue relation delete ENG-123 blocked-by ENG-100 --dry-run --json  # preview relation deletion
 linear issue relation list ENG-123 --json  # emit dependency graph for an issue
 linear issue comment update <id>   # update a comment
 linear issue commits               # show all commits for an issue (jj only)
@@ -220,6 +230,8 @@ linear issue children ENG-123 --json  # emit child issues for decomposition work
 }
 ```
 
+`issue create-batch` creates the parent first and then creates each child in order. If a later child fails, already created issues are not rolled back. Use `--dry-run --json` to preview the plan first. In `--json` mode, partial failures include `error.details.createdIdentifiers` and `error.details.failedStep` so automation can resume from the remaining work instead of rerunning the same batch unchanged.
+
 ### team commands
 
 ```bash
@@ -231,11 +243,26 @@ linear team create     # create a new team
 linear team autolinks  # configure GitHub repository autolinks for Linear issues
 ```
 
+### cycle commands
+
+```bash
+linear cycle list --team ENG
+linear cycle list --team ENG --json  # emit cycle summaries for automation
+linear cycle view "Sprint 42" --team ENG --json  # emit detailed cycle payload
+linear cycle current --team ENG --json  # emit active cycle or null
+linear cycle next --team ENG --json  # emit next cycle or null
+```
+
 ### project commands
 
 ```bash
 linear project list    # list projects
-linear project view    # view project details
+linear project list --json  # emit contract-stable project summaries
+linear project view <projectIdOrSlug>    # view project details
+linear project view <projectIdOrSlug> --json  # emit contract-stable project details
+linear project create --name "Platform Refresh" --team ENG --dry-run --json  # preview a project create
+linear project update <projectIdOrSlug> --name "Platform Refresh" --dry-run  # preview a project update
+linear project delete <projectIdOrSlug> --dry-run  # preview a project deletion
 linear project label add <projectIdOrSlug> <labelNameOrId>     # attach a project label
 linear project label remove <projectIdOrSlug> <labelNameOrId>  # detach a project label
 ```
@@ -244,14 +271,19 @@ linear project label remove <projectIdOrSlug> <labelNameOrId>  # detach a projec
 
 ```bash
 linear milestone list --project <projectId>     # list milestones for a project
+linear milestone list --project <projectId> --json  # emit contract-stable milestone summaries
 linear m list --project <projectId>             # list milestones (alias)
 linear milestone view <milestoneId>             # view milestone details
+linear milestone view <milestoneId> --json      # emit contract-stable milestone details
 linear m view <milestoneId>                     # view milestone (alias)
 linear milestone create --project <projectId> --name "Q1 Goals" --target-date "2026-03-31"  # create a milestone
+linear milestone create --project <projectId> --name "Q1 Goals" --dry-run   # preview a milestone create
 linear m create --project <projectId>           # create a milestone (interactive)
 linear milestone update <milestoneId> --name "New Name"  # update milestone name
+linear milestone update <milestoneId> --name "New Name" --dry-run           # preview a milestone update
 linear m update <milestoneId> --target-date "2026-04-15"  # update target date
 linear milestone delete <milestoneId>           # delete a milestone
+linear milestone delete <milestoneId> --dry-run                                # preview a milestone delete
 linear m delete <milestoneId> --force           # delete without confirmation
 ```
 
@@ -278,17 +310,20 @@ linear document create --title "My Doc" --content "# Hello"           # inline c
 linear document create --title "Spec" --content-file ./spec.md        # from file
 linear document create --title "Doc" --project <projectId>            # attach to project
 linear document create --title "Notes" --issue TC-123                 # attach to issue
+linear document create --title "Spec" --content "# Draft" --dry-run   # preview a document create
 cat spec.md | linear document create --title "Spec"                   # from stdin
 
 # update a document
 linear document update <slug> --title "New Title"                     # update title
 linear document update <slug> --content-file ./updated.md             # update content
 linear document update <slug> --edit                                  # open in $EDITOR
+linear document update <slug> --title "New Title" --dry-run           # preview a document update
 
 # delete a document
 linear document delete <slug>                   # soft delete (move to trash)
 linear document delete <slug> --permanent       # permanent delete
 linear document delete --bulk <slug1> <slug2>   # bulk delete
+linear document delete <slug> --dry-run         # preview a document delete
 ```
 
 ### notification commands
@@ -313,8 +348,11 @@ linear webhook list
 linear webhook list --team ENG
 linear webhook view <webhookId>
 linear webhook create --url https://example.com/linear --resource-types Issue,Comment
+linear webhook create --url https://example.com/linear --resource-types Issue,Comment --dry-run --json
 linear webhook update <webhookId> --disabled
+linear webhook update <webhookId> --disabled --dry-run --json
 linear webhook delete <webhookId> --yes
+linear webhook delete <webhookId> --dry-run --json
 linear webhook list --json
 ```
 

package/npm-shrinkwrap.json

@@ -23,7 +23,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@kyaukyuai/linear-cli",
-      "version": "2.7.1"
+      "version": "2.8.1"
     },
     "node_modules/@isaacs/cliui": {
       "engines": {
@@ -542,5 +542,5 @@
     }
   },
   "requires": true,
-  "version": "2.7.1"
+  "version": "2.8.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/kyaukyuai/linear-cli/releases/download/v2.7.1"
+    "https://github.com/kyaukyuai/linear-cli/releases/download/v2.8.1"
   ],
   "bin": {
     "linear": "run-linear.js"
@@ -85,7 +85,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "2.7.1",
+  "version": "2.8.1",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"