Query Linear Issues

Fetch and view Linear issues to gather context for debugging investigations.

When to Use

• Viewing issue details for debugging context
• Searching for related issues
• Checking issue status and priority
• Reading issue descriptions and comments
• Finding issues by ID or search query

Pre-flight Checks

Authentication

# linearis uses API token from environment or config
# Check if linearis is available
linearis --version 2>/dev/null || {
  echo "linearis CLI not installed"
  echo "Install: npm install -g linearis"
  exit 1
}

# Test authentication (list with limit 1)
linearis issues list --limit 1 >/dev/null 2>&1 || {
  echo "Not authenticated to Linear"
  echo "Set LINEARIS_API_TOKEN environment variable or use --api-token flag"
  exit 1
}

Common Commands

Read Issue Details

# Get issue by ID or identifier
linearis issues read ENG-1234

# Output is JSON - use jq to parse
linearis issues read ENG-1234 | jq '.title'
linearis issues read ENG-1234 | jq '.description'
linearis issues read ENG-1234 | jq '.state.name'

# Full issue details
linearis issues read ENG-1234 | jq '.'

List Issues

# List recent issues (default limit: 25)
linearis issues list

# Limit results
linearis issues list --limit 10
linearis issues list --limit 100

# Save to file for analysis
linearis issues list --limit 50 > /tmp/linear-issues-$(date +%Y%m%d).json

Search Issues

# Search by text query
linearis issues search "api-gateway error"
linearis issues search "production crash"
linearis issues search "kubernetes pod"

# Save search results
linearis issues search "database connection" > /tmp/linear-search-$(date +%Y%m%d).json

Output Format

All linearis commands output JSON. Use jq to parse and extract fields.

Common jq patterns:

# Extract issue title
linearis issues read ENG-1234 | jq -r '.title'

# Extract state
linearis issues read ENG-1234 | jq -r '.state.name'

# Extract assignee
linearis issues read ENG-1234 | jq -r '.assignee.name'

# Extract labels
linearis issues read ENG-1234 | jq -r '.labels[].name'

# Extract priority (0=None, 1=Low, 2=Medium, 3=High, 4=Urgent)
linearis issues read ENG-1234 | jq -r '.priority'

Output Management

Save issue details for debugging context:

# Save issue to tmp file
linearis issues read ENG-1234 > /tmp/linear-issue-ENG-1234-$(date +%Y%m%d).json

# Extract key info for quick reference
linearis issues read ENG-1234 | jq -r '{
  id: .identifier,
  title: .title,
  state: .state.name,
  priority: .priority,
  description: .description
}' > /tmp/issue-summary-ENG-1234.json

# Use issue context for debugging
ISSUE_DESC=$(linearis issues read ENG-1234 | jq -r '.description')
echo "Debugging: $ISSUE_DESC"

Benefits:

• Issue context informs debugging strategy
• Share investigation files with team
• Correlate issue reports with logs/events

Advanced Filtering

For detailed jq filtering patterns, see:

• [jq patterns for filtering and analysis](references/JQ-PATTERNS.md)

Quick Reference

# Filter by team
linearis issues list --limit 200 | jq '[.[] | select(.team.key == "ENG")]'

# Filter by state
linearis issues list --limit 200 | jq '[.[] | select(.state.name == "In Progress")]'

# Filter by label
linearis issues list --limit 200 | jq '[.[] | select(.labels[]?.name == "Bug")]'

# Search in description
linearis issues list --limit 200 | jq '[.[] | select(has("description") and (.description | contains("error")))]'

# Extract summary
linearis issues list --limit 50 | jq '.[] | {
  id: .identifier,
  title: .title,
  state: .state.name,
  assignee: .assignee.name // "Unassigned"
}'

Tips

• Use identifiers like ENG-1234 instead of UUIDs for readability
• Pipe output to jq for parsing JSON
• Save issue details before debugging to preserve context
• Search results are limited - use specific queries
• Issue descriptions often contain error messages, stack traces, or reproduction steps
• Check issue labels for environment info (production, staging, etc.)
• Use has("field") in jq to check field existence before accessing
• Use // operator in jq for default values when fields might be null
• Use ? operator for safe array/object navigation (e.g., .labels[]?)
• Save filtered results to files for further analysis
• Increase --limit (max usually 200) for comprehensive searches
• Priority values: 0=None, 1=Low, 2=Medium, 3=High, 4=Urgent