| 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
linear i list -t TEAM --mine
linear i list --since 7d --group-by state
linear i list --label bug --count-only
linear i get TEAM-123
linear i get TEAM-123 --comments
linear i get TEAM-1 TEAM-2 TEAM-3
linear i create "Title" -t TEAM -p 1
linear i create "Title" -t TEAM -d -
linear i create "Title" -t TEAM --parent PARENT-ID
linear i update TEAM-123 -s "In Progress"
linear i update TEAM-123 -l bug -l urgent
linear i update TEAM-123 --due tomorrow
linear i update TEAM-123 -e 3
linear i start TEAM-123 --checkout
linear i stop TEAM-123
linear i close TEAM-123
linear i assign TEAM-123 "Name"
linear i move TEAM-123 "Project"
linear i transfer TEAM-123 TEAM
linear i comment TEAM-123 -b "text"
linear i archive TEAM-123
linear i open TEAM-123
linear i link TEAM-123
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
linear rel add TEAM-1 -r blocks TEAM-2
linear rel add TEAM-1 -r blocked-by TEAM-2
linear rel add TEAM-1 -r related TEAM-2
linear rel add TEAM-1 -r duplicate TEAM-2
linear rel remove TEAM-1 TEAM-2
linear rel parent TEAM-2 TEAM-1
linear rel unparent TEAM-2
Relation types: blocks, blocked-by, related, duplicate.
Statuses
linear st list -t TEAM
linear st get "In Progress" -t TEAM
Use st list to discover valid names for i update -s.
Bulk Operations
linear b update-state -s Done TEAM-1 TEAM-2
linear b assign --user me TEAM-1 TEAM-2
linear b label --add bug TEAM-1 TEAM-2
linear b unassign TEAM-1 TEAM-2
Projects & Teams
linear p list
linear p get "Name"
linear p create "Name" -t TEAM
linear t list
linear t get TEAM_KEY
linear t members TEAM_KEY
Cycles & Sprints
linear c list -t TEAM
linear c current -t TEAM
linear sp status -t TEAM
linear sp progress -t TEAM
linear sp burndown -t TEAM
linear sp velocity -t TEAM
Git Integration
linear g checkout TEAM-123
linear g branch TEAM-123
linear g create TEAM-123
linear g pr TEAM-123
linear g pr TEAM-123 --draft
Context
Detects current issue from git branch. Designed for AI agents.
linear context
linear ctx --output json
Parses: fac-123-fix-bug, feature/FAC-456-new-feature.
History
linear history issue TEAM-123
linear hist issue TEAM-123 --limit 50
Triage
linear triage list
linear tr claim TEAM-123
linear tr snooze TEAM-123 --duration 1w
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:
linear i get TEAM-123 --comments
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
linear d create "Name" -c "Content"
linear l list
linear l create "name" -c "#FF0000"
linear templates list
linear views list
Search
linear search "query"
linear search "query" --output json --compact
Raw GraphQL API
linear api query '{ viewer { id name } }'
echo '{"query":"..."}' | linear api query -
linear api mutate '<mutation>'
Watch Mode
linear watch TEAM-123
linear watch -t TEAM
Import / Export
linear export -t TEAM --format csv
linear export -t TEAM --format json
linear import --file data.csv -t TEAM
