Linear CLI Developer (Smart Router)
Purpose
Context-aware routing to Linear issue tracking using linctl CLI. Replaces Linear MCP tools with faster, more reliable command-line operations.
Reference Repository: https://github.com/dorkitude/linctl
When Auto-Activated
- Working with Linear issues, projects, or releases
- Keywords: linear, issue, linctl, IOS-XXXX, release task, sprint, cycle
Why linctl Over MCP?
- More reliable: Direct CLI calls vs MCP server communication
- Less context: Simpler command syntax vs verbose MCP tool definitions
- Faster: No MCP overhead
- Agent-optimized: Built specifically for AI agents with
--json output
Installation
brew tap dorkitude/linctl
brew install linctl
linctl auth # Interactive authentication
Critical Rules
- Always use
--json flag for structured output parsing
- Use issue identifiers (IOS-XXXX) not UUIDs for user-facing references
- Default filters exclude old/completed items - use
--newer-than all_time and --include-completed when needed
- Limit results - Default is 50, use
--limit for large datasets
Quick Reference
Issue Commands
| Task |
Command |
| Get issue details |
linctl issue get IOS-1234 --json |
| List my issues |
linctl issue list --assignee me --json |
| List team issues |
linctl issue list --team iOS --json |
| Search issues |
linctl issue search "query" --json |
| Create issue |
linctl issue create --title "Title" --team iOS --json |
| Update issue |
linctl issue update IOS-1234 --state "Done" --json |
| Assign to self |
linctl issue assign IOS-1234 |
Project Commands
| Task |
Command |
| List projects |
linctl project list --json |
| Get project |
linctl project get <project-id> --json |
| Filter by team |
linctl project list --team iOS --json |
Team Commands
| Task |
Command |
| List teams |
linctl team list --json |
| Get team |
linctl team get iOS --json |
| Team members |
linctl team members iOS --json |
User Commands
| Task |
Command |
| Current user |
linctl whoami --json |
| List users |
linctl user list --json |
| Get user |
linctl user get email@example.com --json |
Comment Commands
| Task |
Command |
| List comments |
linctl comment list IOS-1234 --json |
| Add comment |
linctl comment create IOS-1234 --body "Comment text" |
Cycle Commands
| Task |
Command |
| Current cycle |
linctl cycle list --team iOS --type current --json |
Common Workflows
Get Branch Name for Task
# Instead of: mcp__linear-server__list_issues(query: "IOS-1234")
linctl issue get IOS-1234 --json | jq -r '.gitBranchName'
Release Task Hierarchy (for /impact_linear)
# Step 1: Get release task
linctl issue get IOS-5467 --json
# Step 2: Get subtasks (need UUID from step 1)
linctl issue list --parent-id <uuid> --json --include-completed
# Step 3: Get epic subtasks (repeat for each epic UUID)
linctl issue list --parent-id <epic-uuid> --json --include-completed
List All Issues for Sprint
linctl issue list --team iOS --cycle current --json
Filter by State
linctl issue list --state "In Progress" --json
linctl issue list --state "Done" --include-completed --json
MCP to linctl Migration Table
| MCP Tool |
linctl Equivalent |
mcp__linear-server__get_issue(id) |
linctl issue get <id> --json |
mcp__linear-server__list_issues(...) |
linctl issue list [filters] --json |
mcp__linear-server__create_issue(...) |
linctl issue create [options] |
mcp__linear-server__update_issue(...) |
linctl issue update <id> [options] |
mcp__linear-server__list_comments(issueId) |
linctl comment list <id> --json |
mcp__linear-server__create_comment(...) |
linctl comment create <id> --body "..." |
mcp__linear-server__list_teams |
linctl team list --json |
mcp__linear-server__get_team(query) |
linctl team get <key> --json |
mcp__linear-server__list_projects |
linctl project list --json |
mcp__linear-server__get_project(query) |
linctl project get <id> --json |
mcp__linear-server__list_users |
linctl user list --json |
mcp__linear-server__get_user(query) |
linctl user get <email> --json |
mcp__linear-server__list_cycles(...) |
linctl cycle list --team <key> --json |
Priority Values
| Priority |
Name |
| 0 |
None |
| 1 |
Urgent |
| 2 |
High |
| 3 |
Normal (default) |
| 4 |
Low |
Time Filters (--newer-than)
all_time - No filter6_months_ago - Default1_month_ago1_week_ago- ISO-8601 dates
Output Formats
--json - Structured JSON (recommended for agents)--plaintext - Markdown formatted- Default: Table format
Common Mistakes
Forgetting --json
# Wrong - table output, hard to parse
linctl issue get IOS-1234
# Correct - structured JSON
linctl issue get IOS-1234 --json
Missing --include-completed
# Wrong - misses completed/canceled items
linctl issue list --newer-than all_time --json
# Correct - includes all states
linctl issue list --newer-than all_time --include-completed --json
Using UUID in User-Facing Output
# Wrong - UUIDs are internal
"Task: cab796c7-b58d-4876-b1a4-cc9f39da1431"
# Correct - identifiers are readable
"Task: IOS-5467"
Related Skills & Docs
- cpp → Uses Linear for branch names
- impact_linear → Uses Linear for release context gathering
- designReview → Uses Linear for issue context
Navigation: This is a smart router. For CLI details, see: https://github.com/dorkitude/linctl
anyproto