linearis-cli

name	linearis-cli
description	Reference for Linearis CLI commands to interact with Linear project management. Use when working with Linear tickets, cycles, projects, milestones, or when the user mentions ticket IDs like TEAM-123, BRAVO-456, ENG-789.

Linearis CLI Reference

CRITICAL: Always use these exact patterns. Do NOT guess or improvise syntax.

Issue Operations

Read a Ticket

linearis issues read TEAM-123                    # ✅ By identifier
linearis issues read 7690e05c-32fb-4cf2-b709-f9adb12e73e7  # ✅ By UUID

Common mistakes:

linearis issues get TEAM-123      # ❌ WRONG - no 'get' command
linearis issue view TEAM-123      # ❌ WRONG - no 'view', use 'read'
linearis issue TEAM-123           # ❌ WRONG - missing subcommand

List Tickets

linearis issues list                      # Basic list (25 tickets)
linearis issues list --limit 50           # With limit
linearis issues list --team BRAVO         # Filter by team
linearis issues list --team BRAVO --limit 100

NOTE: --limit and --team are the ONLY supported filters. For other filtering, use jq:

# Filter by status - use jq, NOT --status or --filter
linearis issues list --limit 100 | jq '.[] | select(.state.name == "In Progress")'

# Search by title
linearis issues list --limit 100 | jq '.[] | select(.title | contains("auth"))'

Common mistakes:

linearis issues list --status "In Progress"  # ❌ WRONG - no --status flag
linearis issues list --filter "keyword"      # ❌ WRONG - no --filter flag
linearis issues --filter "keyword"           # ❌ WRONG - no --filter flag

Search Tickets

linearis issues search "keyword" --team BRAVO    # ✅ Correct
linearis issues search "auth" --team ENG         # ✅ Correct

Update a Ticket

# Update state - use --state NOT --status!
linearis issues update TEAM-123 --state "In Progress"
linearis issues update TEAM-123 --state "Research"
linearis issues update TEAM-123 --state "Done"

# Other updates
linearis issues update TEAM-123 --title "New title"
linearis issues update TEAM-123 --description "New description"
linearis issues update TEAM-123 --priority 1              # 1=Urgent, 2=High, 3=Medium, 4=Low
linearis issues update TEAM-123 --assignee <user-id>
linearis issues update TEAM-123 --project "Project Name"
linearis issues update TEAM-123 --cycle "Cycle Name"
linearis issues update TEAM-123 --project-milestone "Milestone Name"
linearis issues update TEAM-123 --labels "bug,urgent"
linearis issues update TEAM-123 --clear-cycle
linearis issues update TEAM-123 --clear-project-milestone

Common mistakes:

linearis issues update TEAM-123 --status "Done"   # ❌ WRONG - use --state

Create a Ticket

linearis issues create "Title of ticket"
linearis issues create "Title" --description "Description" --state "Todo" --priority 2
linearis issues create "Title" --team BRAVO --project "Project Name"

Comment Operations

Add a Comment

linearis comments create TEAM-123 --body "Starting research"

# Multi-line comment
linearis comments create TEAM-123 --body "Research complete!

See findings: https://github.com/..."

Common mistakes:

linearis issues comment TEAM-123 "Comment"        # ❌ WRONG
linearis issues add-comment TEAM-123 "Comment"    # ❌ WRONG
linearis comment TEAM-123 --body "Comment"        # ❌ WRONG

Correct pattern: linearis comments create (plural "comments", then "create")

Cycle Operations

List Cycles

linearis cycles list --team BRAVO              # All cycles
linearis cycles list --team BRAVO --active     # Only active cycle
linearis cycles list --team BRAVO --limit 5    # Recent cycles

Read Cycle Details

linearis cycles read "Sprint 2025-11" --team BRAVO   # By name
linearis cycles read <cycle-uuid>                     # By UUID

Returns all issues in the cycle - useful for cycle analysis.

Get Active Cycle Pattern

CYCLE=$(linearis cycles list --team BRAVO --active | jq -r '.[0].name')
linearis cycles read "$CYCLE" --team BRAVO | jq '.issues[] | {identifier, title, state: .state.name}'

Project Operations

List Projects

linearis projects list --team BRAVO
linearis projects list --team BRAVO | jq '.[] | select(.name == "Auth System")'

Milestone Operations

List Milestones

linearis project-milestones list --project "Project Name"
linearis project-milestones list --project <project-uuid>

Read Milestone

linearis project-milestones read "Beta Launch" --project "Auth System"
linearis project-milestones read <milestone-uuid>

Update Milestone

linearis project-milestones update "Milestone" --project "Project" --name "New Name"
linearis project-milestones update "Milestone" --project "Project" --target-date "2025-12-31"

Label Operations

linearis labels list --team BRAVO

Common Workflow Patterns

Read ticket, update state, add comment

# 1. Read ticket
linearis issues read TEAM-123

# 2. Update state
linearis issues update TEAM-123 --state "In Progress"

# 3. Add comment
linearis comments create TEAM-123 --body "Starting work on this"

Find tickets in current cycle

CYCLE=$(linearis cycles list --team BRAVO --active | jq -r '.[0].name')
linearis cycles read "$CYCLE" --team BRAVO | jq '.issues[] | {identifier, title, state: .state.name}'

Get tickets by project

linearis issues list --team BRAVO --limit 100 | jq '.[] | select(.project.name == "Auth System")'

Mark ticket as done with PR link

linearis issues update TEAM-123 --state "Done"
linearis comments create TEAM-123 --body "Merged: PR #456 https://github.com/org/repo/pull/456"

Quick Reference Card

Action	Command
Read ticket	linearis issues read TEAM-123
Update state	linearis issues update TEAM-123 --state "State"
Add comment	linearis comments create TEAM-123 --body "text"
Search	linearis issues search "keyword" --team TEAM
List issues	linearis issues list --team TEAM --limit N
Active cycle	linearis cycles list --team TEAM --active
Cycle details	linearis cycles read "Name" --team TEAM

Important Rules

1. --state NOT --status: Always use --state for issue state updates
2. comments create: Use linearis comments create, not issues comment
3. issues read: Use read, not get or view
4. Filtering via jq: No --filter or --status flags - pipe to jq instead
5. Team parameter: Most commands need --team TEAM-KEY
6. Quotes for spaces: --cycle "Sprint 2025-11" not --cycle Sprint 2025-11
7. JSON output: All commands return JSON - use jq for parsing

Getting Help

linearis --help
linearis issues --help
linearis issues update --help
linearis comments --help
linearis cycles --help