@kyaukyuai/linear-cli 2.10.0 → 2.12.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased]
 
+## [2.12.0] - 2026-03-30
+
+### Added
+
+- added schema-style metadata to `linear capabilities --json` so agents can inspect command arguments, input modes, output semantics, and exit codes without scraping docs
+- added Automation Contract v5 coverage for `initiative list/view --json`, `project-update list --json`, and `initiative-update list --json`
+
+### Changed
+
+- upgraded write timeout handling to reconcile against Linear after client-side confirmation timeouts, distinguishing `probably_succeeded`, `definitely_failed`, and `partial_success` outcomes for high-value write commands
+
+## [2.11.0] - 2026-03-30
+
+### Added
+
+- added `linear capabilities --json` so agents can discover supported JSON, dry-run, stdin, confirmation, and retry semantics without scraping help text
+- added Automation Contract v4 coverage for `team`, `user`, `workflow-state`, and label read surfaces
+
+### Changed
+
+- standardized write retry semantics with explicit idempotency categories, retry-safe notification archive/read behavior, and shared partial-success metadata
+
+### Fixed
+
+- improved write timeout semantics with distinct `timeout_error` JSON failures, exit code `6`, and clearer partial-success details for combined write flows such as `issue update --comment --json`
+
 ## [2.10.0] - 2026-03-30
 
 ### Added

package/README.md

@@ -1,24 +1,20 @@
-# kyaukyuai/linear-cli
+# linear-cli
 
