@kyaukyuai/linear-cli 2.15.0 → 3.0.1

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [3.0.1] - 2026-04-05
+
+### Changed
+
+- published a copy-pasteable v2-to-v3 migration cookbook and strengthened the v3 release guide around startup, diagnostics, and explicit compatibility-mode guidance
+- expanded the v3 release gate to certify both the native startup/discovery path and the explicit compatibility path for diagnostics and human/debug inspection
+
+### Fixed
+
+- improved common v3 compatibility failures so runtime suggestions point callers to `--text`, `--compat v1`, or `--profile human-debug --interactive` instead of forcing migration guidance to live only in docs
+
+## [3.0.0] - 2026-04-04
+
+### Added
+
+- extended the shared `operation` and `receipt` contract family across remaining high-value write commands, including issue assignment/estimate/move/priority, project create and project-label mutation flows, webhook writes, and batch issue creation
+- published an agent-native v3 migration guide and rewrote the README and skill/docs stack around AI agent runtimes instead of mixed human/operator usage
+
+### Changed
+
+- changed the default runtime to agent-native execution for core startup, read, and representative write surfaces by making machine-readable JSON the default output mode and relegating human-readable output to the explicit `--text` escape hatch
+- removed implicit interactive fallback behavior from startup-critical paths; prompt-driven flows now require explicit `--profile human-debug --interactive`
+- made `agent-safe` the default execution profile, so pager-off behavior, longer write timeout defaults, and explicit destructive confirmation semantics are the standard runtime path
+- promoted the richer `linear capabilities` schema metadata to the default discovery surface and kept the legacy trimmed shape available only through explicit `--compat v1`
+
 ## [2.15.0] - 2026-04-03
 
 ### Added

package/README.md

@@ -1,43 +1,91 @@
 # linear-cli
 
-`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.
+`linear-cli` is an agent-native Linear runtime 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 layers on stable JSON contracts, startup discovery, dry-run previews, operation receipts, and workflow-safe error semantics for agent-controlled execution.
 
-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.
+if you want an agent to read Linear state, resolve refs, preview a write, apply it, and return structured output without leaving the shell, this repo is designed for that path first. `main` now reflects the `v3.0.0` runtime direction: core surfaces default to machine-readable output, startup flows are non-interactive, and human-oriented terminal output is an explicit escape hatch instead of the primary product surface.
 
 ```bash
-linear capabilities --json
-linear capabilities --json --compat v2
-linear resolve issue ENG-123 --json
-linear --profile agent-safe issue update ENG-123 --state done --dry-run --json
-linear issue list --json
-linear issue view ENG-123 --json
+linear capabilities
+linear capabilities --compat v1
+linear resolve issue ENG-123
+linear issue update ENG-123 --state done --dry-run --json
+linear issue list
+linear issue view ENG-123
 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
+linear issue update ENG-123 --state done --comment "Shipped in v2.10.0"
+linear project view "Automation Contract v3"
+linear notification list
 ```
 
-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.
+the core agent surfaces now default to machine-readable JSON. use `--text` when a human wants terminal-oriented output for ad-hoc inspection or debugging.
+
+## what v3.0.0 means
+
+`v3.0.0` is the release where `linear-cli` stops behaving like a mixed human/agent CLI and starts behaving like an agent-native control plane by default.
+
+- startup discovery defaults to the richer `linear capabilities` schema
+- startup-critical reads and representative writes default to machine-readable JSON
+- prompt fallbacks are no longer implicit; use `--profile human-debug --interactive` when a maintainer explicitly wants them
+- `agent-safe` is the default execution profile
+- preview/apply/result flows share `operation`, `receipt`, and structured `error.details`
+
+if you are integrating `linear-cli` into an agent runtime, assume the defaults above and treat `--text` plus `--profile human-debug` as secondary debugging tools.
+
+## agent-native runtime
+
+Treat `linear-cli` as a shell-native control plane for agents:
+
+- startup discovery comes from `linear capabilities`
+- startup-critical reads and core write surfaces default to machine-readable JSON
+- refs can be normalized with `linear resolve ...`
+- write previews use `--dry-run --json`
+- write results expose `operation`, `receipt`, and structured `error.details`
+- human/debug behavior is explicit with `--text` and `--profile human-debug --interactive`
+
+The practical default loop is:
+
+1. `linear capabilities`
+2. `linear resolve ...`
+3. default-JSON reads such as `linear issue view ENG-123`
+4. `--dry-run --json` previews for writes
+5. apply the mutation and inspect `operation`, `receipt`, and `error.details`
 
 ## 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` for the stable startup-safe shape; use `linear capabilities --json --compat v2` when you also need required/optional input refs, constrained values, defaults, context resolution hints, input constraints, canonical argv examples, stdin/file targets, and structured output semantics
