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
cat spec.md | linear i create "Feature title" --team CEN -d -

Piping Support (Powerful!)

All description and body flags support stdin via

-

:

# Pipe Claude plan into ticket description
cat .claude/plans/auth-refactor.md | linear i create "Refactor authentication" \
  --team CEN \
  --priority 1 \
  -d -

# Pipe multi-file content
cat design.md implementation.md | linear i create "Feature implementation" \
  --team CEN \
  -d -

# Pipe command output
gh issue view 123 --json body -q .body | linear i create "Port GH issue" \
  --team CEN \
  -d -

# Update issue description from file
cat updated-spec.md | linear i update CEN-123 -d -

# Add comment from file
cat findings.md | linear i comment CEN-123 -b -

# Reply to comment with piped content
cat response.md | linear i reply CEN-123 comment-id -b -

Common Patterns:

# Claude Code plans → Linear tickets
cat .claude/plans/*.md | linear i create "Implementation plan" -d -

# PRD → Parent ticket
cat prd.md | linear i create "Feature: OAuth" --team CEN -d -

# Changelog → Release ticket
git log --oneline v1.0.0..HEAD | linear i create "v1.1.0 Release" -d -

# Test results → Bug report
pytest --verbose | linear i create "Test failures" -d -

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 alice@co.com

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 alice@company.com --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)