Introduction

lin is the Linear CLI: a single, fast, native binary that turns Linear's GraphQL API into a predictable, scriptable command surface. It is first-class for two audiences at once - a person at a terminal, and an AI agent running headless.

Why lin exists

Linear has an excellent API but no first-class command line. Scripts, cron jobs, CI pipelines, and coding agents that want to file an issue, attach a screenshot, or move a card otherwise hand-roll GraphQL or drive a browser. lin fills that gap: one binary, the same shapes everywhere, safe to re-run.

Why a CLI, not just the MCP

The official Linear MCP server is the easy way to give an agent Linear access, but it has a cost. Its tool schema is loaded into the model's context and stays there for the whole session, and every call is an extra round-trip. lin is a different trade:

• Lighter on tokens. The agent does not carry a large tool schema in context. It calls lin describe on demand to learn exactly the command it needs, then invokes it over the shell.
• Faster. A native binary called directly, with no MCP server hop.
• Scriptable everywhere. The same binary runs in a terminal, a cron job, or a CI step, not only inside an MCP-aware client.

An agent can lean on lin instead of the MCP and spend its context on the task, not on tool definitions. See For AI agents for the invariants to load.

What you get

• JSON-first. Data on stdout, messages on stderr. --output json|ndjson|table and --fields shape the payload; a machine is always assumed to be reading.
• Predictable over clever. Resource-first grammar (lin <resource> <verb>), sysexits exit codes, cursor pagination, and --dry-run on every mutation. Learn one command and the rest follow.
• Discoverable at runtime. lin describe emits the whole surface as JSON; these docs are generated from it, so they never drift from the binary.
• Comprehensive through codegen. Commands are typed GraphQL operations compiled against a vendored schema, so coverage is broad without being brittle.
• Safe with secrets. API keys come from the environment or an XDG config file, never from flags, and are masked in output. Mutations only ever change the fields you name; unset never means "clear".

Get started

Install the binary, authenticate with a Linear API key, and run your first commands:

• Installation - Homebrew, go install, or from a clone
• Authentication - your Linear personal API key
• Quickstart - the first commands and the grammar behind them
• Command reference - every command, grouped by resource