linear-cli

name	linear-cli
description	Reference for using linear-cli (aliased as `linear`) to manage Linear.app issues, projects, cycles, and sprints from the terminal. Use when the user mentions Linear tickets, issues, project management, or sprint planning.

Linear CLI (linear)

linear-cli is authenticated via OAuth 2.0. Verify with linear doctor.

Issues

linear i list --mine                              # My issues
linear i list -t TEAM --mine                      # Scoped to team
linear i list --since 7d --group-by state          # Grouped
linear i list --label bug --count-only             # Count

linear i get TEAM-123                              # Details
linear i get TEAM-123 --comments                   # With comments
linear i get TEAM-1 TEAM-2 TEAM-3                 # Batch

linear i create "Title" -t TEAM -p 1               # Create (1=urgent,2=high,3=med,4=low)
linear i create "Title" -t TEAM -d -               # Pipe description from stdin
linear i create "Title" -t TEAM --parent PARENT-ID # Nest under parent/epic

linear i update TEAM-123 -s "In Progress"          # Status
linear i update TEAM-123 -l bug -l urgent          # Labels
linear i update TEAM-123 --due tomorrow            # Due date
linear i update TEAM-123 -e 3                      # Estimate

linear i start TEAM-123 --checkout                 # Start + git branch
linear i stop TEAM-123                             # Back to backlog
linear i close TEAM-123                            # Done
linear i assign TEAM-123 "Name"                    # Assign
linear i move TEAM-123 "Project"                   # Move to project
linear i transfer TEAM-123 TEAM                    # Transfer team
linear i comment TEAM-123 -b "text"                # Comment
linear i archive TEAM-123                          # Archive
linear i open TEAM-123                             # Open in browser
linear i link TEAM-123                             # Print URL

Ticket description hygiene

Load voice before writing non-trivial ticket descriptions; it is the gate for specifics, named actors, and no slop. Unless trivial (typo, formatting), cover:

• What — 1–2 sentences on the problem or feature.
• Why — context (bug report, user feedback, tech debt, regression).
• Acceptance criteria — concrete conditions for "done" when knowable.

Pipe long bodies via stdin (-d -) to avoid shell-quoting pain. For parents/epics, search via linear i search "<keywords>" --output json --compact --fields id,identifier,title then pass --parent <ID> at create.

Relations

linear rel list TEAM-123                           # List relationships
linear rel add TEAM-1 -r blocks TEAM-2             # TEAM-1 blocks TEAM-2
linear rel add TEAM-1 -r blocked-by TEAM-2         # TEAM-1 blocked by TEAM-2
linear rel add TEAM-1 -r related TEAM-2            # Link as related
linear rel add TEAM-1 -r duplicate TEAM-2          # Mark as duplicate
linear rel remove TEAM-1 TEAM-2                    # Remove link
linear rel parent TEAM-2 TEAM-1                    # Set parent
linear rel unparent TEAM-2                         # Remove parent

Relation types: blocks, blocked-by, related, duplicate.

Statuses

linear st list -t TEAM                             # Workflow states
linear st get "In Progress" -t TEAM                # State details

Use st list to discover valid names for i update -s.

Bulk Operations

linear b update-state -s Done TEAM-1 TEAM-2        # Bulk status
linear b assign --user me TEAM-1 TEAM-2            # Bulk assign
linear b label --add bug TEAM-1 TEAM-2             # Bulk label
linear b unassign TEAM-1 TEAM-2                    # Bulk unassign

Projects & Teams

linear p list                                      # Projects
linear p get "Name"                                # Details
linear p create "Name" -t TEAM                     # Create
linear t list                                      # Teams
linear t get TEAM_KEY                              # Team details
linear t members TEAM_KEY                          # Members

Cycles & Sprints

linear c list -t TEAM                              # Cycles
linear c current -t TEAM                           # Current cycle
linear sp status -t TEAM                           # Sprint status
linear sp progress -t TEAM                         # Progress bar
linear sp burndown -t TEAM                         # Burndown chart
linear sp velocity -t TEAM                         # Velocity

