@kyaukyuai/linear-cli 2.11.0 → 2.12.1

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [2.12.1] - 2026-03-30
+
+### Added
+
+- added `stateName` to `issue list --json` as an additive convenience field while keeping the nested `state` object unchanged
+
+### Changed
+
+- refreshed the README, agent workflow docs, and skills.sh install guidance to better position `linear-cli` as an agent-first Linear CLI
+
+### Fixed
+
+- preserved agent-first generated skill docs so `deno task generate-skill-docs` no longer reverts the published skill description and command guidance
+
+## [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

package/README.md

@@ -16,6 +16,22 @@ linear notification list --json
 
 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.
 
+## for agents
+
+If an agent only reads one page, it should be this README plus the two contract docs below.
+
+- start with `linear capabilities --json` to discover which commands support `--json`, `--dry-run`, stdin, confirmation bypass, and stable automation contracts
+- prefer stable read surfaces such as `issue`, `project`, `cycle`, `milestone`, `document`, `webhook`, `notification`, `team`, `user`, `workflow-state`, `label`, `initiative`, and update feeds with `--json`
+- preview writes with `--dry-run --json` before mutating Linear
+- apply writes with `--json`, then inspect exit codes and `error.details` instead of parsing terminal text
+- use stdin or file flags for Markdown-heavy descriptions and comments instead of long inline shell strings
+
+Recommended docs:
+
+- [Agent workflow guide](docs/agent-first.md)
+- [Automation contracts](docs/json-contracts.md)
+- [stdin and pipeline policy](docs/stdin-policy.md)
+
 ## screencast demos
 
 <details>
@@ -36,6 +52,24 @@ interactive commands still exist for humans, but the primary design goal is that
 
 for agents and scripts, prefer a pinned install in the repo or runtime you control.
 
+### install as a skill
+
+If you want to expose `linear-cli` as a reusable skill on top of an existing agent runtime, install it from the repo root and select the public skill explicitly:
+
+```bash
+npx skills add https://github.com/kyaukyuai/linear-cli --skill linear-cli
+```
+
+This is the most compatible form for `skills` and `skills.sh`.
+
+If you want to point directly at the skill directory instead, this also works:
+
+```bash
+npx skills add https://github.com/kyaukyuai/linear-cli/tree/main/skills/linear-cli
+```
+
+Once installed, agents can load the skill and then call the local `linear` binary using the agent-first guidance in [skills/linear-cli/SKILL.md](skills/linear-cli/SKILL.md).
+
 ### npm / bun / pnpm
 
 install as a dependency to pin a version in your project:
@@ -59,6 +93,8 @@ bunx linear issue list
 
 package on npm: [@kyaukyuai/linear-cli](https://www.npmjs.com/package/@kyaukyuai/linear-cli)
 
+skills directory on GitHub: [skills/linear-cli](https://github.com/kyaukyuai/linear-cli/tree/main/skills/linear-cli)
+
 ### deno via jsr
 
 ```bash
@@ -88,7 +124,7 @@ deno task install
 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 and command traits without scraping docs
+- 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
@@ -101,26 +137,38 @@ compared to upstream, this fork adds and maintains capabilities aimed at automat
 - 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, milestone, document, webhook, and notification 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
 
+## docs map
+
+Use the docs in this order if you are building an agent integration:
+
+1. [docs/agent-first.md](docs/agent-first.md) for the recommended discover/read/preview/apply/recover loop
+2. [docs/json-contracts.md](docs/json-contracts.md) for stable JSON payloads, exit codes, timeout semantics, and dry-run envelopes
+3. [docs/stdin-policy.md](docs/stdin-policy.md) for pipeline and file-input conventions
+4. [`linear capabilities --json`](#automation-contract) for machine-readable command metadata at runtime
+
 ## automation contract
 
 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, and idempotency category.
+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`, 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 issue write commands also 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"`.
+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.
 

package/npm-shrinkwrap.json

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

package/package.json

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