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
```bash
# Works with both identifier (TEAM-123) and UUID
linearis issues read BRAVO-284
linearis issues read 7690e05c-32fb-4cf2-b709-f9adb12e73e7
```

### List tickets
```bash
# 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
```bash
# Use list + jq for searching
linearis issues list --limit 100 | jq '.[] | select(.title | contains("auth"))'
```

### Update a ticket
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# By milestone name
linearis project-milestones read "Beta Launch" --project "Auth System"

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

### Update milestone
```bash
# 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
```bash
# List all labels for a team
linearis labels list --team BRAVO
```

## Common Patterns

### Get ticket + update state + add comment
```bash
# 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
```bash
# 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
```bash
# 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

```bash
# 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`