lin — Linear CLI

A fast, native CLI for Linear. Manage issues, projects, cycles, and more from your terminal.

Install

Homebrew (macOS)

brew install aaronkwhite/tap/lin

Cargo

cargo install lincli

Pre-built Binaries

Download from GitHub Releases — available for macOS (Intel & Apple Silicon) and Linux (x86 & ARM).

From Source

git clone https://github.com/aaronkwhite/linear-cli.git
cd linear-cli
cargo install --path .

Setup

Get your API key from Linear Settings > API > Personal API keys, then:

lin config set-token

Or set it via environment variable:

export LINEAR_API_KEY="lin_api_..."

Usage

lin --help                                              # Show all commands
lin issues list --team ENG                              # List issues for a team
lin issues list --state "In Progress"                   # Filter by state
lin issues list --label bug --label urgent              # Filter by labels
lin issues get ENG-123                                  # Get issue details
lin issues update ENG-123 --team HP                     # Move issue to another team
lin projects list                                       # List projects
lin projects update "My Project" --add-team ENG         # Add team to project
lin cycles add ENG-123 --cycle <id>                     # Add issue to specific cycle
lin teams list                                          # List teams
lin api '{ viewer { id displayName } }'                 # Raw GraphQL query

Global Flags

Commands

Using with Claude Code

Install the skill (recommended)

A Claude Code skill ships with this repo that teaches Claude how to use lin for any Linear task — creating issues, querying status, managing projects and cycles, and more.

cp -r .claude/skills/lin ~/.claude/skills/lin

The skill handles tool selection (lin first, Linear MCP as fallback), includes a full command reference, and documents which operations require MCP vs. lin.

Manual CLAUDE.md snippet

If you prefer a lightweight setup, add this to your project's CLAUDE.md:

## Linear

Use the `lin` CLI for all Linear operations. Always use `--json` for structured output.

- `lin issues list --team ENG --json` — list issues
- `lin issues get ENG-123 --json` — get issue details
- `lin issues create --team ENG --title "Title" --json` — create issue
- `lin issues update ENG-123 --status "Done" --json` — update status
- `lin search "query" --json` — search across issues, projects, docs

Run `lin <command> --help` for full flag details.

Why CLI over MCP?

MCP servers inject the full JSON schema for every tool into the LLM's context window on every message — whether those tools are used or not. This creates a permanent tax on every interaction.

Token Cost

Source: Scalekit benchmark, 75 runs, Claude Sonnet 4, p < 0.05

Why the Gap Is So Large

MCP loads the entire API surface into context on every message. Linear's official MCP server injects 22 tool schemas (~19,659 tokens) before you ask a single question. Connect 3 MCP servers and you can lose 72% of your context window at idle.

A CLI pays only for what it uses. lin issues list --team ENG --json costs ~15 tokens for the command string. The other 200+ subcommands cost nothing because they're never loaded.

Reliability

Source: Scalekit benchmark, 25 runs per method

Industry Trend

• Perplexity dropped MCP internally, citing context window waste and authentication issues (source)
• mcp2cli (wraps MCP servers as CLIs) measured 96-99% token reduction (source)
• "MCP is dead, long live the CLI" hit the Hacker News front page (discussion)

When MCP Still Makes Sense

MCP works well for non-technical users in chat interfaces where CLI access isn't available, or for services that don't have a CLI wrapper. For developer tooling where you have shell access, CLI wins on every axis.

Development

cargo build                           # Build
cargo test                            # Run tests (smoke + unit)
LINEAR_API_KEY=... cargo test -- --ignored  # Run integration tests

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

MIT