linear-cli

name	linear-cli
description	Manage Linear issues and projects from the command line. This skill allows automating Linear project management.

Linear CLI

A cross-platform CLI for Linear's GraphQL API, with unblocked issue filtering.

Install: npm install -g @dabble/linear-cli

First-Time Setup

linear login

This will:

1. Ask where to save credentials (project or global)
2. Open Linear API settings in your browser
3. Prompt you to paste your API key
4. Show available teams and let you pick one (or create a new team)
5. Save config to the chosen location

Configuration

Config is layered: ~/.linear (global) is loaded first, then ./.linear (local) overrides on top. Local values override global; unset local values inherit from global. Env vars (LINEAR_API_KEY, LINEAR_TEAM, LINEAR_PROJECT, LINEAR_MILESTONE) are used as fallbacks.

# .linear file format
api_key=lin_api_xxx
team=ISSUE
project=My Project
milestone=Sprint 3

[aliases]
V2=Version 2.0 Release
MVP=MVP Milestone

Aliases

Create short codes for projects and milestones to use in commands:

# Create aliases
linear alias V2 "Version 2.0"           # For a project
linear alias MVP "MVP Milestone"        # For a milestone

# List all aliases
linear alias --list

# Remove an alias
linear alias --remove MVP

Use aliases anywhere a project or milestone name is accepted:

linear issues --project V2
linear issues --milestone MVP
linear issue create --project V2 --milestone MVP "New feature"
linear milestones --project V2

Aliases are shown in linear projects and linear milestones output:

Projects:
[V2] Version 2.0 Release  started  58%

Milestones:
[MVP] MVP Milestone [next]

Quick Reference

# Auth
linear login                    # Interactive setup
linear logout                   # Remove config
linear whoami                   # Show current user/team

# Roadmap (overview)
linear roadmap                  # Projects with milestones and progress

# Default context (sets project/milestone for issues & create)
linear project open "Phase 1"    # Set default project
linear milestone open "Sprint 3" # Set default milestone
linear project close             # Clear default project
linear milestone close           # Clear default milestone

# Issues
linear issues                    # Default: backlog + todo issues (filtered by open project/milestone)
linear issues --no-project       # Bypass default project filter
linear issues --no-milestone     # Bypass default milestone filter
linear issues --unblocked       # Ready to work on (no blockers)
linear issues --open            # All non-completed issues
linear issues --status todo     # Only todo issues
linear issues --status backlog  # Only backlog issues
linear issues --status in-progress # Issues currently in progress
linear issues --status todo --status in-progress # Multiple statuses
linear issues --mine            # Only your assigned issues
linear issues --project "Name"  # Issues in a project
linear issues --milestone "M1"  # Issues in a milestone
linear issues --label bug       # Filter by label
linear issues --priority urgent # Filter by priority (urgent/high/medium/low/none)
# Flags can be combined: linear issues --status todo --mine
linear issue show ISSUE-1        # Full details with parent context
linear issue start ISSUE-1       
linear issue create --title  --project  --assign --estimate M
linear issue create --title  --priority urgent --assign
linear issue create --title  --milestone  --estimate S
linear issue create --title  --blocked-by ISSUE-1 --blocked-by ISSUE-2
linear issue create --title  --label bug --label frontend  
linear issue update ISSUE-1 --status 
linear issue update ISSUE-1 --priority high   
linear issue update ISSUE-1 --estimate M      
linear issue update ISSUE-1 --label bug --label frontend  
linear issue update ISSUE-1 --assign          
linear issue update ISSUE-1 --parent ISSUE-2  
linear issue update ISSUE-1 --milestone 
linear issue update ISSUE-1 --append 
linear issue update ISSUE-1 --check  
linear issue update ISSUE-1 --blocks ISSUE-2 --blocks ISSUE-3  
linear issue close ISSUE-1
linear issue comment ISSUE-1 


linear projects                 
linear projects --all           
linear project show    
linear project create  --description 
linear project complete 
linear project open    
linear project close            


linear milestones --project  
linear milestone show      
linear milestone create  --project  --target-date 2024-03-01
linear milestone open     
linear milestone close          


linear projects reorder              
linear project move  --before   
linear milestones reorder   --project 
linear milestone move  --after  --project 
linear issues reorder ISSUE-1 ISSUE-2 ISSUE-3    
linear issue move ISSUE-5 --before ISSUE-1       


linear labels                   
linear label create  --color 


linear  V2         
linear  --list                  
linear  --remove V2             



linear branch ISSUE-1            

Estimation

Use t-shirt sizes for estimates. Always use --estimate (not -e) for clarity.

Size	Meaning
XS	Trivial, < 1 hour
S	Small, couple hours
M	Medium, a day or so
L	Large, multi-day - consider breaking down
XL	Very large - should definitely break down

