linear-cli

Agent-first CLI for Linear. Built for AI coding agents and developers who live in the terminal.

Linear has no official CLI. If you're an AI agent that needs structured data from Linear, or a developer who wants to manage issues without leaving the terminal, this fills the gap. JSON stdout, errors to stderr, dry-run on every mutation.

Install

npm install -g @efetoker/linear-cli

Or run from source:

git clone https://github.com/efetoker/linear-cli.git
cd linear-cli
npm install && npm run build
npm link

Setup

linear init

This prompts for your Linear API key, optionally verifies it against the API, and writes a config file to ~/.config/linear-cli/config.json (XDG paths on Linux).

Get your API key at linear.app/settings/api under "Personal API keys".

Use --no-verify to skip the verification step.

Quick Start

linear teams list                                        # see your teams
linear issues list --team ENG                            # list issues in a team
linear issues search "login bug"                         # full-text search
linear issues get ENG-123                                # get a single issue
linear --dry-run issues create --team ENG --title "Fix auth"  # preview
linear issues create --team ENG --title "Fix auth"       # create for real
linear issues assign ENG-123 [email protected]            # assign by email
linear issues state ENG-123 "In Progress"                # change state
linear comments add ENG-123 --body "Done"                # add a comment
linear comments reply <comment-id> --body "Thanks"       # reply to a comment
linear users me                                          # check your identity

For AI Agents

This CLI is designed to be used by AI coding agents (Claude Code, Codex, Gemini CLI, etc.) as a tool for interacting with Linear.

What makes it agent-friendly:

• All output is JSON on stdout — easy to parse
• Errors go to stderr with non-zero exit code — easy to detect
• Every command has detailed --help — agents can self-discover usage
• --dry-run on all mutations — agents can preview before acting
• --pretty for readable output during debugging
• Flag aliases for all positional args — agents can use --issue-id, --query, --comment-id etc. instead of positional arguments (both forms work)
• Fuzzy name resolution — --team ENG or --team Engineering both work, with clear errors on ambiguous matches

Minimal system prompt snippet:

You have access to the `linear` CLI for managing Linear issues and projects.
Use `linear <group> --help` to discover commands.
Always use `--dry-run` before mutating commands.
Output is JSON on stdout; errors go to stderr.

Commands

| Group | Subcommands | Description | |-------|-------------|-------------| | init | — | Interactive API key setup | | issues | list, get, search, create, update, assign, state, delete | Full issue CRUD | | comments | list, add, reply | Comments with threading | | teams | list, get | Team discovery | | users | list, me | User discovery | | labels | list | Label discovery (workspace or team-scoped) | | states | list | Workflow state discovery (workspace or team-scoped) | | projects | list, get | Project discovery |

Use linear <group> <command> --help for detailed usage and examples.

Global Flags

--pretty     Pretty-print JSON output
--dry-run    Preview mutations without executing
--debug      Log API requests to stderr
--version    Show version

Key Behaviors

• Flag aliases — every positional argument also accepts a --flag form. issues get ENG-123 and issues get --issue-id ENG-123 are equivalent.
• Fuzzy resolution — team, user, state, label, and project names are resolved case-insensitively. Ambiguous matches return a clear error listing all candidates.
• --label is repeatable — issues create --label Bug --label Urgent attaches multiple labels.
• --body-file — comments add and comments reply accept --body-file path/to/file.md as an alternative to --body.
• issues delete archives the issue (Linear's standard deletion). Requires --yes in non-interactive mode.

Output Format

Every command returns one of three JSON envelopes on stdout:

// Success
{ "ok": true, "data": { ... }, "meta": { "command": "issues.list" } }

// Dry run
{ "ok": true, "dryRun": true, "data": { "operation": "issues.create", "target": { ... }, "input": { ... } } }

// Error (on stderr)
error [AUTH_ERROR]: No API key configured. Run `linear init` first.

Configuration

Config file

linear init creates ~/.config/linear-cli/config.json:

{
  "apiKey": "lin_api_..."
}

Config file is saved with 0600 permissions (owner-only read/write).

Config options

| Field | Type | Description | |-------|------|-------------| | apiKey | string | Linear API key | | pretty | boolean | Default pretty-print (optional) | | debug | boolean | Default debug logging (optional) |

Coverage and Gaps

Covered: issues (CRUD + assign + state + search), comments (list + add + reply), teams, users, labels, workflow states, projects.

Not yet covered: cycles, initiatives, issue relations, attachments, webhooks, roadmaps, favorites, notifications, bulk operations.

Development

git clone https://github.com/efetoker/linear-cli.git
cd linear-cli
npm install
npm run build
npm test

Node.js >= 22 required.

License

MIT