linear

name	linear
description	Linear integration with Linearis CLI - rules, team config, issue format, and all Linear operations (create, update, comment, list, triage, view, project create/plan). Use when creating or managing Linear issues, referencing issues in commits/PRs, or working with Linear projects.

Linear Integration Rules

CLI Tool: Linearis

Use Linearis CLI as the primary tool for Linear operations.

Installation

mise use -g npm:linearis@2025.12.3

Authentication

Linearis uses the $LINEAR_API_TOKEN environment variable for authentication.

Why Linearis over MCP

• More stable than Linear MCP server (which frequently disconnects)
• JSON output for easy parsing
• No token overhead in LLM context
• Simple CLI commands via terminal

---

Team Configuration

• Default Team: Self Driven Platform
  • Identifier: PLTFRM
  • ID: 94fb9928-3874-464a-9f3d-a354d3364f5c
• Alternative Team: Platform ICEBOX
  • Identifier: PLAI
  • ID: 7357e730-4a1a-4f1a-8e53-f42a5077dbbd
  • Use only when explicitly requested

IMPORTANT: Always use PLTFRM as the issue team, unless explicitly requested otherwise.

---

Default Settings

Setting	Default Value	Notes
Team	Self Driven Platform (PLTFRM)	Unless ICEBOX specifically requested
Assignee	me (current user)	Auto-assign to creator
Status	Backlog	Not Triage or Todo
Priority	Based on inference	See auto-detection rules
Labels	Based on inference	See auto-detection rules

Status Options

• Backlog: Default for new issues (planned work)
• Triage: Use /linear-triage or --status Triage for unplanned/incoming requests
• Todo: Ready to start
• In Progress: Currently being worked on
• In Review: Awaiting review
• Done: Completed
• Canceled: Will not be done

---

Auto-Detection Rules

Labels from Title Prefix

