Skip to content
Back to search

linearis

CLI tool for Linear.app with JSON output, smart ID resolution, and optimized GraphQL queries. Designed for LLM agents and humans who prefer structured data.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/linearis-oss/linearis with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/linearis-oss/linearis'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/czottmann--linearis/badge.svg)](/listings/czottmann--linearis)

HTML

<a href="/listings/czottmann--linearis"><img src="/api/listings/czottmann--linearis/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install -g linearis

Requires **Node.js ≥ 22**. The `linearis` command is canonical; `linear` is a fully supported alias that runs the same CLI.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 22 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "linearis",
  3. "owner": {
  4. "name": "linearis-oss",
  5. "url": "https://github.com/linearis-oss/linearis"
  6. },
  7. "metadata": {
  8. "description": "Marketplace for the linearis Claude Code plugin.",
  9. "version": "1.1.0"
  10. },
  11. "plugins": [
  12. {
  13. "name": "linearis",
  14. "source": "./",
  15. "description": "Agent skill teaching agents to use the linearis Linear.app CLI.",
  16. "version": "1.1.0",
  17. "author": { "name": "linearis-oss" },
  18. "homepage": "https://github.com/linearis-oss/linearis",
  19. "license": "MIT"
  20. }
  21. ]
  22. }
README.md · README · 288 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # Linearis
  3. **A token-efficient [Linear.app](https://linear.app) CLI built for AI agents — and humans who like structured data.**
  4. [![NPM version](https://img.shields.io/npm/v/linearis.svg)](https://www.npmjs.com/package/linearis)
  5. [![Node version](https://img.shields.io/node/v/linearis.svg)](https://nodejs.org)
  6. [![CI](https://github.com/linearis-oss/linearis/actions/workflows/ci.yml/badge.svg)](https://github.com/linearis-oss/linearis/actions/workflows/ci.yml)
  7. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.md)
  8. [![skills.sh](https://skills.sh/b/linearis-oss/linearis)](https://skills.sh/linearis-oss/linearis)
  9. </div>
  10. Linearis is a command-line interface for Linear that speaks **JSON only**. It resolves human-friendly IDs (like `ENG-42` or a team name) to UUIDs for you, and exposes a two-tier `usage` system so an agent can discover exactly the commands it needs without loading the whole API surface into context.
  11. ```bash
  12. npm install -g linearis
  13. linearis auth login
  14. linearis issues list --limit 10
  15. ```
  16. ## Why Linearis?
  17. The official Linear MCP works well, but it costs ~13k tokens just by being connected — before an agent does anything. Linearis takes a different approach: agents discover capabilities on demand through a two-tier usage system.
  18. - `linearis usage` — a compact overview of every domain (~200 tokens).
  19. - `linearis <domain> usage` — the full reference for one domain (~300–500 tokens).
  20. 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.
  21. > [!NOTE]
  22. > 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.
  23. ## Features
  24. - **JSON-only output** — pipe into `jq`, no parsing of tables or prose.
  25. - **Smart ID resolution** — pass `ENG-42`, a team name, or a UUID interchangeably.
  26. - **Two-tier discovery** — self-documenting `usage` commands keep agent context small.
  27. - **Discussion threads** — first-class root/reply modeling on issues.
  28. - **File attachments** — upload and download with signed URLs.
  29. - **Broad domain coverage** — issues, projects, cycles, milestones, initiatives, documents, labels, teams, users, and more.
  30. ## Installation
  31. ```bash
  32. npm install -g linearis
  33. ```
  34. Requires **Node.js ≥ 22**. The `linearis` command is canonical; `linear` is a fully supported alias that runs the same CLI.
  35. ## Authentication
  36. The interactive flow opens Linear in your browser, walks you through creating an API key, and stores it encrypted in `~/.linearis/token`:
  37. ```bash
  38. linearis auth login
  39. ```
  40. Or provide a token directly:
  41. ```bash
  42. linearis --api-token <token> issues list # via flag
  43. LINEAR_API_TOKEN=<token> linearis issues list # via environment variable
  44. ```
  45. Token resolution order: `--api-token` flag → `LINEAR_API_TOKEN` env → `~/.linearis/token` → `~/.linear_api_token` (deprecated).
  46. ## Usage
  47. All output is JSON. Start with discovery, then act.
  48. ```bash
  49. # Discover what's available (~200 tokens)
  50. linearis usage
  51. # Drill into one domain for its full command reference
  52. linearis issues usage
  53. # List and search
  54. linearis issues list --limit 10
  55. linearis issues search "authentication bug"
  56. # Create an issue
  57. linearis issues create "Fix login flow" --team Platform --priority 2
  58. # Read an issue (includes embeds with signed download URLs)
  59. linearis issues read ENG-42
  60. ```
  61. For the complete reference of every command and flag, run `linearis <domain> usage`.
  62. ### Discussions
  63. Discussions are modeled as root threads with replies, rather than a flat comment list:
  64. ```bash
  65. # Start a discussion thread on an issue
  66. linearis issues discuss ENG-42 --body "Investigating this now"
  67. # List root discussion threads for an issue
  68. linearis issues discussions ENG-42
  69. # List replies in one root thread
  70. linearis issues replies <root-thread-id>
  71. # Reply to a thread (use a root discussion thread ID, not a reply ID)
  72. linearis issues reply <root-thread-id> --body "I found the root cause"
  73. ```
  74. ### Batch operations
  75. Both batch commands take a JSON document instead of flags, and apply it in a single transaction — either every issue changes or none does. Unknown keys are rejected rather than ignored, so a typo fails the command instead of quietly dropping a field.
  76. `issues batch create` takes an array with one object per issue, keys named after the `issues create` flags:
  77. ```json
  78. [
  79. { "title": "Fix login redirect loop", "team": "ENG", "labels": ["bug"] },
  80. { "title": "Document the SSO flow", "team": "ENG", "project": "Q3 Auth" }
  81. ]
  82. ```
  83. `issues batch update` takes the targets plus the one patch they share, keys named after the `issues update` flags, where `null` clears a field:
  84. ```json
  85. {
  86. "issues": ["ENG-42", "ENG-43"],
  87. "patch": { "status": "In Progress", "assignee": "alice", "cycle": null }
  88. }
  89. ```
  90. ```bash
  91. linearis issues batch create --file issues.json
  92. linearis issues batch update --file patch.json
  93. # - reads stdin, and --json takes the document inline for one-offs
  94. generate-issues | linearis issues batch create --file -
  95. linearis issues batch update --json '{"issues":["ENG-42"],"patch":{"status":"Done"}}'
  96. ```
  97. Both formats are published as JSON Schema (draft 2020-12) in [`schemas/`](schemas/), shipped in the npm package and served raw from the default branch — point a validator or an editor at them to check a document before spending an API call on it.
  98. A schema is the input contract only: it cannot know your team's workflow states, label names, or estimation scale, so a document that validates can still be rejected when a name does not resolve.
  99. ## Coverage
  100. Linear's GraphQL API exposes **520 root operations** (159 queries, 361 mutations). Linearis wires **114 of them** directly, plus a number of nested reads — chosen to cover planning and issue work end to end rather than the whole API.
  101. Both figures are checkable rather than asserted: `npm run count:root-fields -- --verify` parses `graphql/**/*.graphql` and cross-checks the result against a live introspection of the schema.
  102. 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.
  103. **Legend** — ✅ complete for practical purposes · 🟡 core operations, known gaps · 🟠 read-only or narrow slice · 🔴 no CLI surface yet
  104. | Area | Extent | What you can do | Not covered |
  105. |---|---|---|---|
  106. | `auth` | ✅ | Interactive login, token status, logout | — |
  107. | Discussions | ✅ | Root threads and replies on issues, projects, and initiatives; edit, delete, resolve/unresolve; emoji reactions on any of them | Custom workspace emoji management, and comment threads on a status update — `CommentCreateInput.projectUpdateId` makes an update its own discussion surface, which neither `projects updates` nor `initiatives updates` exposes |
  108. | `issues` | ✅ | List, filter, full-text search, read, create, update, batch create/update, archive/unarchive, delete/restore, snooze; assign labels/assignee/delegate/state/priority/project/cycle/team (including moves between teams); subscribe/unsubscribe, share/unshare, reminders; find the issue for a git branch (`from-branch`); relations (list/add/remove); activity history | Deliberately excluded: the AI-assist and integration-suggestion queries (Figma file lookup, filter/repository suggestions, title-from-customer-request) — see the Integrations row — and `issuePriorityValues`, a static list already in the help text |
  109. | `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 |
  110. | `projects` | ✅ | List, full-text search, read, create, update, delete (trash) and unarchive (restore), disable external sync; assign project labels by name (`--labels`, `--label-mode`, `--clear-labels`); status updates (list, read, create, edit, archive/unarchive, remind); dependency relations (list, read, add, update, remove); administer the workspace project status flow (`projects statuses`); discussions; activity timeline | Deliberately excluded: Slack-channel creation and the AI filter suggestion, which are `[Internal]` integration plumbing — see the Integrations row. Project labels live under `labels --type project`; milestone delete/move under `milestones` |
  111. | `documents` | 🟡 | List, read, create, update, delete | Content history, document full-text search, unarchive |
  112. | `milestones` | 🟡 | List, read, create, update (per project) | Delete, reordering/move between projects |
  113. | `attachments` | 🟡 | List on an issue, create from a URL, delete, disable external sync | Update, and the provider-specific link mutations (GitHub PR/issue, GitLab MR, Slack, Jira, Zendesk, Intercom, Front, Salesforce, Discord) |
  114. | `files` | 🟡 | Upload a file, download via signed URL | Delete uploads, image-from-URL, CSV export reports |
  115. | `teams` | 🟡 | List, read, create, update; list/add/remove members | Delete, workflow-state administration, triage responsibility, git automation, SLA configuration |
  116. | `labels` | 🟡 | Issue and project labels alike (`--type issue\|project`): list, read, create, update, delete, retire/restore; label groups (`--group`, `--parent`) | Initiative labels |
  117. | `cycles` | 🟠 | List cycles, read a cycle with its issues | Create, update, archive, shift all, start upcoming cycle |
  118. | `users` | 🟠 | List workspace members | Read a single user, update, role changes, suspend/unsuspend, user settings, session management |
  119. | Integrations | 🔴 | — | All 70 integration root fields (62 mutations, 8 queries): Slack, GitHub, GitLab, Jira, Figma, Sentry, PagerDuty, Intercom, Salesforce, and more. Also the `[Internal]` per-entity integration plumbing excluded from the `issues` and `projects` rows: Slack channel creation and dismissal on a project, Slack/Teams/Jira project posts, and the AI-assist suggestion queries (issue and project filter suggestions, Figma file lookup, title-from-customer-request) |
  120. | Organization & admin | 🔴 | — | Org settings, invites, domains, webhooks, OAuth apps, audit log, SSO |
  121. | Releases | 🔴 | — | Releases, release pipelines, stages, release notes |
  122. | Customers (CRM) | 🔴 | — | Customers, needs, tiers, customer statuses |
  123. | Views & templates | 🔴 | — | Custom views, favorites, templates, view preferences |
  124. | Notifications | 🔴 | — | Inbox, subscriptions, snooze, mark read, push subscriptions |
  125. | Agent sessions | 🔴 | — | Agent sessions, activities, skills, semantic search |
  126. | Roadmaps | 🔴 | — | Roadmaps and roadmap-to-project links. `roadmapToProject*` is deprecated in favour of `initiativeToProject*`, which `initiatives` already wires |
  127. | Imports & exports | 🔴 | — | Jira/Asana/Clubhouse/GitHub/CSV import jobs |
  128. | Schedules | 🔴 | — | Time schedules and on-call rotations |
  129. 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.
  130. > [!TIP]
  131. > 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.
  132. ## Exit codes
  133. Every failure is JSON on stderr, and the exit code says which class of failure it is:
  134. | Code | Meaning | Payload |
  135. |---|---|---|
  136. | `0` | Success | Result JSON on stdout |
  137. | `1` | Application error — the request was well-formed but could not be fulfilled (entity not found, API rejection) | `{ "error": "<message>" }` |
  138. | `2` | Invalid invocation — unknown command or option, wrong number of arguments, or a command group named without a subcommand | Usage envelope (below) |
  139. | `42` | Authentication required — no usable token, or the stored one is invalid | `{ "error": "AUTHENTICATION_REQUIRED", … }` |
  140. Exit code `2` carries a machine-readable recovery path:
  141. ```json
  142. {
  143. "error": "UNKNOWN_COMMAND",
  144. "message": "Unknown command \"get\" for \"linearis issues\".",
  145. "suggestion": "Did you mean read?",
  146. "command": "linearis issues",
  147. "available_commands": ["read", "list", "create", "…", "usage"],
  148. "instruction": "Run 'linearis issues usage' to list valid subcommands.",
  149. "exit_code": 2
  150. }
  151. ```
  152. `error` is one of `UNKNOWN_COMMAND`, `UNKNOWN_OPTION`, `MISSING_ARGUMENT`,
  153. `MISSING_REQUIRED_OPTION`, `MISSING_OPTION_ARGUMENT`, `TOO_MANY_ARGUMENTS`,
  154. `MISSING_SUBCOMMAND`, or `INVALID_USAGE`. `message` is always
  155. a single line. `suggestion` is present only when there is a close-enough near miss,
  156. and `available_commands` only when the failing scope has subcommands to choose from.
  157. Naming a command group without a subcommand (`linearis issues`, `linearis issues
  158. threads`) is a `MISSING_SUBCOMMAND` failure, not a request for help — use
  159. `linearis issues usage` for the machine-readable reference or `linearis issues
  160. --help` for the human one. `linearis` on its own still prints the overview.
  161. ## AI agent integration
  162. Linearis is structured around a **discover-then-act** pattern that matches how agents work:
  163. 1. **Discover** — `linearis usage` returns a compact overview of all domains. The agent reads it once.
  164. 2. **Drill down** — `linearis <domain> usage` gives the full reference for a single domain. The agent loads only what it needs.
  165. 3. **Execute** — every command returns structured JSON. No table or prose parsing.
  166. The agent never loads the full API surface into context — it pays for what it uses, one domain at a time.
  167. ### Linearis vs. Linear MCP
  168. | | Linearis | Linear MCP |
  169. |---|---|---|
  170. | Context cost | ~500–700 tokens per interaction | ~13k tokens on connect |
  171. | Coverage | Common operations (issues, discussions, cycles, docs, files) | Full Linear API |
  172. | Output | JSON via stdout | Tool-call responses |
  173. | Setup | `npm install -g linearis` + Bash tool | MCP server connection |
  174. Use Linearis when token efficiency matters and you work primarily with issues and related data. Use the MCP when you need full API coverage or tight tool-call integration.
  175. ### Agent skill
  176. Linearis ships an agent skill (following the [agentskills.io](https://agentskills.io) standard) so your agent knows how to use it — no prompt to paste. The skill preflights the install, advisory-checks for updates, then follows the discover-then-act protocol above.
  177. **Any harness (recommended)** — Vercel's skills CLI installs into the right place for 70+ agents and lists it on [skills.sh](https://skills.sh):
  178. ```bash
  179. npx skills add linearis-oss/linearis
  180. ```
  181. **Claude Code** — native plugin:
  182. ```
  183. /plugin marketplace add linearis-oss/linearis
  184. /plugin install linearis@linearis
  185. ```
  186. **OpenAI Codex** — `npx skills add linearis-oss/linearis` installs to `~/.agents/skills/`; invoke with `/skills` or `$`.
  187. **pi** — `npx skills add linearis-oss/linearis` (or drop `skills/linearis/` into `.pi/skills/`); invoke `/skill:linearis`.
  188. **Google Antigravity** — `npx skills add linearis-oss/linearis` installs to `.agents/skills/`; auto-discovered from the skill list.
  189. ## Documentation
  190. - [MIGRATION_2026.4.9.md](MIGRATION_2026.4.9.md) — migrating from the deprecated `comments` domain to discussions (v2026.4.9).
  191. - [`docs/`](docs/) — architecture, development, testing, and build-system references.
  192. - [`schemas/`](schemas/) — JSON Schemas for the commands that take a JSON document ([batch operations](#batch-operations)).
  193. - [`docs/ci-run-model.md`](docs/ci-run-model.md) — the authoritative CI/release trigger matrix.
  194. - [CONTRIBUTING.md](CONTRIBUTING.md) — contributor guidelines.
  195. - [SECURITY.md](SECURITY.md) — how to report security issues.
  196. ## Contributors
  197. <a href="https://github.com/linearis-oss/linearis/graphs/contributors">
  198. <img src="https://contrib.rocks/image?repo=linearis-oss/linearis" alt="Contributors" />
  199. </a>
  200. Made with [contrib.rocks](https://contrib.rocks).
  201. ## License
  202. [MIT](LICENSE.md)
  203. This project is neither affiliated with nor endorsed by Linear.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.