# Create with estimate (use long flags for clarity)
linear issue create --title "Add caching" --estimate M --assign

# L/XL issues should be broken into sub-issues
linear issue create --title "Implement auth" --estimate L
linear issue create --title "Add login endpoint" --parent ISSUE-5 --estimate S
linear issue create --title "Add JWT validation" --parent ISSUE-5 --estimate S

Git Conventions

Always link git work to Linear issues:

# Create branch from issue (recommended)
linear branch ISSUE-5            # Creates: ISSUE-5-add-caching-layer

# Commit message format
git commit -m "ISSUE-5: Add cache invalidation on logout"

# Include issue ID in PR title
gh pr create --title "ISSUE-5: Add caching layer"

Workflow Guidelines

Setting context

When working on a specific project/milestone, set it as default to avoid repeating flags:

linear project open "Phase 1"    # All commands now default to Phase 1
linear milestone open "Sprint 3" # And to Sprint 3 milestone
linear issues                    # Shows Phase 1 > Sprint 3 issues only
linear issue create --title "Fix" # Created in Phase 1, Sprint 3
linear project close             # Done? Clear the context

Getting oriented

linear roadmap                  # See all projects, milestones, progress
linear issues --project "P1"    # Issues in a specific project
linear issues --milestone "M1"  # Issues in a specific milestone

Starting work on an issue

linear issues --unblocked       # Find what's ready
linear issue show ISSUE-2        # Review it (shows parent context)
linear issue start ISSUE-2       # Assign + set In Progress
linear branch ISSUE-2            # Create git branch

When you hit a blocker

If work cannot continue due to a dependency or external factor:

# Create the blocking issue
linear issue create --title "Need API credentials" --blocks ISSUE-5

# Or mark existing issue as blocking
linear issue update ISSUE-3 --blocks ISSUE-5

This removes ISSUE-5 from --unblocked results until the blocker is resolved.

When a task is larger than expected

If you discover an M issue is actually L/XL, break it down:

# Create sub-issues
linear issue create --title "Step 1: Research approach" --parent ISSUE-5 --estimate S
linear issue create --title "Step 2: Implement core logic" --parent ISSUE-5 --estimate M
linear issue create --title "Step 3: Add tests" --parent ISSUE-5 --estimate S

# Start working on the first sub-issue
linear issue start ISSUE-6

Checklists vs. sub-issues

Use description checklists for lightweight steps within a single issue. Use sub-issues when items need their own status, assignee, or estimate.

# Checklist — quick implementation steps, a punch list, acceptance criteria
linear issue update ISSUE-5 --append "## TODO\n- [ ] Add validation\n- [ ] Update tests\n- [ ] Check edge cases"

# Check off completed items (fuzzy matches the item text)
linear issue update ISSUE-5 --check "validation"
linear issue update ISSUE-5 --check "tests"

# Uncheck if needed
linear issue update ISSUE-5 --uncheck "validation"

# Sub-issues — substantial, independently trackable work
linear issue create --title "Add login endpoint" --parent ISSUE-5 --estimate S

Prefer checklists when the items are small and don't need independent tracking. Prefer sub-issues when you'd want to assign, estimate, or block on them individually. Use --check to mark items complete as you finish them.

Completing work

After finishing implementation, ask the developer if they want to close the issue:

# Suggest closing
linear issue close ISSUE-5

Do not auto-close issues. Let the developer review the work first.

Adding notes while working

linear issue update ISSUE-2 --append "## Notes\n\nDiscovered X, trying Y approach..."
# or for quick updates
linear issue comment ISSUE-2 "Found the root cause in auth.ts:142"

Organizing with milestones

Milestones group related issues within a project:

# Create milestone for a release
linear milestone create "Beta" --project "Phase 1" --target-date 2024-03-01

# Add issues to milestone
linear issue create --title "Core feature" --milestone "Beta" --estimate M
linear issue update ISSUE-5 --milestone "Beta"

# Reorder milestones to reflect priority
linear milestones reorder "Alpha" "Beta" "Stable" --project "Phase 1"

Completing a phase

linear issue close ISSUE-7       # Close remaining issues
linear project complete "Phase 1"
# Then update CLAUDE.md status table

Parent Context

When viewing an issue with linear issue show, you'll see where it fits in the larger work:

# ISSUE-6: Add JWT validation

State: In Progress
...

## Context

ISSUE-3: Implement authentication system
  - [Done] ISSUE-4: Add login endpoint
  → [In Progress] ISSUE-6: Add JWT validation  ← you are here
  - [Backlog] ISSUE-7: Add refresh tokens

This helps understand the scope and what comes before/after the current task.