linearctl

Agent-first CLI for the Linear API. Built to be used by LLM coding agents like Claude Code and Codex, but works just as well for humans at the terminal.

Three command layers: curated commands for common workflows, a generated API layer for full schema coverage, and raw GraphQL as a fallback. Human-readable output is the default; pass --json or --json-envelope for stable machine-readable contracts that agents can rely on.

Install

curl -fsSL https://raw.githubusercontent.com/qwrobins/linearctl/main/install.sh | sh

Or install a specific version:

LINEAR_VERSION=v0.8.4 curl -fsSL https://raw.githubusercontent.com/qwrobins/linearctl/main/install.sh | sh

On Debian/Ubuntu, the installer automatically uses the .deb package. To skip deb and install the raw binary instead:

LINEAR_NO_DEB=1 curl -fsSL https://raw.githubusercontent.com/qwrobins/linearctl/main/install.sh | sh

Or build from source:

bun run build:binary
cp dist/linearctl ~/.local/bin/linearctl

The compiled binary has no runtime dependencies. Building from source requires Bun.

Quick start

Point your agent at the install guide and it will handle everything:

Install and set up linearctl using https://raw.githubusercontent.com/qwrobins/linearctl/main/INSTALL.md

Or do it step by step:

# Install
curl -fsSL https://raw.githubusercontent.com/qwrobins/linearctl/main/install.sh | sh

# Install agent skills
linearctl skills install

Then ask your agent:

Set up linearctl with my Linear API key. My key is in the LINEAR_API_KEY environment variable.

Or set up manually:

API key

Create an API key at https://linear.app/settings/api, then:

export LINEAR_API_KEY=lin_api_...
linearctl auth login --profile work --api-key-env LINEAR_API_KEY --set-default
linearctl team list
linearctl team get <team-key> --set-default

Your key is now stored in ~/.config/linear/credentials (permissions 0600) and loaded automatically on every run. No env vars to export in your shell profile, no secrets in dotfiles. You only need LINEAR_API_KEY for that initial login.

OAuth (browser-based)

Create an OAuth app at https://linear.app/settings/api/applications and register http://127.0.0.1:8765/oauth/callback as its redirect URI, then:

linearctl auth login --profile work --oauth --oauth-client-id <id> --set-default

Usage

Profile metadata is in ~/.config/linear/config. See auth and profiles for the full file layout.

linearctl issue list
linearctl issue list --state "In Progress"
linearctl issue create --title "Fix pagination bug" --priority 2
linearctl issue get INF-42
linearctl auth whoami

Add --json to any command for machine-readable output (see output modes). For command discovery, agents can inspect the stable curated metadata with linearctl --metadata curated --json.

Commands

Group	Operations
issue	get, view, create, list, search, update, close, delete, assign, comment, attach-slack, bulk-update, bulk-close, bulk-archive, bulk-delete, bulk-assign
project	get, list, create, update, create-with-issues, delete
cycle	get, list, current, create, update, archive, delete
team	get, list, members
user	get, me, list
label	get, list, create, delete
state	get, list, create, archive, delete
project-status	list, get, create, delete
comment	list, create, update, delete
attachment	list, create, delete
file	upload, url, download
auth	login, logout, status, switch, whoami
schema	version, pull, check
workspace	list
skills	install, list
api	Generated commands for any Linear API resource
gql	Raw GraphQL queries and mutations

Profiles

Credentials are stored in AWS CLI-style INI files at ~/.config/linear/:

~/.config/linear/
  config          # default profile, workspace metadata
  credentials     # API keys and OAuth tokens (0600 permissions)

Each profile is a named section. Resolution order: --profile flag > LINEAR_PROFILE env var > configured default. See auth and profiles for the full file layout and OAuth setup.

Output modes

Flag	Description
(none)	Human-readable (not stable, not for parsing)
--json	Data-only JSON (stable contract)
--json-envelope	Envelope with ok, data, pageInfo, errors, meta
--jsonl	Streaming, one JSON object per line; requires --all or --max <n>
--raw	Exact GraphQL response (gql only)

See docs/output-modes.md.

Docs

• Getting started
• Command reference
• Auth and profiles
• Output modes
• Filtering and pagination
• Agent usage
• Schema and generated API

License

MIT