alienfast/linear

Linear Issue Tracking - Complete Reference

READ THIS FIRST - Token-efficient CLI for managing issues, dependencies, and cycles.

---

⚠️ INSTALL ALL SKILLS FOR FULL WORKFLOW AUTOMATION

Run linear skills install --all to get specialized workflows:

• /prd - Create agent-friendly tickets with PRDs
• /triage - Prioritize backlog by staleness and blockers
• /cycle-plan - Plan cycles using velocity analytics
• /retro - Generate sprint retrospectives
• /deps - Analyze dependency chains and blockers
• /link-deps - Discover and link related issues

Without these skills, you're only using basic commands. Install them to unlock full agentic capabilities.

---

Authentication Modes

When you run linear auth login, you choose:

• User mode: --assignee me assigns to your personal Linear account
• Agent mode: --assignee me assigns to the OAuth app (delegate), visible as a separate entity

Check current mode:

linear auth status   # Shows: Mode: User or Mode: Agent

Important: If you see "Auth mode not set", re-run linear auth login to configure.

Command Reference

# Setup
linear init                              # Set default team (.linear.yaml)
linear onboard                           # Show teams, states, quick reference
linear auth login|logout|status          # OAuth authentication (sets user/agent mode)

# Issues (alias: i)
linear i list [flags]                    # List issues
linear i get <ID>                        # Get details (CEN-123)
linear i create <title> [flags]          # Create issue
linear i update <ID> [flags]             # Update issue
linear i comment <ID> -b "text"          # Add comment
linear i react <ID> 👍                   # Add reaction

# Projects (alias: p)
linear p list [--mine]                   # List projects
linear p create <name> [flags]           # Create project

# Cycles (alias: c)
linear c list [--active]                 # List cycles
linear c get <number>                    # Get cycle (requires init)
linear c analyze --team <KEY>            # Velocity analytics

# Teams, Users
linear teams list                        # List teams
linear teams states <KEY>                # Workflow states
linear users list [--team <KEY>]         # List users

# Search & Dependencies
linear search <query> [flags]            # Semantic search across all entities
linear deps <ID>                         # Dependency graph
linear deps --team <KEY>                 # All team dependencies

Output Formats

All commands support JSON output for automation:

# Text output (default) - token-efficient ASCII
linear i list
linear i get CEN-123

# JSON output - machine-readable
linear i list --output json
linear i get CEN-123 --output json

# Control detail level with --format
linear i list --format minimal --output json   # Essential fields (~50 tokens)
linear i list --format compact --output json   # Key metadata (~150 tokens, default)
linear i list --format full --output json      # Complete details (~500 tokens)

# Pipe to jq for filtering
linear i list --priority 1 --output json | jq '.[] | select(.state == "In Progress")'

# Export for processing
linear cycles analyze --team CEN --output json > velocity.json

When to use JSON:

• Parsing data programmatically
• Filtering results with jq
• Storing/processing bulk data
• Integrating with other tools

Supported commands:

• issues list, issues get
• cycles list, cycles get, cycles analyze
• projects list, projects get
• teams list, teams get, teams labels, teams states
• users list, users get, users me
• search (all operations)

Semantic Search

The search is SEMANTIC - finds related issues even without exact matches.

# Basic semantic search
linear search "authentication"           # Finds: auth, login, OAuth, SSO, etc.

# Cross-entity search
linear search "sprint planning" --type all     # Search issues, cycles, projects, users

# Entity-specific
linear search "database migration" --type issues
linear search "john" --type users

Dependency Management

Finding Blocked Work (Critical for Unblocking)

# Find ALL blocked issues (run this weekly!)
linear search --has-blockers --team CEN

# Find high-priority blocked work
linear search --priority 1 --has-blockers --team CEN

# What's blocked by a specific bottleneck?
linear search --blocked-by CEN-123

# What blocks a critical feature?
linear search --blocks CEN-456

Dependency Analysis

# Visualize full dependency graph for issue
linear deps CEN-123

# See all team dependencies (detect circular deps)
linear deps --team CEN

# Find issues with circular dependencies
linear search --has-circular-deps --team CEN

# Find deep dependency chains
linear search --max-depth 5 --team CEN

Cycle Analytics & Velocity

Analyze past cycles to predict capacity:

# Analyze last 10 cycles
linear c analyze --team CEN --count 10

# Output shows:
# - Completed vs planned points
# - Velocity trend
# - Completion rate
# - Recommendations for next cycle capacity

Use before sprint planning to set realistic goals!

Powerful Filter Combinations

# High-priority in-progress work assigned to me
linear i list --priority 1 --state "In Progress" --assignee me

# Backlog items with blockers (prioritize removing blockers!)
linear search --state Backlog --has-blockers --team CEN

# Customer-facing bugs in current cycle
linear i list --labels customer,bug --cycle 65 --format full

# Unassigned high-priority work
linear search --priority 1 --assignee none --team CEN

# Work depending on other issues (check before starting)
linear search --has-dependencies --state "In Progress" --team CEN

Creating Issues with Dependencies

# Simple issue
linear i create "Fix login bug" --team CEN --priority 1

# Full issue with dependencies
linear i create "Add OAuth integration" \
  --team CEN \
  --state "In Progress" \
  --priority 2 \
  --assignee me \
  --parent CEN-100 \
  --depends-on CEN-99 \
  --blocked-by CEN-98 \
  --labels backend,security \
  --estimate 5 \
  --cycle 65 \
  --project "Auth Revamp" \
  --due 2026-02-01