Title Pattern	Label
feat:, feat(, feature	Feature
fix:, fix(, bug	Bug
chore:, chore(	Chore
docs:, docs(, documentation	Docs
refactor:, refactor(	Improvement

Priority from Keywords

Keywords in Title/Description	Priority
urgent, critical, broken, production	1 (Urgent)
important, high, asap	2 (High)
(default)	3 (Normal)
low, minor, nice-to-have, someday	4 (Low)

---

Issue Reference Format

Always Use Full Markdown URLs

When referencing Linear issues in PR descriptions, commits, or documentation, always use the full markdown URL format:

# Correct

Closes [PLTFRM-123: Issue Title](https://linear.app/cloudwalk/issue/PLTFRM-123/issue-slug)

# Avoid (less informative)

Closes PLTFRM-123

Magic Words for Auto-Linking

• Closes - Closes the issue when PR is merged
• Fixes - Fixes the issue when PR is merged
• Resolves - Resolves the issue when PR is merged

---

Linearis CLI Commands Reference

Issues

# Create issue (use --status Backlog by default)
linearis issues create "Title" --team PLTFRM --status Backlog -a me

# Create with full options
linearis issues create "feat: new feature" \
  --team PLTFRM \
  --status Backlog \
  -a me \
  -d "Description here" \
  --labels "Feature" \
  -p 3 \
  --project "Project Name"

# Read issue details
linearis issues read PLTFRM-123

# Update issue
linearis issues update PLTFRM-123 --status "In Progress"

# List issues
linearis issues list --team PLTFRM --assignee me

# Search issues
linearis issues search "search query"

Comments

# Add comment
linearis comments create PLTFRM-123 --body "Comment text"

Projects

# List projects
linearis projects list

# List issues in project
linearis issues list --project "Project Name"

Labels

# List available labels
linearis labels list

Teams

# List teams
linearis teams list

---

Workflow Integration

Creating Issues from Code Context

When working on code and needing to create a related issue:

1. Use /linear-create with context from current work
2. Include file paths and relevant code snippets in description
3. Link the created issue in subsequent commits

Linking Commits to Issues

git commit -m "feat(auth): add JWT validation

Closes [PLTFRM-123: Add JWT validation](https://linear.app/cloudwalk/issue/PLTFRM-123/add-jwt-validation)"

PR Description Format

## Related Issues

Closes [PLTFRM-123: Issue Title](https://linear.app/cloudwalk/issue/PLTFRM-123/issue-slug)

## Summary

- Implementation details here

---

MCP Fallback

Use Linear MCP only when Linearis CLI cannot perform the operation:

• Complex GraphQL queries not supported by Linearis
• Operations requiring real-time subscriptions
• Bulk operations not available in CLI

For most day-to-day operations (create, read, update, list, comment), prefer Linearis CLI.

---

/linear-create

Overview

Create a new Linear issue using Linearis CLI with intelligent inference for labels and priority.

Steps

1. Parse Arguments:

   • Extract title from arguments (required)
   • Extract description (optional)
   • Extract team (default: PLTFRM)
   • Extract project (optional)
   • Extract labels (optional, or auto-detect)
   • Extract priority (optional, or auto-detect)
   • Extract status (default: Backlog)

2. Auto-Detect Labels from Title:

   • feat:, feat(, feature → Label: Feature
   • fix:, fix(, bug → Label: Bug
   • chore:, chore( → Label: Chore
   • docs:, docs( → Label: Docs
   • refactor:, refactor( → Label: Improvement

3. Auto-Detect Priority from Keywords:

   • urgent, critical, broken, production → Priority 1 (Urgent)
   • important, high, asap → Priority 2 (High)
   • Default → Priority 3 (Normal)
   • low, minor, nice-to-have → Priority 4 (Low)

4. Create Issue with Linearis CLI:

   linearis issues create "Title" \
     --team PLTFRM \
     --status Backlog \
     -a me \
     -d "Description" \
     --labels "Label1,Label2" \
     -p 3
   

5. Parse JSON Response:

   • Extract issue identifier (e.g., PLTFRM-123)
   • Extract issue URL
   • Extract issue title

6. Generate Output:

   • Display created issue details
   • Provide full markdown URL for references

Default Settings

Setting	Default	Notes
Team	PLTFRM	Self Driven Platform
Status	Backlog	Use /linear-triage for Triage
Assignee	me	Current user
Priority	3 (Normal)	Unless detected from keywords
Labels	Auto-detected	Based on title prefix

Output Format

## Issue Created

**Issue**: [PLTFRM-123: Issue Title](https://linear.app/cloudwalk/issue/PLTFRM-123/issue-slug)
**Team**: Self Driven Platform
**Status**: Backlog
**Priority**: Normal (3)
**Labels**: Feature
**Assignee**: @me

### Use in Commits/PRs

Closes PLTFRM-123: Issue Title

Examples

# Basic issue (auto-detects Feature label)
/linear-create "feat: add user authentication"

# Issue with description
/linear-create "fix: login timeout" "Users are experiencing timeouts after 30 seconds"

# Issue with explicit options
/linear-create "chore: update dependencies" --priority 4 --labels "Chore,maintenance"

# Issue in specific project
/linear-create "feat: new dashboard" --project "Q1 2025"

# Urgent issue (auto-detects priority 1)
/linear-create "fix: critical production bug breaking payments"

Arguments

Arguments: $ARGUMENTS

• First argument: Issue title (required)
• Second argument: Issue description (optional)
• --team: Team key (default: PLTFRM)
• --project: Project name or ID
• --labels: Comma-separated labels
• --priority or -p: Priority 1-4
• --status: Status name (default: Backlog)

Safety Checks

• ✅ Always use PLTFRM team unless explicitly specified
• ✅ Always set status to Backlog (not Triage/Todo)
• ✅ Always assign to current user
• ✅ Auto-detect labels and priority when not specified
• ✅ Generate full markdown URL for issue reference
• ❌ Never create issue without a title

---

/linear-update

Overview

Update an existing Linear issue using Linearis CLI.

Steps

1. Parse Arguments:

   • Extract issue ID (required)
   • Extract fields to update:
     • --title: New title
     • --description or -d: New description
     • --status: New status
     • --priority or -p: New priority (1-4)
     • --assignee or -a: New assignee
     • --labels: New labels (comma-separated)
     • --project: Add to project

2. Update Issue with Linearis CLI:

   linearis issues update PLTFRM-123 \
     --status "In Progress" \
     -p 2
   

3. Parse JSON Response:

   • Confirm update success
   • Extract updated fields

4. Display Updated Issue:

   • Show what changed
   • Provide issue URL

Output Format

## Issue Updated

**Issue**: [PLTFRM-123: Issue Title](https://linear.app/cloudwalk/issue/PLTFRM-123/issue-slug)

### Changes Applied

| Field | Old Value | New Value |
|-------|-----------|-----------|
| Status | Backlog | In Progress |
| Priority | Normal (3) | High (2) |

Common Status Values

Status	Description
Backlog	Planned work, not started
Triage	Needs review/prioritization
Todo	Ready to start
In Progress	Currently being worked on
In Review	Awaiting review
Done	Completed
Canceled	Will not be done

Examples

# Update status
/linear-update PLTFRM-123 --status "In Progress"

# Update priority
/linear-update PLTFRM-123 --priority 1

# Update multiple fields
/linear-update PLTFRM-123 --status "In Review" --labels "Feature,ready-for-review"

# Update description
/linear-update PLTFRM-123 -d "Updated description with more details"

# Move to different status (start working)
/linear-update PLTFRM-123 --status "In Progress"

# Mark as done
/linear-update PLTFRM-123 --status "Done"

Arguments

Arguments: $ARGUMENTS

• First argument: Issue identifier (required)
• --title: New title
• --description or -d: New description
• --status: New status
• --priority or -p: Priority 1-4
• --assignee or -a: New assignee
• --labels: Comma-separated labels
• --project: Project name or ID

Safety Checks

• ✅ Always confirm issue exists before updating
• ✅ Show what will be changed before applying
• ❌ Never update without specifying issue ID

---

/linear-comment

Overview

Add a comment to a Linear issue using Linearis CLI.

Steps

1. Parse Arguments:

   • Extract issue ID (required)
   • Extract comment body (required)

2. Create Comment with Linearis CLI:

   linearis comments create PLTFRM-123 --body "Comment text here"
   

3. Parse JSON Response:

   • Confirm comment created
   • Extract comment details

4. Display Confirmation:

   • Show comment added
   • Provide issue URL

Output Format

## Comment Added

**Issue**: [PLTFRM-123: Issue Title](https://linear.app/cloudwalk/issue/PLTFRM-123/issue-slug)

### Comment

> Comment text here...

**View**: [See in Linear](https://linear.app/cloudwalk/issue/PLTFRM-123/issue-slug#comment-xyz)

Examples

# Add simple comment
/linear-comment PLTFRM-123 "Started working on this"

# Add progress update
/linear-comment PLTFRM-123 "Completed initial implementation. Ready for review."

# Add multi-line comment (use quotes)
/linear-comment PLTFRM-123 "Progress update:
- Implemented feature X
- Fixed bug Y
- Need to add tests"

# Add comment with code reference
/linear-comment PLTFRM-123 "Fixed in commit abc123. See PR #456"

Arguments

Arguments: $ARGUMENTS

• First argument: Issue identifier (required)
  • Format: PLTFRM-123
• Second argument: Comment body (required)
  • Supports markdown formatting

Use Cases

• Progress updates during development
• Questions or clarifications
• Review feedback
• Blockers or dependency notes
• Completion notes

---

/linear-list

Overview

List Linear issues with filters using Linearis CLI.

Steps

1. Parse Filter Arguments:

   • --team: Team filter (default: PLTFRM)
   • --assignee or -a: Assignee filter (default: me)
   • --status: Status filter
   • --project: Project filter
   • --label: Label filter
   • --limit or -l: Result limit (default: 20)

2. List Issues with Linearis CLI:

   linearis issues list \
     --team PLTFRM \
     --assignee me \
     --limit 20
   

3. Parse JSON Response:

   • Extract issue list
   • Format for table display

4. Display Results:

   • Show issues in table format
   • Include count and filters applied

Output Format

## Issues (15 found)

**Filters**: Team: PLTFRM | Assignee: me | Status: all

| ID | Title | Status | Priority | Updated |
|----|-------|--------|----------|---------|
| PLTFRM-123 | feat: add authentication | In Progress | High | 2h ago |
| PLTFRM-122 | fix: login timeout | Backlog | Normal | 1d ago |
| PLTFRM-121 | chore: update deps | Done | Low | 3d ago |

**View in Linear**: [Team Issues](https://linear.app/cloudwalk/team/PLTFRM/active)

Examples

# List my issues (default)
/linear-list

# List by status
/linear-list --status "In Progress"

# List by project
/linear-list --project "Q1 2025"

# List all team issues (not just mine)
/linear-list --assignee all

# List with label filter
/linear-list --label "Bug"

# List more results
/linear-list --limit 50

# Combine filters
/linear-list --status "Backlog" --label "Feature" --limit 10

Arguments

Arguments: $ARGUMENTS

• --team: Team key (default: PLTFRM)
• --assignee or -a: Assignee filter (default: me, use "all" for all)
• --status: Status name filter
• --project: Project name or ID
• --label: Label name filter
• --limit or -l: Max results (default: 20)

Default Behavior

• Shows issues assigned to current user
• From PLTFRM team
• All statuses (except archived)
• Limited to 20 results

---

/linear-triage

Overview

Quick shortcut to create a Linear issue in Triage status (for unplanned/incoming requests).

When to Use

Use /linear-triage instead of /linear-create when:

• Receiving ad-hoc requests that need review
• Creating issues from Slack messages or emails
• Capturing bugs reported by users
• Anything that needs prioritization before starting

Steps

1. Parse Arguments:

   • Same as /linear-create
   • Status is automatically set to Triage

2. Create Issue with Linearis CLI:

   linearis issues create "Title" \
     --team PLTFRM \
     --status Triage \
     -a me
   

3. Display Created Issue:

   • Same output as /linear-create
   • Highlights Triage status

Output Format

## Issue Created (Triage)

**Issue**: [PLTFRM-123: Issue Title](https://linear.app/cloudwalk/issue/PLTFRM-123/issue-slug)
**Team**: Self Driven Platform
**Status**: ⚠️ Triage (needs prioritization)
**Assignee**: @me

> This issue is in Triage. Review and move to Backlog when prioritized.

Difference from /linear-create

Aspect	/linear-create	/linear-triage
Default Status	Backlog	Triage
Use Case	Planned work	Incoming requests
Priority	Auto-detected	Usually needs review

Examples

# Quick triage issue
/linear-triage "User reported login issue"

# Triage with description
/linear-triage "API timeout from customer" "Customer XYZ reported timeouts on endpoint /api/v1/data"

# Triage with initial label
/linear-triage "Production error in payments" --labels "Bug"

Arguments

Arguments: $ARGUMENTS

• First argument: Issue title (required)
• Second argument: Issue description (optional)
• --labels: Comma-separated labels (optional)
• --priority or -p: Priority 1-4 (optional)
• --project: Project name (optional)

Workflow

1. Create issue with /linear-triage
2. Review and prioritize in Linear
3. Move to Backlog when ready to plan
4. Move to Todo when ready to start

---

/linear-view

Overview

View detailed information about a Linear issue using Linearis CLI.

Steps

1. Parse Issue Identifier:

   • Extract issue ID from arguments (required)
   • Supports formats: PLTFRM-123, 123, or full UUID

2. Fetch Issue Details:

   linearis issues read PLTFRM-123
   

3. Parse JSON Response:

   • Extract all issue fields
   • Format for readable output

4. Display Issue Information:

   • Title and identifier
   • Status and priority
   • Assignee and team
   • Labels and project
   • Description
   • URL

Output Format

## PLTFRM-123: Issue Title

**Status**: In Progress
**Priority**: Normal (3)
**Assignee**: @username
**Team**: Self Driven Platform
**Labels**: Feature, backend
**Project**: Q1 2025
**Created**: 2025-01-10
**Updated**: 2025-01-13

### Description

Issue description content here...

### Links

- **Linear**: [View in Linear](https://linear.app/cloudwalk/issue/PLTFRM-123/issue-slug)
- **Git Branch**: `pltfrm-123-issue-slug`

### Reference for PRs

Closes PLTFRM-123: Issue Title

Examples

# View by identifier
/linear-view PLTFRM-123

# View by number (assumes PLTFRM team)
/linear-view 123

Arguments

Arguments: $ARGUMENTS

• First argument: Issue identifier (required)
  • Format: PLTFRM-123 or just 123

Error Handling

• If issue not found, display error message
• If identifier format invalid, suggest correct format

---

/linear-project-create

Overview

Create a Linear project from a Cursor plan file, converting plan tasks into Linear issues.

Steps

1. Parse Arguments:

   • Extract plan file path (required, or detect from .cursor/plans/)
   • Extract project name (optional, defaults to plan name)
   • Extract team (default: PLTFRM)

2. Read Plan File:

   • Load plan from .cursor/plans/ directory
   • Parse YAML frontmatter for metadata
   • Extract tasks/todos from plan content

3. Create Linear Project:

   • Note: Linearis CLI doesn't support project creation directly
   • Use Linear MCP or create issues with --project flag to existing project

4. Create Issues from Tasks:

   • For each task in the plan:

   linearis issues create "Task title" \
     --team PLTFRM \
     --status Backlog \
     --project "Project Name" \
     -d "Task description from plan"
   

5. Update Plan with Issue Links:

   • Add Linear issue IDs to plan tasks
   • Create mapping between plan tasks and issues

6. Display Results:

   • List all created issues
   • Show project link
   • Provide summary

Output Format

## Project Created from Plan

**Plan**: `.cursor/plans/2025-01-13-feature-x.md`
**Project**: [Project Name](https://linear.app/cloudwalk/project/project-id)
**Team**: Self Driven Platform

### Issues Created (5)

| # | Issue | Title | Status |
|---|-------|-------|--------|
| 1 | [PLTFRM-123](url) | Task 1 from plan | Backlog |
| 2 | [PLTFRM-124](url) | Task 2 from plan | Backlog |
| 3 | [PLTFRM-125](url) | Task 3 from plan | Backlog |
| 4 | [PLTFRM-126](url) | Task 4 from plan | Backlog |
| 5 | [PLTFRM-127](url) | Task 5 from plan | Backlog |

### Plan Updated

Tasks in plan now include Linear issue references.

Examples

# Create project from specific plan
/linear-project-create .cursor/plans/2025-01-13-feature-x.md

# Create with custom project name
/linear-project-create .cursor/plans/plan.md --project "Q1 Feature Release"

# Create from most recent plan (auto-detect)
/linear-project-create

Arguments

Arguments: $ARGUMENTS

• First argument: Plan file path (optional, auto-detects most recent)
• --project: Project name in Linear (will create issues linked to this project)
• --team: Team key (default: PLTFRM)

Workflow

1. Create plan using /plan command
2. Review and refine plan
3. Run /linear-project-create to create issues
4. Work on issues, update status
5. Plan file stays in sync (optional)

Notes

• Requires existing Linear project to link issues to
• Each plan task becomes one Linear issue
• Task dependencies are noted in issue descriptions
• Plan file is updated with issue references after creation

---

/linear-project-plan

Overview

Generate a Cursor plan file from an existing Linear project, converting issues into actionable tasks.

Steps

1. Parse Arguments:

   • Extract project name or ID (required)
   • Extract output path (optional, defaults to .cursor/plans/)

2. Fetch Project Details:

   # List projects to find the one
   linearis projects list
   

3. Fetch Project Issues:

   linearis issues list --project "Project Name"
   

4. Generate Plan File:

   • Create YAML frontmatter with project metadata
   • Convert issues to todo items
   • Preserve issue relationships as dependencies
   • Include issue links in task descriptions

5. Write Plan File:

   • Save to .cursor/plans/ directory
   • Use naming convention: YYYY-MM-DD-project-name.md

6. Display Results:

   • Show created plan file path
   • Summarize tasks imported

Output Format

## Plan Created from Project

**Project**: [Project Name](https://linear.app/cloudwalk/project/project-id)
**Plan File**: `.cursor/plans/2025-01-13-project-name.md`

### Tasks Imported (8)

| Status | Count |
|--------|--------|
| Backlog | 3 |
| Todo | 2 |
| In Progress | 2 |
| Done | 1 |

### Next Steps

1. Review the generated plan
2. Start working on tasks using the plan
3. Update Linear issues as you progress

Examples

# Generate plan from project name
/linear-project-plan "Q1 2025 Features"

# Generate with custom output path
/linear-project-plan "Project Name" --output .cursor/plans/q1-features.md

# Generate from project with specific team filter
/linear-project-plan "Project Name" --team PLTFRM

Arguments

Arguments: $ARGUMENTS

• First argument: Project name or ID (required)
• --output: Custom output file path
• --team: Filter issues by team
• --status: Filter issues by status (e.g., only active issues)

Status Mapping

Linear Status	Plan Status
Backlog	pending
Triage	pending
Todo	pending
In Progress	in_progress
In Review	in_progress
Done	completed
Canceled	cancelled

Workflow

1. Identify Linear project to work on
2. Run /linear-project-plan "Project Name"
3. Review generated plan
4. Execute tasks using the plan
5. Update Linear issues as you complete work

Use Cases

• Onboarding to existing project
• Planning sprint work from Linear backlog
• Creating execution roadmap from project issues
• Syncing Linear project state to local plan