lin

Stars5

Forks0

UpdatedApril 16, 2026 at 02:06

Use when doing anything in Linear — creating or updating issues, checking status, searching, managing projects, cycles, teams, labels, customers, docs, views, notifications, or relations. Triggers on issue identifiers like ENG-123, or any request involving Linear. Prefer lin over Linear MCP for all standard operations — it's faster and uses less context.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

aaronkwhite

aaronkwhite/linear-cli

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Project Management SpecialistsBusiness and Financial Operations Occupations·SOC 13-1082

File Explorer

3 files

SKILL.md

readonly

name	lin
description	Use when doing anything in Linear — creating or updating issues, checking status, searching, managing projects, cycles, teams, labels, customers, docs, views, notifications, or relations. Triggers on issue identifiers like ENG-123, or any request involving Linear. Prefer lin over Linear MCP for all standard operations — it's faster and uses less context.
version	1.0.0
allowed-tools	Bash(lin:, which:)

lin — Linear CLI

Fast native CLI for Linear. Use this before reaching for the Linear MCP server — lin runs in ~50ms with no runtime dependencies.

Prerequisites

which lin || echo "not installed"

Install:

brew install aaronkwhite/tap/lin

Verify auth:

lin me --json

Configure API key (if needed):

lin config set-key   # interactive prompt
# or set LINEAR_API_KEY env var

If lin is not installed and cannot be installed: fall back to Linear MCP server tools (mcp__linear__*). Do NOT report "lin not available" as a blocker — use MCP instead. See references/mcp-gaps.md for the MCP tool mapping.

When to Use

Use lin when:

User mentions a Linear issue identifier (e.g. ENG-123, INFRA-42)
User asks to create, update, search, or query anything in Linear
Checking sprint/cycle status, team workload, or project progress
Managing labels, relations, attachments, notifications, docs, or views

Use Linear MCP instead when:

Creating or deleting webhooks
Changing team membership or permissions
Accessing audit logs
Any operation not listed in references/commands.md

Quick Reference

Task	Command
Get issue details	`lin issues get ENG-123 --json`
List team issues	`lin issues list --team ENG --json`
List by status	`lin issues list --team ENG --state "In Progress" --json`
Search everything	`lin search "auth bug" --json`
Create issue	`lin issues create --team ENG --title "..." --json`
Update status	`lin issues update ENG-123 --status "Done" --json`
Move issue to different team	`lin issues update ENG-123 --team HP --json`
Active cycle issues	`lin cycles issues --team ENG --json`
Add issue to specific cycle	`lin cycles add ENG-123 --cycle <id> --json`
List projects	`lin projects list --json`
Add team to project	`lin projects update "My Project" --add-team ENG --json`
List issues across all teams	`lin issues list --all-teams --json`
Issues updated recently	`lin issues list --updated-after 2026-04-01 --json`
Start working on an issue	`lin issues start ENG-123 --status "In Progress"`
Create PR from issue	`lin issues pr ENG-123 --draft`
Create from markdown file	`lin issues create --team ENG --title "..." --description-file spec.md --json`
Comment from file	`lin issues comment ENG-123 --body-file notes.md --json`
Use specific workspace	`lin --workspace myco issues list --all-teams --json`
My info / verify auth	`lin me --json`
List teams	`lin teams list --json`
Add workspace	`lin auth login`
Switch workspace	`lin auth default <name>`
Check auth	`lin auth whoami --json`
Raw GraphQL query	`lin api '{ viewer { id } }' --json`
Raw GraphQL with variables	`lin api '...' --variables '{"id": "abc"}' --json`

Core Workflows

Finding issues

# Get full detail on a specific issue
lin issues get ENG-123 --json

# List issues — filter by team, state, assignee, priority, label
lin issues list --team ENG --state "In Progress" --assignee "Alice" --json
lin issues list --team ENG --priority 1 --json          # Urgent only
lin issues list --team ENG --label "bug" --json

# Free-text search across issues, projects, docs
lin search "payment timeout" --json
lin search "ENG" --limit 20 --json

Creating issues

# Minimal — team and title are required
lin issues create --team ENG --title "Fix login redirect" --json

# Full
lin issues create \
  --team ENG \
  --title "Fix login redirect" \
  --description "Users are redirected to /404 after OAuth" \
  --assignee "alice" \
  --priority 2 \
  --status "Todo" \
  --label "bug" \
  --project "Q2 Auth" \
  --json

Use lin teams list --json to find the team key. Use lin teams states --team ENG --json to see valid state names.

