linearis

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.

npm install -g linearis
linearis auth login
linearis issues list --limit 10

Why Linearis?

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.

• linearis usage — a compact overview of every domain (~200 tokens).
• linearis <domain> usage — the full reference for one domain (~300–500 tokens).

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.

Features

• JSON-only output — pipe into jq, no parsing of tables or prose.
• Smart ID resolution — pass ENG-42, a team name, or a UUID interchangeably.
• Two-tier discovery — self-documenting usage commands keep agent context small.
• Discussion threads — first-class root/reply modeling on issues.
• File attachments — upload and download with signed URLs.
• Broad domain coverage — issues, projects, cycles, milestones, initiatives, documents, labels, teams, users, and more.

Installation

npm install -g linearis

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

Authentication

The interactive flow opens Linear in your browser, walks you through creating an API key, and stores it encrypted in ~/.linearis/token:

linearis auth login

Or provide a token directly:

linearis --api-token <token> issues list        # via flag
LINEAR_API_TOKEN=<token> linearis issues list    # via environment variable

Token resolution order: --api-token flag → LINEAR_API_TOKEN env → ~/.linearis/token → ~/.linear_api_token (deprecated).

Usage

All output is JSON. Start with discovery, then act.

# Discover what's available (~200 tokens)
linearis usage

# Drill into one domain for its full command reference
linearis issues usage

# List and search
linearis issues list --limit 10
linearis issues search "authentication bug"

# Create an issue
linearis issues create "Fix login flow" --team Platform --priority 2

# Read an issue (includes embeds with signed download URLs)
linearis issues read ENG-42

For the complete reference of every command and flag, run linearis <domain> usage.

Discussions

Discussions are modeled as root threads with replies, rather than a flat comment list:

# Start a discussion thread on an issue
linearis issues discuss ENG-42 --body "Investigating this now"

# List root discussion threads for an issue
linearis issues discussions ENG-42

# List replies in one root thread
linearis issues replies <root-thread-id>

# Reply to a thread (use a root discussion thread ID, not a reply 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

AI agent integration