linearis-oss · iamfj · Aug 7, 2026 · Jul 6, 2026 · Jul 6, 2026 · Jul 6, 2026
@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Marketplace for the linearis Claude Code plugin.",
-    "version": "1.0.0"
+    "version": "1.1.0"
   },
   "plugins": [
     {
       "name": "linearis",
       "source": "./",
       "description": "Agent skill teaching agents to use the linearis Linear.app CLI.",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "author": { "name": "linearis-oss" },
       "homepage": "https://github.com/linearis-oss/linearis",
       "license": "MIT"

@@ -1,7 +1,7 @@
 {
   "name": "linearis",
-  "description": "Agent skill for the linearis Linear.app CLI: preflight, discover-then-act usage protocol, JSON output, ID resolution, discussions, files.",
-  "version": "1.0.0",
+  "description": "Agent skill for the linearis Linear.app CLI: preflight, discover-then-act usage protocol, JSON output, error envelopes and exit codes, ID resolution, discussions, files.",
+  "version": "1.1.0",
   "author": {
     "name": "linearis-oss",
     "url": "https://github.com/linearis-oss/linearis"

@@ -27,13 +27,22 @@ runs:
     # node-version (when set by a matrix job) takes precedence over
     # node-version-file; an empty node-version falls back to .nvmrc.
     - name: Setup Node
-      uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
       with:
         node-version: ${{ inputs.node-version }}
         node-version-file: .nvmrc
         cache: npm
         registry-url: ${{ inputs.registry-url }}
 
+    # package-lock.json is written by npm 11 (project default and Renovate).
+    # Node 22 bundles npm 10, which materializes optional peerDependencies that
+    # npm 11 omits from the lockfile, so `npm ci` there fails with EUSAGE. Pin
+    # the npm major so every matrix Node version agrees with the committed
+    # lockfile; the matrix still exercises the engines floor at runtime.
+    - name: Pin npm major
+      shell: bash
+      run: npm install -g npm@11
+
     # `npm ci` runs `prepare`, which is CI-guarded (scripts/prepare.mjs) so it
     # does NOT hit the live Linear GraphQL schema here. Jobs needing generated
     # types must run the build step below (or `npm pack`).

@@ -20,7 +20,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Setup and build
         uses: ./.github/actions/setup

@@ -34,7 +34,7 @@ jobs:
         node-version: [22, 24]
     steps:
       - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Setup and build
         uses: ./.github/actions/setup
@@ -49,7 +49,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Setup and build
         uses: ./.github/actions/setup
@@ -68,7 +68,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Run actionlint
         uses: docker://rhysd/actionlint@sha256:b1934ee5f1c509618f2508e6eb47ee0d3520686341fec936f3b79331f9315667 # v1.7.12
@@ -90,7 +90,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       # Build runs codegen (prebuild) so src/gql exists and imports resolve.
       - name: Setup and build
@@ -162,7 +162,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
 
@@ -185,7 +185,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       # No build here: verify:packed-binaries runs `npm pack`, whose `prepack`
       # builds (and generates) the package the same way a consumer install would.
@@ -205,7 +205,7 @@ jobs:
       contents: read
       pull-requests: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
       - name: Check for docs/plans/*.md in branch history
@@ -253,7 +253,7 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event_name == 'pull_request'
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
 

@@ -47,7 +47,7 @@ jobs:
         run: echo "number=$(cat pr-number.txt)" >> "$GITHUB_OUTPUT"
 
       - name: Post / update PR comment
-        uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v3.0.4
+        uses: marocchino/sticky-pull-request-comment@5770ad5eb8f42dd2c4f34da00c94c5381e49af88 # v3.0.5
         with:
           header: knip-dead-code
           path: knip-comment.md

@@ -21,7 +21,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: next
           fetch-depth: 0

@@ -65,7 +65,7 @@ jobs:
           echo "Releasing from branch: $branch"
 
       - name: Checkout code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
           ref: ${{ steps.target.outputs.branch }}

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout next
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: next
           fetch-depth: 0

@@ -1,3 +1,15 @@
+## [2026.7.0-next.6](https://github.com/linearis-oss/linearis/compare/v2026.7.0-next.5...v2026.7.0-next.6) (2026-08-07)
+
+## [2026.7.0-next.5](https://github.com/linearis-oss/linearis/compare/v2026.7.0-next.4...v2026.7.0-next.5) (2026-08-06)
+
+## [2026.7.0-next.4](https://github.com/linearis-oss/linearis/compare/v2026.7.0-next.3...v2026.7.0-next.4) (2026-08-06)
+
+## [2026.7.0-next.3](https://github.com/linearis-oss/linearis/compare/v2026.7.0-next.2...v2026.7.0-next.3) (2026-08-06)
+
+## [2026.7.0-next.2](https://github.com/linearis-oss/linearis/compare/v2026.7.0-next.1...v2026.7.0-next.2) (2026-07-06)
+
+## [2026.7.0-next.1](https://github.com/linearis-oss/linearis/compare/v2026.6.0...v2026.7.0-next.1) (2026-07-06)
+
 ## [2026.6.0](https://github.com/linearis-oss/linearis/compare/v2026.5.0...v2026.6.0) (2026-07-04)
 
 ### Features

@@ -30,7 +30,7 @@ The official Linear MCP works well, but it costs ~13k tokens just by being conne
 A typical agent interaction costs **~500–700 tokens** of context instead of ~13k. The agent pays only for what it uses, one domain at a time.
 
 > [!NOTE]
-> The trade-off is coverage. Linearis focuses on the operations that matter for day-to-day work — issues, discussions, cycles, projects, documents, and files. For custom workflows, integrations, or workspace settings, the MCP is the better choice.
+> The trade-off is coverage. Linearis focuses on the operations that matter for day-to-day work — issues, discussions, cycles, projects, documents, and files. For custom workflows, integrations, or workspace settings, the MCP is the better choice. See [Coverage](#coverage) for the exact picture.
 
 ## Features
 
@@ -108,22 +108,80 @@ linearis issues replies <root-thread-id>
 linearis issues reply <root-thread-id> --body "I found the root cause"
 ```
 
-### Domains
-
-| Domain | What it covers |
-|---|---|
-| `issues` | Work items with status, priority, assignee, labels, and discussions |
-| `projects` | Groups of issues working toward a goal |
-| `initiatives` | Strategic, multi-project goals |
-| `cycles` | Time-boxed iterations (sprints) per team |
-| `milestones` | Progress checkpoints within projects |
-| `documents` | Long-form markdown docs attached to projects or issues |
-| `labels` | Categorization tags for issues and projects |
-| `attachments` | Linked external resources on issues (PRs, commits, URLs) |
-| `files` | Upload and download file attachments |
-| `teams` | Organizational units owning issues and cycles |
-| `users` | Workspace members and assignees |
-| `auth` | Authenticate with the Linear API |
+## Coverage
+
+Linear's GraphQL API exposes **537 root operations** (164 queries, 373 mutations). Linearis wires about **75 of them** directly, plus a number of nested reads — chosen to cover planning and issue work end to end rather than the whole API.
+
+The table below is the honest picture of the whole surface — what works today, and what you'll need the [Linear MCP](#linearis-vs-linear-mcp) or a raw API call for.
+
+**Legend** — ✅ complete for practical purposes · 🟡 core operations, known gaps · 🟠 read-only or narrow slice · 🔴 no CLI surface yet
+
+| Area | Extent | What you can do | Not covered |
+|---|---|---|---|
+| `auth` | ✅ | Interactive login, token status, logout | — |
+| Discussions | ✅ | Root threads and replies on issues, projects, and initiatives; edit, delete, resolve/unresolve; emoji reactions on any of them | Custom workspace emoji management |
+| `issues` | 🟡 | List, filter, full-text search, read, create, update, archive/unarchive, delete; assign labels/assignee/state/priority/project/cycle; relations (list/add/remove); activity history | Batch create/update, subscribe/unsubscribe, share links, reminders, external sync toggles |
+| `initiatives` | 🟡 | List, read, create, update, archive/unarchive, delete; attach/detach projects; initiative-to-initiative relations; initiative updates (list, read, create, update, archive/unarchive); discussions | Initiative labels, lead-team reassignment, relation reordering |
+| `projects` | 🟡 | List, read, create, update, archive/unarchive, delete; assign project labels by name (`--labels`, `--label-mode`, `--clear-labels`); discussions | Project updates (status posts), project-label CRUD, project relations, project status administration, Slack channel creation |
+| `documents` | 🟡 | List, read, create, update, delete | Content history, document full-text search, unarchive |
+| `milestones` | 🟡 | List, read, create, update (per project) | Delete, reordering/move between projects |
+| `attachments` | 🟡 | List on an issue, create from a URL, delete | Update, and the provider-specific link mutations (GitHub PR/issue, GitLab MR, Slack, Jira, Zendesk, Intercom, Front, Salesforce, Discord) |
+| `files` | 🟡 | Upload a file, download via signed URL | Delete uploads, image-from-URL, CSV export reports |
+| `teams` | 🟡 | List, read, create, update; list/add/remove members | Delete, workflow-state administration, triage responsibility, git automation, SLA configuration |
+| `labels` | 🟠 | Issue labels: list, read, create, update, delete; project labels: list (`--type project`) | Project-label create/update/delete, initiative labels, retire/restore |
+| `cycles` | 🟠 | List cycles, read a cycle with its issues | Create, update, archive, shift all, start upcoming cycle |
+| `users` | 🟠 | List workspace members | Read a single user, update, role changes, suspend/unsuspend, user settings, session management |
+| Integrations | 🔴 | — | All 73 integration root fields (65 mutations, 8 queries): Slack, GitHub, GitLab, Jira, Figma, Sentry, PagerDuty, Intercom, Salesforce, and more |
+| Organization & admin | 🔴 | — | Org settings, invites, domains, webhooks, OAuth apps, audit log, SSO |
+| Releases | 🔴 | — | Releases, release pipelines, stages, release notes |
+| Customers (CRM) | 🔴 | — | Customers, needs, tiers, customer statuses |
+| Views & templates | 🔴 | — | Custom views, favorites, templates, view preferences |
+| Notifications | 🔴 | — | Inbox, subscriptions, snooze, mark read, push subscriptions |
+| Agent sessions | 🔴 | — | Agent sessions, activities, skills, semantic search |
+| Roadmaps | 🔴 | — | Roadmaps and roadmap-to-project links |
+| Imports & exports | 🔴 | — | Jira/Asana/Clubhouse/GitHub/CSV import jobs |
+| Schedules | 🔴 | — | Time schedules and on-call rotations |
+
+The 🔴 rows are mostly workspace administration and integration plumbing — work an agent rarely does mid-task, and the main reason the API-wide coverage number is low while day-to-day coverage is not.
+
+> [!TIP]
+> Missing something you need day to day? [Open an issue](https://github.com/linearis-oss/linearis/issues) — the covered set is driven by what people actually reach for, not by API completeness.
+
+## Exit codes
+
+Every failure is JSON on stderr, and the exit code says which class of failure it is:
+
+| Code | Meaning | Payload |
+|---|---|---|
+| `0` | Success | Result JSON on stdout |
+| `1` | Application error — the request was well-formed but could not be fulfilled (entity not found, API rejection) | `{ "error": "<message>" }` |
+| `2` | Invalid invocation — unknown command or option, wrong number of arguments, or a command group named without a subcommand | Usage envelope (below) |
+| `42` | Authentication required — no usable token, or the stored one is invalid | `{ "error": "AUTHENTICATION_REQUIRED", … }` |
+
+Exit code `2` carries a machine-readable recovery path:
+
+```json
+{
+  "error": "UNKNOWN_COMMAND",
+  "message": "Unknown command \"get\" for \"linearis issues\".",
+  "suggestion": "Did you mean read?",
+  "command": "linearis issues",
+  "available_commands": ["read", "list", "create", "…", "usage"],
+  "instruction": "Run 'linearis issues usage' to list valid subcommands.",
+  "exit_code": 2
+}
+```
+
+`error` is one of `UNKNOWN_COMMAND`, `UNKNOWN_OPTION`, `MISSING_ARGUMENT`,
+`MISSING_REQUIRED_OPTION`, `MISSING_OPTION_ARGUMENT`, `TOO_MANY_ARGUMENTS`,
+`MISSING_SUBCOMMAND`, or `INVALID_USAGE`. `message` is always
+a single line. `suggestion` is present only when there is a close-enough near miss,
+and `available_commands` only when the failing scope has subcommands to choose from.
+
+Naming a command group without a subcommand (`linearis issues`, `linearis issues
+threads`) is a `MISSING_SUBCOMMAND` failure, not a request for help — use
+`linearis issues usage` for the machine-readable reference or `linearis issues
+--help` for the human one. `linearis` on its own still prints the overview.
 
 ## AI agent integration
 

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.11/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.5.6/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",
@@ -23,7 +23,7 @@
   },
   "linter": {
     "rules": {
-      "recommended": true,
+      "preset": "recommended",
       "complexity": {
         "useLiteralKeys": "off"
       },

@@ -280,8 +280,30 @@ outputSuccess(data);   // JSON.stringify(data, null, 2)
 
 // Error: written to stderr, exits with code 1
 outputError(error);    // { "error": "message" }
+
+// Authentication error: written to stderr, exits with code 42
+outputAuthError(error);   // { "error": "AUTHENTICATION_REQUIRED", ... }
+
+// Malformed invocation: written to stderr, exits with code 2
+outputUsageError(payload);  // { "error": "UNKNOWN_COMMAND", ... }
 ```
 
+Exit codes:
+
+| Code | Constant | Meaning |
+|---|---|---|
+| `0` | — | Success |
+| `1` | — | Application error (`outputError`) |
+| `2` | `USAGE_ERROR_CODE` | Invalid invocation (`outputUsageError`) |
+| `42` | `AUTH_ERROR_CODE` | Authentication required (`outputAuthError`) |
+
+`outputUsageError` is driven by `src/common/cli-errors.ts`, which classifies
+Commander parse failures. `interceptParseErrors(program)` installs a per-command
+`exitOverride` (capturing the failing `Command`, so the scope is exact) and
+silences Commander's plain-text stderr writes; `program.parseAsync().catch(handleParseFailure)`
+is the terminal handler. Both are wired at the bottom of `src/main.ts`, after
+every command is registered.
+
 ## Authentication
 
 For interactive setup, run `linearis auth login` — it opens Linear in the browser and stores the token encrypted in `~/.linearis/token`.