# With description from file (use linear-stdin.sh to avoid permission prompts)
~/.claude/scripts/linear-stdin.sh spec.md i create "Feature title" --team CEN -d -

Passing File Content to Linear CLI

All description and body flags support stdin via -. Use ~/.claude/scripts/linear-stdin.sh to pass file content — it wraps the stdin redirect so Bash permission wildcards match correctly.

# Usage: ~/.claude/scripts/linear-stdin.sh <file> <linear-args...>

# Create issue with description from file
~/.claude/scripts/linear-stdin.sh tmp/description.md i create "Feature title" \
  --team CEN \
  --priority 1 \
  -d -

# Update issue description
~/.claude/scripts/linear-stdin.sh tmp/linear-description-cen-123.md i update CEN-123 -d -

# Add comment from file
~/.claude/scripts/linear-stdin.sh tmp/linear-comment-cen-123.md i comment CEN-123 -b -

Standard workflow for any command that passes file content:

1. Use the Write tool to save content to tmp/<descriptive-name>.md
2. Run ~/.claude/scripts/linear-stdin.sh tmp/<file>.md <linear-args> -d - (or -b - for comments)

Why not use shell redirects directly? Claude Code's Bash permission wildcards don't match through shell operators (<, |, $()). The helper script wraps the redirect internally so permissions work.

For short inline values (no file needed):

# Short descriptions/comments can be passed directly as arguments
linear i create "Fix login bug" --team CEN --priority 1 -d "Brief description here"
linear i comment CEN-123 -b "Quick status update"

Output Formats (Token Efficiency)

# Minimal - most token-efficient (IDs only)
linear i list --format minimal

# Compact - balanced (default)
linear i list --format compact

# Full - all details (use for single issues)
linear i get CEN-123 --format full
linear search "auth" --limit 5 --format full

Real-World Workflows

Weekly Unblocking Routine

# 1. Find all blocked work
linear search --has-blockers --team CEN --format full

# 2. For each blocker, check status
linear i get CEN-123 --format full

# 3. Update blockers or reassign blocked work
linear i update CEN-123 --state "In Progress" --assignee me

Sprint Planning

# 1. Check velocity
linear c analyze --team CEN --count 5

# 2. Find backlog candidates
linear search --state Backlog --team CEN --format compact

# 3. Check dependencies before committing
linear deps --team CEN

# 4. Assign to cycle
linear i update CEN-456 --cycle 66 --assignee [email protected]

Dependency Discovery (Before Creating Issues)

# 1. Search for related work
linear search "authentication refactor" --team CEN

# 2. Check what depends on foundation work
linear search --depends-on CEN-100

# 3. Link new issue to dependencies
linear i create "Add JWT refresh" --depends-on CEN-100,CEN-101

Finding Work Order

# 1. Visualize dependencies
linear deps --team CEN

# 2. Start with issues that have no blockers
linear search --state Backlog --team CEN | grep -v "Blocked by"

# 3. Work that unblocks the most
linear search --blocking <critical-feature-id>

Common Patterns

# Find work for specific person
linear i list --assignee [email protected] --format compact

# High-priority work in active cycle
linear i list --priority 1 --cycle current --team CEN

# All bugs
linear i list --labels bug --team CEN

# Overdue issues
linear i list --state "In Progress" --team CEN # Check due dates manually

# Issues I created
linear i list --creator me --team CEN

Tips for LLMs

1. Always run linear init first - sets default team
2. Use semantic search liberally - finds related work without exact keywords
3. Check blockers weekly - linear search --has-blockers prevents stalled work
4. Analyze velocity before planning - linear c analyze gives realistic estimates
5. Visualize dependencies - linear deps --team <KEY> shows work order
6. Use --format full sparingly - token-expensive, use for single issues only
7. Combine filters - search is powerful with multiple constraints
8. Issue IDs work everywhere - CEN-123 format, no team context needed
9. Cycle numbers need init - Run linear init before using cycle numbers

Flag Reference

Issue Flags:

• -t, --team <KEY> - Team (from init or manual)
• -s, --state <name> - Workflow state
• -p, --priority <0-4> - 0=none, 1=urgent, 2=high, 3=normal, 4=low
• -a, --assignee <email|me> - Assign to user
• -c, --cycle <number> - Cycle number
• -P, --project <name> - Project name
• -e, --estimate <points> - Story points
• -l, --labels <list> - Comma-separated
• -d, --description <text|-> - Description (- for stdin)
• --parent <ID> - Parent issue
• --depends-on <IDs> - Comma-separated dependencies
• --blocked-by <IDs> - Comma-separated blockers
• --due <date> - Due date (YYYY-MM-DD)
• --attach <file> - Attach file

Search Flags:

• --type <entity> - issues, cycles, projects, users, all
• --blocked-by <ID> - Issues blocked by this
• --blocks <ID> - Issues that block this
• --has-blockers - Any blockers
• --has-dependencies - Any dependencies
• --has-circular-deps - Circular dependency chains
• --max-depth <n> - Max dependency depth
• -n, --limit <n> - Results limit
• -f, --format <type> - minimal, compact, full

Output Formats:

• --format minimal - IDs only (most token-efficient)
• --format compact - Balanced (default)
• --format full - All details (use sparingly)