Initial commit

agents/.linearis-syntax-reference.md

@@ -0,0 +1,226 @@
+# 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`