-`kyaukyuai/linear-cli` is a fork of [`schpet/linear-cli`](https://github.com/schpet/linear-cli) for teams that want a git-first Linear CLI with additional automation, scripting, and documentation support. it remains git and [jj](https://www.jj-vcs.dev/) aware so you can stay in the right Linear context without leaving the terminal.
+`linear-cli` is an agent-first Linear CLI for Claude Code, Codex, and other automation that needs a stable command surface instead of screen scraping or ad-hoc GraphQL scripts. this fork of [`schpet/linear-cli`](https://github.com/schpet/linear-cli) keeps the git and [jj](https://www.jj-vcs.dev/) workflow ergonomics from upstream, then adds stable JSON contracts, dry-run previews, retry-safe error semantics, and pipeline-friendly command behavior for automation-heavy teams.
 
-**works great with AI agents** — the CLI includes a [skill](#skills) that lets agents create issues, update status, and manage your Linear workflow alongside your code.
-
-here's how it works:
+if you want an agent to read Linear state, preview a write, apply it, and return structured output without leaving the shell, this repo is designed for that path first.
 
 ```bash
-linear config               # setup your repo, it writes a config file
-
-linear issue list           # list unstarted issues assigned to you
-linear issue list -A        # include unassigned and other assignees
-linear issue start          # choose an issue to start, creates a branch
-linear issue start ABC-123  # start a specific issue
-linear issue view           # see current branch's issue as markdown
-linear issue pr             # makes a PR with title/body preset, using gh cli
-linear issue create         # create a new issue
+linear capabilities --json
+linear issue list --json
+linear issue view ENG-123 --json
+linear issue create -t "Backfill webhook contract docs" --team ENG --dry-run --json
+linear issue update ENG-123 --state done --comment "Shipped in v2.10.0" --json
+linear project view "Automation Contract v3" --json
+linear notification list --json
 ```
 
-it aims to be a complement to the web and desktop apps that lets you stay on the command line in an interactive or scripted way.
+interactive commands still exist for humans, but the primary design goal is that an agent can discover commands incrementally, pass all important input as flags or stdin, and get machine-readable success or failure back.
 
 ## screencast demos
 
@@ -38,21 +34,11 @@ it aims to be a complement to the web and desktop apps that lets you stay on the
 
 ## install
 
-### homebrew
-
-```
-brew install kyaukyuai/tap/linear
-```
-
-### deno via jsr
-
-```bash
-deno install -A --reload -f -g -n linear jsr:@kyaukyuai/linear-cli
-```
+for agents and scripts, prefer a pinned install in the repo or runtime you control.
 
 ### npm / bun / pnpm
 
-install as a dev dependency to pin a version in your project:
+install as a dependency to pin a version in your project:
 
 ```bash
 npm install -D @kyaukyuai/linear-cli
@@ -73,6 +59,18 @@ bunx linear issue list
 
 package on npm: [@kyaukyuai/linear-cli](https://www.npmjs.com/package/@kyaukyuai/linear-cli)
 
+### deno via jsr
+
+```bash
+deno install -A --reload -f -g -n linear jsr:@kyaukyuai/linear-cli
+```
+
+### homebrew
+
+```bash
+brew install kyaukyuai/tap/linear
+```
+
 ### binaries
 
 https://github.com/kyaukyuai/linear-cli/releases/latest
@@ -85,10 +83,17 @@ cd linear-cli
 deno task install
 ```
 
-## fork-specific features
+## agent-facing capabilities
 
-compared to upstream, this fork adds and maintains several capabilities aimed at automation-heavy workflows:
+compared to upstream, this fork adds and maintains capabilities aimed at automation-heavy workflows:
 
+- stable JSON contracts for the automation tier, with machine-readable failures for parser, validation, and runtime errors
+- a self-describing `linear capabilities --json` surface so agents can discover contract coverage, primary input schema, output semantics, and command traits without scraping docs
+- `--dry-run` previews for high-value write commands, including `issue start`, issue writes, and non-issue writes
+- stdin and pipeline support for high-value write paths
+- retry-safe semantics for relation add/delete, project label add/remove, notification read/archive, and structured partial-failure details
+- canonical `--yes` confirmation bypass handling for destructive commands
+- agent-focused help examples across automation-tier and major write commands
 - cycle workflows beyond listing and viewing, including `cycle current`, `cycle next`, `cycle create`, `cycle add`, and `cycle remove`
 - issue workflow commands for `search`, `assign`, `move`, `priority`, `estimate`, `label add/remove`, comment delete, relations, and attachments
 - inbox notification commands for `list`, `count`, `read`, and `archive`
@@ -96,7 +101,8 @@ compared to upstream, this fork adds and maintains several capabilities aimed at
 - workflow state commands for `list` and `view`
 - user commands for `list` and `view`
 - project label commands for `list` and `project label add/remove`
-- JSON output for scripting across issue, cycle, project, and document commands
+- initiative commands for `list` and `view`, plus project update and initiative update feeds
+- JSON output for scripting across issue, cycle, project, milestone, initiative, document, webhook, notification, and update-feed commands
 - 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
 
@@ -104,14 +110,20 @@ compared to upstream, this fork adds and maintains several capabilities aimed at
 
 for bot and org-wide automation use cases, `linear-cli` defines a stable JSON contract for a focused automation tier.
 
+to discover the curated agent-facing command surface programmatically, use `linear capabilities --json`. it reports stable contract versions, automation-tier membership, and per-command support for `--json`, `--dry-run`, stdin, confirmation bypass, idempotency category, primary arguments and flags, and success/failure output semantics.
+
 - 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`
 - v3 additions: `document list/view --json`, `webhook list/view --json`, `notification list/count --json`
+- v4 additions: `team list/view --json`, `user list/view --json`, `workflow-state list/view --json`, `label list --json`, `project-label list --json`
+- v5 additions: `initiative list/view --json`, `project-update list --json`, `initiative-update list --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.
 
-for automation consumers, auth and authorization failures now use exit code `4`, while free-plan or workspace-plan limit failures use exit code `5`. other contract failures remain non-zero and currently use `1`. rate-limited responses remain on exit code `1`, but now include retry guidance and, when available, `error.details.rateLimit` metadata.
+for automation consumers, auth and authorization failures now use exit code `4`, free-plan or workspace-plan limit failures use exit code `5`, and client-side write confirmation timeouts use exit code `6`. other contract failures remain non-zero and currently use `1`. rate-limited responses remain on exit code `1`, but now include retry guidance and, when available, `error.details.rateLimit` metadata.
+
+high-value write commands honor `LINEAR_WRITE_TIMEOUT_MS` and accept `--timeout-ms` for per-command overrides. timeout failures return a distinct machine-readable failure mode, `timeout_error`, with `error.details.failureMode = "timeout_waiting_for_confirmation"`. when reconciliation runs after the timeout, `error.details.outcome` now distinguishes `definitely_failed`, `probably_succeeded`, and `partial_success` from the fallback `unknown` state. notification `read` and `archive` now use the same timeout contract as issue write commands.
 
 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.
 
@@ -120,10 +132,11 @@ destructive commands use `--yes` as the canonical confirmation-bypass flag. lega
 for retry behavior, prefer treating write commands in three buckets:
 
 - retry-safe set-style writes: `issue update` without `--comment`, plus relation add/delete
+- retry-safe no-op writes: `project label add/remove` and `notification read/archive`, which succeed without mutating when the target state is already satisfied
 - non-idempotent writes: `issue create`, `issue comment add`, and `issue update --comment`
 - resumable but non-idempotent batch writes: `issue create-batch`, which reports `error.details.createdIdentifiers` and `failedStep` on partial failure
 
-when `issue update --comment --json` updates the issue but the follow-up comment fails, the command exits non-zero and includes `error.details.partialSuccess.issueUpdated = true` plus a standalone retry command for `issue comment add`.
+when a write command completes part of its work and then fails, `error.details` uses a shared partial-success shape with `failureStage`, `retryable`, and `partialSuccess`. for example, `issue update --comment --json` sets `error.details.partialSuccess.issueUpdated = true` and includes a standalone retry command for `issue comment add`.
 
 For stdin and pipeline behavior, see [docs/stdin-policy.md](docs/stdin-policy.md).
 
@@ -257,6 +270,8 @@ For short inline text, `-d/--description` is fine. For Markdown content, prefer
 
 ```bash
 linear team list       # list teams
+linear team list --json  # emit contract-stable team summaries
+linear team view ENG --json  # emit contract-stable team details
 linear team id         # print out the team id (e.g. for scripts)
 linear team members    # list team members
 linear team members ENG --json  # emit assignable candidates for a team
@@ -383,11 +398,24 @@ inspect workflow states directly, without going through issue mutations.
 
 ```bash
 linear workflow-state list --team ENG
-linear workflow-state list --json
+linear workflow-state list --team ENG --json
 linear workflow-state view <workflowStateId>
 linear workflow-state view <workflowStateId> --json
 ```
 
+### label commands
+
+inspect issue labels and project labels directly with a primitive GraphQL-aligned surface.
+
+```bash
+linear label list
+linear label list --team ENG
+linear label list --json
+linear project-label list
+linear project-label list --include-archived
+linear project-label list --json
+```
+
 ### project label commands
 
 inspect workspace project labels directly with a primitive GraphQL-aligned surface.
@@ -405,9 +433,9 @@ inspect workspace users directly with a primitive GraphQL-aligned surface.
 ```bash
 linear user list
 linear user list --all
-linear user list --json
+linear user list --json  # emit contract-stable user summaries
 linear user view <userId>
-linear user view <userId> --json
+linear user view <userId> --json  # emit contract-stable user details
 ```
 
 ### other commands

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/kyaukyuai/linear-cli/releases/download/v2.10.0"
+    "https://github.com/kyaukyuai/linear-cli/releases/download/v2.12.0"
   ],
   "bin": {
     "linear": "run-linear.js"
@@ -12,7 +12,7 @@
     "detect-libc": "^2.1.2",
     "rimraf": "^6.1.3"
   },
-  "description": "Git-first Linear CLI with workspace-aware auth, issue workflows, and automation-friendly JSON output",
+  "description": "Agent-first Linear CLI with stable JSON contracts, dry-run previews, and workflow-safe automation",
   "devDependencies": {
     "prettier": "^3.8.1"
   },
@@ -85,7 +85,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "2.10.0",
+  "version": "2.12.0",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"