-- use `linear --profile agent-safe ...` when you want predictable non-interactive defaults for an automation run
-- resolve ambiguous issue/team/state/user/label refs with `linear resolve ... --json` before previewing or applying writes
-- prefer stable read surfaces such as `issue`, `project`, `cycle`, `milestone`, `document`, `webhook`, `notification`, `team`, `user`, `workflow-state`, `label`, `initiative`, and update feeds with `--json`
+- start with `linear capabilities` for the default schema-like discovery shape; use `linear capabilities --compat v1` only when an older consumer still expects the legacy startup shape
+- use the default runtime for predictable non-interactive agent execution; `--profile human-debug` is the explicit escape hatch for pager and prompt-driven debugging
+- resolve ambiguous issue/team/state/user/label refs with `linear resolve ...` before previewing or applying writes
+- prefer stable read surfaces such as `issue`, `project`, `cycle`, `milestone`, `document`, `webhook`, `notification`, `team`, `user`, `workflow-state`, `label`, `initiative`, and update feeds; those agent-first entrypoints now default to machine-readable 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
+- apply writes on default-JSON surfaces without `--text`, then inspect exit codes and `error.details` instead of parsing terminal text
+- use `--profile human-debug --interactive` for human/debug prompt flows; missing required inputs now fail fast by default
 - 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)
+- [Agent-only v3 release guide](docs/agent-only-v3.md)
+- [v2 to v3 migration cookbook](docs/v2-to-v3-migration-cookbook.md)
 - [stdin and pipeline policy](docs/stdin-policy.md)
 
-## screencast demos
+## migration from 2.x
+
+If a downstream consumer still assumes the older mixed human/agent behavior, migrate in this order:
+
+1. stop parsing styled terminal output
+2. use `linear capabilities` for startup discovery and pin `--compat v1` only where a legacy consumer still needs it
+3. treat `operation`, `receipt`, and `error.details` as the canonical execution surface
+4. add `--text` anywhere a maintainer still wants terminal-oriented output
+5. add `--profile human-debug --interactive` anywhere a maintainer still wants prompts or pager-oriented debugging
+
+The detailed release and migration guide lives in [docs/agent-only-v3.md](docs/agent-only-v3.md). For copy-pasteable before/after fixes, use [docs/v2-to-v3-migration-cookbook.md](docs/v2-to-v3-migration-cookbook.md).
+
+## human-debug demos
+
+These demos are intentionally secondary. they show the explicit human/debug escape hatch, not the primary runtime path for agents.
 
 <details>
 <summary><code>linear issue create</code></summary>
@@ -129,7 +177,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 with a backward-compatible default and an explicit `--compat v2` mode for richer schema and output metadata
+- a self-describing `linear capabilities` surface with richer schema and output metadata by default and an explicit `--compat v1` fallback for legacy consumers
 - `--dry-run` previews for high-value write commands, including `issue start`, issue writes, and non-issue writes
 - additive operation receipts on high-value JSON write success paths
 - a shared top-level `operation` contract on representative preview/apply JSON write paths