Git Integration

linear g checkout TEAM-123                         # Checkout/create branch
linear g branch TEAM-123                           # Print branch name
linear g create TEAM-123                           # Create branch (no checkout)
linear g pr TEAM-123                               # GitHub PR
linear g pr TEAM-123 --draft                       # Draft PR

Context

Detects current issue from git branch. Designed for AI agents.

linear context                                     # Issue from branch
linear ctx --output json                           # JSON for parsing

Parses: fac-123-fix-bug, feature/FAC-456-new-feature.

History

linear history issue TEAM-123                      # Activity log
linear hist issue TEAM-123 --limit 50              # More entries

Triage

linear triage list                                 # Unassigned issues
linear tr claim TEAM-123                           # Claim + backlog
linear tr snooze TEAM-123 --duration 1w            # Snooze 1 week

Slack Thread Enrichment

Linear tickets often have Slack threads attached (in comments or description URLs). If the slack-cli skill is available, use it to fetch thread context for richer understanding of an issue or feature goal:

# 1. Pull ticket details / comments for Slack URLs
linear i get TEAM-123 --comments

# 2. Extract channel ID + thread timestamp from the Slack URL
#    e.g. https://workspace.slack.com/archives/C0123456789/p1234567890123456
#    → channel=C0123456789, thread_ts=1234567890.123456

# 3. Fetch the thread via slack-cli
slack ch history C0123456789 --oldest 1234567890.123456 --count 50

Attached Artifact Enrichment

Tickets often link artifacts holding the real failure state or design intent. Pull them when fetching the ticket, not later:

• Bug-report IDs (project-local skills, e.g. daily-cli-bug-report)
• Sentry / Rollbar / Bugsnag issues (matching MCP if configured)
• Axiom / DataDog / CloudWatch / Loki / Grafana log queries
• S3 zips, HAR files, screen recordings, screenshots
• Stack traces, repro scripts, customer-attached logs
• Linked PR diffs, commit SHAs, design docs

Default is pull, not skip. A bug ticket without its bug report is empty; root-cause analysis runs on guesswork. Treat ticket + artifact as one comprehension step.

Read-only fetches are not spec-mode violations, even when they cache to disk. Spec mode restricts repo/workspace mutations -- not network reads or cache writes. The "spec mode means no downloads" reading produces symptom-anchored specs.

Agent Output Patterns

Use these flags when consuming output programmatically:

Flag	Purpose
--output json	JSON (also ndjson)
--compact	No pretty-print
--fields a,b,c	Limit fields (dot paths)
--id-only	Only resource ID
--quiet	Suppress decoration
--format "{{identifier}} {{title}}"	Template
--filter "state.name=In Progress"	Client-side filter
--fail-on-empty	Non-zero exit on empty
--dry-run	Preview

Chaining

ID=$(linear i create "Title" -t TEAM --id-only --quiet)
linear i update "$ID" -s "In Progress"

Exit Codes

Code	Meaning
0	Success
1	General error
2	Not found
3	Auth error
4	Rate limited

Documents, Labels, Templates

linear d list                                      # Documents
linear d create "Name" -c "Content"                # Create doc
linear l list                                      # Labels
linear l create "name" -c "#FF0000"                # Create label
linear templates list                              # Templates
linear views list                                  # Custom views

Search

linear search "query"                              # Search issues
linear search "query" --output json --compact      # JSON output

Raw GraphQL API

linear api query '{ viewer { id name } }'          # Query
echo '{"query":"..."}' | linear api query -         # Pipe
linear api mutate '<mutation>'                      # Mutate

Watch Mode

linear watch TEAM-123                              # Watch issue changes
linear watch -t TEAM                               # Watch team activity

Import / Export

linear export -t TEAM --format csv                 # Export CSV
linear export -t TEAM --format json                # Export JSON
linear import --file data.csv -t TEAM              # Import CSV