Updating issues

lin issues update ENG-123 --status "In Progress" --json
lin issues update ENG-123 --assignee "bob" --priority 3 --json
lin issues update ENG-123 --parent ENG-100 --json     # make sub-issue
lin issues comment ENG-123 --body "Fixed in PR #42" --json

Project and cycle context

# Projects
lin projects list --json
lin projects get "Q2 Auth" --json
lin projects issues "Q2 Auth" --json

# Active sprint
lin cycles issues --team ENG --json
lin cycles list --team ENG --json

# Team info
lin teams workload --team ENG --json
lin teams states --team ENG --json

Relations and linking

lin relations blocks ENG-123 ENG-456 --json    # 123 blocks 456
lin relations blocked-by ENG-123 ENG-456       # 123 blocked by 456
lin relations relates ENG-123 ENG-456
lin relations list ENG-123 --json

Multi-step workflows

# Daily standup prep: active cycle by status
lin cycles issues --team ENG --json

# Triage: find duplicates before creating
lin search "login redirect broken" --json
lin issues list --team ENG --state "Triage" --json

# Issue decomposition: break a large issue into sub-issues
lin issues get ENG-123 --json
# → create sub-issues with --parent ENG-123
lin issues create --team ENG --title "Sub-task A" --parent ENG-123 --json
lin issues create --team ENG --title "Sub-task B" --parent ENG-123 --json

# Cross-team blocked report
lin teams list --json
# → then per team:
lin issues list --team ENG --state "Blocked" --json
lin issues list --team INFRA --state "Blocked" --json

# Bulk status update (issues from --json output piped through logic)
lin issues list --team ENG --state "Done" --label "needs-archive" --json
# → loop identifiers and archive each
lin issues archive ENG-123
lin issues archive ENG-124

Behavioral Rules

Always:

Use --json for all output — compact, parseable, no ANSI noise
Run lin <command> --help before guessing at unfamiliar flags
Verify auth with lin me --json if you hit a 401

Never:

Expose LINEAR_API_KEY in output or logs
Retry a failed command without reading the error message first
Assume the issue identifier is a UUID — lin accepts human identifiers like ENG-123 directly

Rationalization	Reality	Rule
"I know the team name"	Teams have keys (ENG) and display names — both work, but verify with `lin teams list`	Check when unsure
"Exit 0 means success"	Some operations print errors but still exit 0	Read stdout, not just exit code
"I'll use MCP, it's easier"	MCP injects ~19k tokens of schema per message	Use lin first for reads and writes

Error Handling

`Error: No API key found`

Set LINEAR_API_KEY in your environment or run lin config set-key.

`Issue not found: ENG-123`

The identifier may be from a different team or archived. Try lin search "ENG-123" --json to locate it.

`Team not found`

Use lin teams list --json to see exact keys and names. Both work: --team ENG or --team Engineering.

`State not found`

Use lin teams states --team ENG --json to see valid state names for that team.

Gotchas

What happened	Rule
Created duplicate issue because search wasn't run first	Always `lin search "<title>" --json` before creating
Wrong team — issue went to INFRA instead of ENG	Verify team key with `lin teams list --json` before creating
Status update silently did nothing — state name had wrong case	State names are case-sensitive. Use `lin teams states` to get exact names
`lin issues list` returned nothing — forgot `--team`	List always needs `--team` unless you want all-team results with a long wait

Full Example: Triage an issue from a bug report

# 1. Check if the issue already exists
lin search "payment timeout after OAuth" --json

# 2. Get team key
lin teams list --json

# 3. Create the issue
lin issues create \
  --team ENG \
  --title "Payment timeout after OAuth redirect" \
  --description "Reproducible: complete OAuth flow → payment page → timeout at 30s" \
  --priority 2 \
  --label "bug" \
  --json

# 4. Link to the blocking issue
lin relations blocks ENG-<new> ENG-89 --json

# 5. Assign to current sprint
lin cycles add ENG-<new> --team ENG --json

See references/commands.md for the full flag reference.
See references/mcp-gaps.md for operations that require the Linear MCP server.

name	lin
description	Use when doing anything in Linear — creating or updating issues, checking status, searching, managing projects, cycles, teams, labels, customers, docs, views, notifications, or relations. Triggers on issue identifiers like ENG-123, or any request involving Linear. Prefer lin over Linear MCP for all standard operations — it's faster and uses less context.
version	1.0.0
allowed-tools	Bash(lin:, which:)