@@ -155,22 +203,24 @@ 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
+3. [docs/agent-only-v3.md](docs/agent-only-v3.md) for the `v3.0.0` release contract and downstream migration checklist
+4. [docs/v2-to-v3-migration-cookbook.md](docs/v2-to-v3-migration-cookbook.md) for consumer-facing before/after upgrade examples
+5. [docs/stdin-policy.md](docs/stdin-policy.md) for pipeline and file-input conventions
+6. [`linear capabilities`](#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.
+for bot and org-wide automation use cases, `linear-cli` defines a stable machine-readable contract for a focused automation tier. that contract is the primary runtime surface. `--text` and prompt flows are secondary human/debug escape hatches.
 
-to discover the curated agent-facing command surface programmatically, use `linear capabilities --json`. the default shape preserves the v1-compatible startup contract for existing bots. when you need richer metadata such as required vs optional primary inputs, constrained values, defaults, context resolution hints, input constraints, canonical argv examples, stdin/file targets, structured output semantics, and timeout/no-op traits, opt into `linear capabilities --json --compat v2`.
+to discover the curated agent-facing command surface programmatically, use `linear capabilities`. the default shape now returns the richer v2 schema metadata for agent-native startup. when an older consumer still expects the trimmed legacy shape, pin it explicitly with `linear capabilities --compat v1`.
 
-`linear --profile agent-safe ...` is the opt-in execution profile for agent-controlled runs. it currently disables pager-by-default behavior, extends the built-in write timeout to `45000ms` unless `--timeout-ms` or `LINEAR_WRITE_TIMEOUT_MS` is set, and rejects destructive confirmation prompts unless the caller passes `--yes`.
+`agent-safe` is now the default execution profile for agent-controlled runs. it disables pager-by-default behavior, extends the built-in write timeout to `45000ms` unless `--timeout-ms` or `LINEAR_WRITE_TIMEOUT_MS` is set, and keeps destructive confirmation bypass explicit with `--yes`. use `--profile human-debug` when a maintainer explicitly wants prompt-driven or pager-oriented debugging behavior.
 
 non-goals:
 
-- it does not force `--json`
+- it does not force `--json` on commands outside the agent-native default-JSON surface
 - it does not auto-confirm destructive actions
-- it does not replace every interactive data-entry fallback; callers should still pass explicit flags, stdin, or file inputs
+- it does not replace explicit human/debug prompt flows; callers should pass flags, stdin, file inputs, or opt into `--profile human-debug --interactive`
 
 - 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`
@@ -180,7 +230,7 @@ non-goals:
 - v6 additions: `resolve issue/team/workflow-state/user/label --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 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 the command is in machine-readable mode, whether that is the default or was requested explicitly with `--json`.
 
 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.
 
@@ -188,7 +238,7 @@ high-value write commands honor `LINEAR_WRITE_TIMEOUT_MS` and accept `--timeout-
 
 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.
 
-representative preview/apply JSON write paths may add a top-level `operation` field so agents can diff preview intent against apply results with one parser path. successful high-value JSON writes may also add a top-level `receipt` field. this gives agents a shared place to inspect `operationId`, `resolvedRefs`, `appliedChanges`, `noOp`, and `nextSafeAction` without inferring those traits from command-specific payload fields.
+representative preview/apply JSON write paths may add a top-level `operation` field so agents can diff preview intent against apply results with one parser path. successful high-value JSON writes may also add a top-level `receipt` field. this gives agents a shared place to inspect `operationId`, `resolvedRefs`, `appliedChanges`, `noOp`, and `nextSafeAction` without inferring those traits from command-specific payload fields. current coverage includes issue create/update/comment/relation, issue batch creation, issue assignment/estimate/move/priority, project create and label add/remove, webhook create/update/delete, and notification read/archive.
 
 destructive commands use `--yes` as the canonical confirmation-bypass flag. legacy `--force` and `--confirm` flags are still accepted where older workflows already depended on them.
 
@@ -219,17 +269,17 @@ this fork is intentionally diverging from upstream in a few ways:
 2. authenticate with the CLI:
 
    ```sh
-   linear auth login
+   linear auth login --profile human-debug --interactive
    ```
 
 3. configure your project:
 
    ```sh
    cd my-project-repo
-   linear config
+   linear config --profile human-debug --interactive
    ```
 
-see [docs/authentication.md](docs/authentication.md) for multi-workspace support and other authentication options.
+For unattended agent runtimes, prefer injected credentials and explicit config over prompt flows. see [docs/authentication.md](docs/authentication.md) for multi-workspace support and other authentication options.
 
 the CLI works with both git and jj version control systems:
 
@@ -248,11 +298,11 @@ the current issue is determined by:
 note that [Linear's GitHub integration](https://linear.app/docs/github#branch-format) will suggest git branch names.
 
 ```bash
-linear issue view      # view current issue details in terminal
+linear issue view      # emit machine-readable current issue details
 linear issue view ABC-123
 linear issue view 123
-linear issue view ABC-123 --json            # emit stable machine-readable issue details
-linear issue view ABC-123 --json --no-comments  # skip raw comments but keep commentsSummary
+linear issue view ABC-123 --text            # human/debug output
+linear issue view ABC-123 --no-comments     # skip raw comments but keep commentsSummary
 linear issue view -w   # open issue in web browser
 linear issue view -a   # open issue in Linear.app
 linear issue id        # prints the issue id from current branch (e.g., "ENG-123")
@@ -269,9 +319,10 @@ linear issue list --all-states --query auth --priority high --updated-before 202
 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  # create/switch to issue branch and mark as started
+linear issue start --interactive  # choose an issue interactively in a terminal
 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 --interactive  # create a new issue with interactive prompts
 linear issue create -t "title" -d "description"  # create with flags
 cat description.md | linear issue create -t "title" --team ENG  # read description from stdin
 linear issue create -t "title" --team ENG --json  # emit machine-readable created issue data
@@ -279,7 +330,7 @@ linear issue create -t "title" --team ENG --dry-run --json  # preview the create
 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 --interactive  # update an issue with interactive prompts
 cat description.md | linear issue update ENG-123 --state started  # read description from stdin
 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
@@ -506,7 +557,7 @@ linear user view <userId> --json  # emit contract-stable user details
 ```bash
 linear --help          # show all commands
 linear --version       # show version
-linear config          # setup the project
+linear config --profile human-debug --interactive  # maintainer setup flow
 linear completions     # generate shell completions
 ```
 

package/npm-shrinkwrap.json

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

package/package.json

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