CLI tool for Linear.app optimized for AI agents. JSON output, smart ID resolution, token-efficient usage commands, and a discover-then-act workflow that keeps agent context small. Works just as well for humans who prefer structured data on the command line.
The official Linear MCP works fine, but it eats up ~13k tokens just by being connected -- before the agent does anything. Linearis takes a different approach: instead of exposing the full API surface upfront, agents discover what they need through a two-tier usage system. linearis usage gives an overview in ~200 tokens, then linearis <domain> usage provides the full reference for one area in ~300-500 tokens. A typical agent interaction costs ~500-700 tokens of context, not ~13k.
The trade-off is coverage. An MCP exposes the entire Linear API; Linearis covers the operations that matter for day-to-day work with issues, comments, cycles, documents, and files. If you need to manage custom workflows, integrations, or workspace settings, the MCP is the better choice.
This project scratches my own itches, and satisfies my own usage patterns of working with Linear: I do work with tickets/issues and comments on the command line; I do not manage projects or workspaces etc. there. YMMV.
npm install -g linearisRequires Node.js >= 22.
linearis auth loginThis opens Linear in your browser, guides you through creating an API key, and stores the token encrypted in ~/.linearis/token.
Alternatively, provide a token directly:
# Via CLI flag
linearis --api-token <token> issues list
# Via environment variable
LINEAR_API_TOKEN=<token> linearis issues listToken resolution order: --api-token flag > LINEAR_API_TOKEN env > ~/.linearis/token > ~/.linear_api_token (deprecated).
All output is JSON. Pipe through jq or similar for formatting.
# Discovery
linearis usage # overview of all domains
linearis issues usage # detailed usage for one domain# List recent issues
linearis issues list --limit 10
# Search issues by text
linearis issues list --query "authentication" --team Platform
# Create an issue
linearis issues create "Fix login timeout" --team Backend \
--assignee "Jane Doe" --labels "Bug,Critical" --priority 1 \
--description "Users report session expiry after 5 minutes"
# Read issue details (supports ABC-123 identifiers)
linearis issues read DEV-456
# Update status, priority, labels
linearis issues update ABC-123 --status "In Review" --priority 2
linearis issues update DEV-789 --labels "Frontend,UX" --label-mode add
linearis issues update ABC-123 --clear-labels
# Parent-child relationships
linearis issues update SUB-001 --parent-ticket EPIC-100
# Issue relations
linearis issues create "Blocked task" --team Backend --blocked-by DEV-123
linearis issues update ABC-123 --blocks DEV-456
linearis issues update ABC-123 --relates-to DEV-789
linearis issues update ABC-123 --remove-relation DEV-456linearis comments create ABC-123 --body "Fixed in PR #456"# Create a document (optionally link to a project and/or issue)
linearis documents create --title "API Design" --content "# Overview..."
linearis documents create --title "Bug Analysis" --project "Backend" --issue ABC-123
# List documents
linearis documents list
linearis documents list --project "Backend"
linearis documents list --issue ABC-123
# Read, update, delete
linearis documents read <document-id>
linearis documents update <document-id> --title "New Title" --content "Updated content"
linearis documents delete <document-id># List cycles for a team
linearis cycles list --team Backend --limit 10
# Active cycle only
linearis cycles list --team Backend --active
# Active cycle +/- 3 neighbors
linearis cycles list --team Backend --window 3
# Read cycle details
linearis cycles read "Sprint 2025-10" --team Backend# List milestones in a project
linearis milestones list --project "Backend"
# Read milestone details
linearis milestones read "Beta Release" --project "Backend"
# Create and update milestones
linearis milestones create "v2.0" --project "Backend" --target-date 2025-06-01
linearis milestones update "v2.0" --project "Backend" --description "Major release"# Download a file from Linear storage
linearis files download "https://uploads.linear.app/.../file.png" --output ./screenshot.png
# Upload and reference in a comment
URL=$(linearis files upload ./bug.png | jq -r .assetUrl)
linearis comments create ABC-123 --body "Screenshot: "linearis projects list
linearis labels list --team Backend
linearis teams list
linearis users list --activeAll list commands support cursor-based pagination:
linearis issues list --limit 25
# Response includes pageInfo with endCursor and hasNextPage
linearis issues list --limit 25 --after "cursor-from-previous-response"The CLI is structured around a discover-then-act pattern that matches how agents work:
- Discover --
linearis usagereturns a compact overview of all domains (~200 tokens). The agent reads this once to understand what's available. - Drill down --
linearis <domain> usagegives the full command reference for one domain (~300-500 tokens). The agent only loads what it needs. - Execute -- All commands return structured JSON. No parsing of human-readable tables or prose.
This means the agent never loads the full API surface into context. It pays for what it uses, one domain at a time.
| Linearis | Linear MCP | |
|---|---|---|
| Context cost | ~500-700 tokens per interaction | ~13k tokens on connect |
| Coverage | Common operations (issues, comments, cycles, docs, files) | Full Linear API |
| Output | JSON via stdout | Tool call responses |
| Setup | npm install -g linearis + bash tool |
MCP server connection |
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.
## Linear (project management)
Tool: `linearis` CLI via Bash. All output is JSON.
Discovery: Run `linearis usage` once to see available domains. Run `linearis <domain> usage` for full command reference of a specific domain. Do NOT guess flags or subcommands -- check usage first.
Ticket format: "ABC-123". Always reference tickets by their identifier.
Workflow rules:
- When creating a ticket, ask the user which project to assign it to if unclear.
- For subtasks, inherit the parent ticket's project by default.
- When a task in a ticket description changes status, update the description.
- For progress beyond simple checkbox changes, add a comment instead of editing the description.
File handling: `issues read` returns an `embeds` array with signed download URLs and expiration timestamps. Use `files download` to retrieve them. Use `files upload` to attach new files, then reference the returned URL in comments or descriptions.Add this (or a version adapted to your workflow) to your AGENTS.md or CLAUDE.md so every agent session has it in context automatically.
Want to contribute? See CONTRIBUTING.md.
Fabian Jocks -- github.com/iamfj | linkedin.com/in/fabianjocks
Carlo Zottmann -- c.zottmann.dev | github.com/czottmann
Carlo created Linearis and drove its early development. As interest in the project grew, he handed maintenance over to Fabian.
This project is neither affiliated with nor endorsed by Linear.
Carlo doesn't accept sponsoring in the "GitHub sponsorship" sense1 but next to his own apps, he also sells "Tokens of Appreciation". Any support is appreciated!
Tip
Carlo makes Shortcuts-related macOS & iOS productivity apps like Actions For Obsidian, Browser Actions (which adds Shortcuts support for several major browsers), and BarCuts (a surprisingly useful contextual Shortcuts launcher). Check them out!
MIT. See LICENSE.md.
Footnotes
-
Apparently, the German revenue service is still having some fits over "money for nothing??". ↩