Linear Integration Skill

Purpose: Issue management for Linear.app using Linearis CLI with JSON output optimized for LLM agents.

Tool: Linearis CLI - npm package

linearis

Table of Contents

1. Prerequisites
2. Decision Tree
3. Quick Command Reference
4. Pattern Recognition - Auto-Invocation
5. Workflow Examples
6. Error Handling
7. Authentication Strategy
8. JSON Output Handling

Prerequisites

Verify Installation

# Check CLI installed
linearis --version

Authentication (Priority Order)

IMPORTANT: Always check for project-specific credentials first. Different projects may use different Linear workspaces.

1. Project .env (PREFERRED - project-specific):

   # Check project .env for LINEAR_API_KEY
   grep LINEAR_API_KEY .env
   
   # Run commands with project token
   export LINEAR_API_TOKEN="$(grep LINEAR_API_KEY .env | cut -d= -f2)"
   linearis teams list
   

2. Environment Variable (session override):

   export LINEAR_API_TOKEN="lin_api_xxx"
   

Running Commands with Project Credentials

# Inline token from project .env (recommended)
LINEAR_API_TOKEN=$(grep LINEAR_API_KEY .env | cut -d= -f2) linearis <command>

# Or export for session
export LINEAR_API_TOKEN=$(grep LINEAR_API_KEY .env | cut -d= -f2)
linearis <command>

Decision Tree

Issue Operations

User wants to...
├── View issue details
│   └── linearis issues read <ISSUE-ID>
├── Create new issue
│   └── linearis issues create "Title" --team <Team> [options]
├── Update existing issue
│   └── linearis issues update <ISSUE-ID> [--state|--assignee|--priority]
├── Search issues
│   └── linearis issues search "query" [--team|--limit]
├── List recent issues
│   └── linearis issues list [--limit N] [--team Name]
└── Delete issue (soft)
    └── linearis issues update <ISSUE-ID> --trashed

Metadata Operations

User wants to...
├── List teams
│   └── linearis teams list
├── List projects
│   └── linearis projects list
├── List cycles/sprints
│   └── linearis cycles list [--team Name] [--active]
├── List labels
│   └── linearis labels list [--team Name]
└── List users
    └── linearis users list [--active]

Comments

Add a comment to an issue
└── linearis comments create <ISSUE-ID> --body "Comment text"

Quick Command Reference

Issues CRUD

linearis issues list

linearis issues list --limit 10 --team TractionBD

linearis issues search "query"

linearis issues search "auth bug"

linearis issues read <ID>

linearis issues read TBD-456

linearis issues create "Title"

linearis issues create "Fix login" --team TractionBD --priority 1

linearis issues update <ID>

linearis issues update TBD-123 --state "In Review"

Create Issue Options

linearis issues create "Title" \
  --team "TractionBD" \
  --assignee "user-id-or-name" \
  --labels "Bug,Critical" \
  --priority 1 \
  --project "Project Name" \
  --description "Detailed description" \
  --parent-ticket TBD-100

Priority values: 0 (none), 1 (urgent), 2 (high), 3 (medium), 4 (low)

Update Issue Options

linearis issues update TBD-123 \
  --state "In Review" \
  --assignee "new-user" \
  --priority 2 \
  --labels "Bug,P1" \
  --clear-labels \
  --parent-ticket TBD-200 \
  --trashed

Metadata Queries

# Teams
linearis teams list

# Projects
linearis projects list

# Labels (optionally by team)
linearis labels list --team TractionBD

# Users
linearis users list --active

# Cycles/Sprints
linearis cycles list --team TractionBD --active
linearis cycles list --team TractionBD --around-active 3

Comments

linearis comments create TBD-123 --body "This is a comment"

Pattern Recognition - Auto-Invocation

High Confidence Triggers (invoke immediately)

Issue Operations:
  - "Create a Linear issue for..."
  - "Open a ticket in Linear..."
  - "Log this as a Linear bug..."
  - "Check Linear issue TBD-123"
  - "What's the status of TBD-123?"
  - "Update TBD-123 to..."
  - "Move TBD-123 to In Review"
  - "Assign TBD-123 to..."
  - "Close Linear issue..."
  - "Search Linear for..."
  - "Find issues about..."

Sprint/Cycle Operations:
  - "What's in the current sprint?"
  - "Show active cycle for..."
  - "List team's cycles"

Metadata:
  - "List Linear teams"
  - "Show all projects in Linear"
  - "What labels are available?"
  - "Who can I assign this to?"

Issue ID Detection

# Linear issue ID pattern
[A-Z]{2,10}-\d+

# Examples: TBD-123, DEV-456, BACKEND-789

Context Signals

Strong indicators:
  - .env contains LINEAR_API_KEY
  - Recent messages mention "Linear"
  - Issue IDs in ABC-123 format present
  - User mentions "sprint", "cycle", "backlog"

Workflow Examples

Create Issue from Bug Report

User: "Create a Linear issue for the login timeout bug"

Steps:
  1. Parse request: title=login timeout bug
  2. Execute: linearis issues create "Login timeout bug" --team TractionBD --labels "Bug"
  3. Return: Issue ID and details from JSON response

Check Issue Status

User: "What's the status of TBD-123?"

Steps:
  1. Parse issue ID: TBD-123
  2. Execute: linearis issues read TBD-123
  3. Return: Issue title, state, assignee, priority from JSON

Update Issue State

User: "Move TBD-123 to In Review and assign to John"

Steps:
  1. Get user list: linearis users list --active
  2. Find John's ID from JSON
  3. Update: linearis issues update TBD-123 --state "In Review" --assignee john-id
  4. Confirm: linearis issues read TBD-123

Sprint Planning

User: "What issues are in the current sprint?"

Steps:
  1. Get active cycle: linearis cycles list --team TractionBD --active
  2. Parse cycle from JSON
  3. List issues: linearis issues list --team TractionBD --limit 50
  4. Filter by cycle in results

Error Handling

command not found: linearis

npm install -g linearis

No API token found

LINEAR_API_KEY

.env

LINEAR_API_TOKEN

Unauthorized

.env

Issue not found

Team not found

linearis teams list

Rate limited

Authentication Troubleshooting

Wrong workspace issues:
  Problem: Commands return unexpected teams/issues
  Cause: Using global token instead of project-specific token
  Fix: Check project .env and use that token

  # Verify which workspace you're connected to
  LINEAR_API_TOKEN=$(grep LINEAR_API_KEY .env | cut -d= -f2) linearis teams list

Graceful Fallback

If Linearis unavailable:
  1. Log the error for visibility
  2. Provide web URL: https://linear.app/[workspace]/issue/ABC-123
  3. Suggest manual action with instructions

Authentication Strategy

Priority Order:
  1. Project .env (LINEAR_API_KEY) - project-specific workspaces
  2. LINEAR_API_TOKEN env var - session override

Before Running Commands:
  1. Check if project has .env with LINEAR_API_KEY
  2. Export token for session
  3. If no project .env, prompt user to add LINEAR_API_KEY

Example:
  export LINEAR_API_TOKEN="$(grep LINEAR_API_KEY .env | cut -d= -f2)"
  linearis teams list

JSON Output Handling

Linearis outputs JSON. Parse and extract relevant fields:

# Get issue title
linearis issues read TBD-123 | jq -r '.title'

# Get issue state
linearis issues read TBD-123 | jq -r '.state.name'

# List issue identifiers and titles
linearis issues list --limit 10 | jq -r '.[] | "\(.identifier): \(.title)"'