gh-coalesce-labs-catalyst-plugins-dev/agents/.linearis-syntax-reference.md

Linearis CLI Syntax Reference

Quick reference for common linearis commands to avoid trial-and-error.

Issue Operations

Read a ticket

# Works with both identifier (TEAM-123) and UUID
linearis issues read BRAVO-284
linearis issues read 7690e05c-32fb-4cf2-b709-f9adb12e73e7

List tickets

# Basic list (default: 25 tickets)
linearis issues list

# With limit
linearis issues list --limit 50

# Filter by team (if needed)
linearis issues list --team BRAVO --limit 50

Search tickets

# Use list + jq for searching
linearis issues list --limit 100 | jq '.[] | select(.title | contains("auth"))'

Update a ticket

# Update state (use --state NOT --status!)
linearis issues update BRAVO-284 --state "In Progress"
linearis issues update BRAVO-284 --state "Research"

# Update title
linearis issues update BRAVO-284 --title "New title"

# Update description
linearis issues update BRAVO-284 --description "New description"

# Update priority (1-4, where 1 is highest)
linearis issues update BRAVO-284 --priority 1

# Assign to someone
linearis issues update BRAVO-284 --assignee <user-id>

# Set project
linearis issues update BRAVO-284 --project "Project Name"

# Set cycle
linearis issues update BRAVO-284 --cycle "Cycle Name"

# Set milestone
linearis issues update BRAVO-284 --project-milestone "Milestone Name"

# Add labels (comma-separated)
linearis issues update BRAVO-284 --labels "bug,urgent"

# Clear cycle
linearis issues update BRAVO-284 --clear-cycle

# Clear milestone
linearis issues update BRAVO-284 --clear-project-milestone

Create a ticket

# Basic create
linearis issues create "Title of ticket"

# With options
linearis issues create "Title" --description "Desc" --state "Todo" --priority 2

Comment Operations

Add a comment to a ticket

# Use 'comments create' NOT 'issues comment'!
linearis comments create BRAVO-284 --body "Starting research on authentication flow"

# Multi-line comment (use quotes)
linearis comments create BRAVO-284 --body "Research complete!

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

Cycle Operations

List cycles

# List all cycles for a team
linearis cycles list --team BRAVO

# List only active cycle
linearis cycles list --team BRAVO --active

# Limit results
linearis cycles list --team BRAVO --limit 5

Read cycle details

# By cycle name (returns all issues in cycle)
linearis cycles read "Sprint 2025-11" --team BRAVO

# By UUID
linearis cycles read <cycle-uuid>

Project Operations

List projects

# List all projects for a team
linearis projects list --team BRAVO

# Search for specific project using jq
linearis projects list --team BRAVO | jq '.[] | select(.name == "Auth System")'

Project Milestone Operations

List milestones

# List milestones in a project
linearis project-milestones list --project "Project Name"

# Or by project ID
linearis project-milestones list --project <project-uuid>

Read milestone details

# By milestone name
linearis project-milestones read "Beta Launch" --project "Auth System"

# By UUID
linearis project-milestones read <milestone-uuid>

Update milestone

# Update name
linearis project-milestones update "Old Name" --project "Project" --name "New Name"

# Update target date
linearis project-milestones update "Milestone" --project "Project" --target-date "2025-12-31"

Label Operations

List labels

# List all labels for a team
linearis labels list --team BRAVO

Common Patterns

Get ticket + update state + add comment

# 1. Read ticket first
TICKET_DATA=$(linearis issues read BRAVO-284)
echo "$TICKET_DATA" | jq .

# 2. Update state to Research
linearis issues update BRAVO-284 --state "Research"

# 3. Add starting comment
linearis comments create BRAVO-284 --body "Starting research on authentication flow"

Find tickets in current cycle

# Get active cycle
CYCLE=$(linearis cycles list --team BRAVO --active | jq -r '.[0].name')

# List tickets in that cycle
linearis cycles read "$CYCLE" --team BRAVO | jq '.issues[] | {identifier, title, state: .state.name}'

Get tickets by project

# List tickets and filter by project
linearis issues list --limit 100 | jq '.[] | select(.project.name == "Auth System")'

Important Notes

1. State vs Status: Use --state NOT --status for issue updates
2. Comments: Use linearis comments create NOT linearis issues comment
3. Team parameter: Many commands require --team TEAM-KEY
4. Identifiers: Both TEAM-123 format and UUIDs work for most commands
5. JSON output: All commands return JSON - pipe to jq for filtering
6. Quotes: Use quotes for names with spaces: --cycle "Sprint 2025-11"

Getting Help

# Top-level help
linearis --help

# Command-specific help
linearis issues --help
linearis issues update --help
linearis comments --help
linearis cycles --help

Common Mistakes to Avoid

❌ linearis issues update BRAVO-284 --status "Research" ✅ linearis issues update BRAVO-284 --state "Research"

❌ linearis issues comment BRAVO-284 "Comment text" ✅ linearis comments create BRAVO-284 --body "Comment text"

❌ linearis issues view BRAVO-284 ✅ linearis issues read BRAVO-284

❌ linearis issue BRAVO-284 ✅ linearis issues read BRAVO-284