lin

Linear CLI for humans and LLMs

Language
Go
Version
0.36.4
License
PolyForm Perimeter 1.0.0
Category
CLI Tool

A Linear CLI built for structured output and LLM-shaped interaction, covering issues, projects, initiatives, documents, customers and their requests, cycles, teams, labels and files — plus a raw GraphQL escape hatch. Runs as an MCP server that several named people can share, each pinned to their own workspace and failing closed if identity is missing.

Features

01

Structured output — JSONL for lists and searches, NDJSON for multi-id gets, JSON or YAML on request, errors to stderr with fixable_by and a hint

02

LLM-optimized docs — lin usage in under 1,000 tokens, with a fuller usage page per command group

03

Smart IDs — accepts issue keys, UUIDs or URL fragments interchangeably

04

Customers and requests, first-class — list by tier, status, owner, domain or revenue, and pull the feedback attached to an issue or project

05

Rich integration attachments — link GitHub PRs and issues, GitLab MRs, Slack threads (optionally synced) and Discord messages

06

A pretty mode for humans — --format pretty renders a terminal card for reading an entity, and --full adds relations and comments

07

Item-level misses do not lose the batch — a missing id becomes an @unresolved line on stdout with exit 0; only command-level failures exit non-zero

08

Multi-user MCP — one lin mcp server serves several people, each principal's calls pinned to their own stored workspace

09

Fails closed on identity — LIN_REQUIRE_IDENTITY means a call missing its identity is refused rather than falling back to the operator's default

10

Browser self-enrollment — a principal minted without a binding pastes their own Linear API key during OAuth approval; it is validated, stored keychain-first, and bound automatically

11

One slot, one organization — a key resolving to a different Linear org is refused rather than silently re-pointing the slot

12

Read-back for filesystem-free clients — a built-in read-only fs MCP tool returns downloaded files, images as image blocks

13

Zero runtime dependencies — a single static Go binary

Install

Homebrew

>_
$ brew install shhac/tap/lin

AI Agent Skill

>_
$ npx skills add shhac/agent-skills --skill lin --global

GitHub Release (macOS)

>_
$ curl -L https://github.com/shhac/lin/releases/latest/download/lin-darwin-arm64.tar.gz | tar xz

Build from Source

>_
$ git clone https://github.com/shhac/lin.git && cd lin && make build

Getting Started

lin needs a Linear personal API key. For CI and agent use an environment variable is the simplest path; for interactive use, store it and let lin keep it in the keychain.

01 · Generate an API key

Linear Settings > Account > Security > Personal API Keys. The key starts lin_api_.

02 · Set it for CI or agent use

>_
$ export LINEAR_API_KEY="lin_api_..."

The recommended path when something other than a person is running the command.

03 · Or store it locally

>_
$ lin auth login lin_api_...

Stored keychain-first. Add --alias to keep several workspaces side by side and switch with lin auth workspace switch.

04 · Verify access

>_
$ lin auth status

Then lin usage for the overview, or lin issue usage for full detail on flags, valid values and return fields.

Usage

>_ Search issues
$ lin issue search "auth bug"
>_ List filtered issues
$ lin issue list --team ENG --status "In Progress"
>_ Read one issue as a terminal card
$ lin issue get ENG-123 --format pretty --full
>_ Create an issue
$ lin issue new "Fix login redirect" --team ENG --priority high
>_ Attach a PR to an issue
$ lin issue attachment add ENG-123 --github-pr https://github.com/org/repo/pull/42
>_ Customer feedback behind a project
$ lin project requests PROJ-ID --important
>_ Customers by tier
$ lin customer list --tier enterprise
>_ Raw GraphQL escape hatch
$ lin api query 'query { viewer { id name } }'