Linear Lifecycle Management with Linearis CLI

Overview

Core principle: Use Linearis CLI for all Linear operations instead of loading 20k token Linear MCP. CLI returns structured JSON for parsing without context overhead.

Tool: Linearis - Linear CLI built for LLM agents with ~1000 token footprint vs 13k+ for MCP.

Context savings: 100% - no MCP loaded, just bash commands with JSON output.

Setup

One-time dependencies install:

Use /linear-setup to install Linearis CLI (required for this skill to work).

Token configuration:

Automatic! On first use, Claude will:

1. Check if ~/.linear_api_token exists
2. If not, prompt you for your Linear API token
3. Save it to ~/.linear_api_token with secure permissions
4. Verify the connection works

Get your token: Linear Settings → Security & Access → Personal API keys

When to Use

Use this skill when:

• Starting work on a Linear issue (need issue details)
• Creating new issues from bugs or features discovered
• Updating issue status during development
• Adding comments or progress updates
• Searching for issues across teams/projects

Don't use when:

• Issue tracking not needed for current work
• Working on non-Linear projects

Implementation

IMPORTANT: Always check for token on first Linear operation in a skill invocation:

# Check if token exists
if [ ! -f ~/.linear_api_token ]; then
  echo "⚠️  Linear API token not found."
  echo ""
  echo "Get your token from: Linear Settings → Security & Access → Personal API keys"
  echo ""
  # Use AskUserQuestion tool to prompt for token
  # Save response to ~/.linear_api_token
  # Set permissions: chmod 600 ~/.linear_api_token
  # Verify it works with: linearis issues list -l 1
fi

After token is confirmed, proceed with Linear operations. Linearis automatically reads from ~/.linear_api_token.

Creating a New Issue

IMPORTANT: Keep it simple! Specify the team key directly. Never use --labels or --priority.

User request: "Create a Linear issue for fixing the avatar crop bug"

Command:

linearis issues create "Fix avatar crop bug" \
  --team BET \
  --description "Avatar images are cropping incorrectly on mobile devices. Need to adjust aspect ratio handling."

Key rules:

• ✅ Use --team TEAM_KEY (get from user's Linear workspace, e.g. BET, ENG, etc.)
• ✅ Keep description clear and concise
• ❌ NEVER use --labels (causes errors)
• ❌ NEVER use --priority (unnecessary)

Parse response:

# Returns JSON with: {identifier, title, url, ...}
# Extract: issue ID (e.g., BET-145) and URL

Response to user:

✓ Created issue BET-145: Fix avatar crop bug
https://linear.app/your-workspace/issue/BET-145

Starting Work on an Issue

User request: "Start working on bet-123"

Command:

linearis issues read BET-123

Parse JSON response for:

• title
• description
• state (current status)
• priority
• labels
• branchName (suggested git branch)

Response to user:

Issue: BET-123 - [Title]
Status: [State]
Description: [Brief description]
Labels: [labels]
Branch: [branchName or generate from title]

Creating branch [branch-name]...

Then create branch and proceed with development.

Updating Issue Status

User request: "Update bet-456 to in progress"

Command:

linearis issues update BET-456 --state "In Progress"

Response:

✓ Updated BET-456 to In Progress

Adding Comments

User request: "Add comment to bet-789 about the refactor being done"

Command:

linearis comments create BET-789 --body "Completed auth refactor. Moved from Context API to Zustand for better performance. All tests passing."

Response:

✓ Added comment to BET-789

Searching for Issues

User request: "Find all open bugs with label 'authentication'"

Command:

linearis issues search "authentication" --team "$LINEAR_TEAM_KEY" | jq '.[] | select(.labels[]? | contains("bug")) | {id: .identifier, title: .title, state: .state.name}'

Parse and format results as table.

Completing Work

User request: "Close bet-789, PR merged"

Commands:

# 1. Add completion comment
linearis comments create BET-789 --body "Feature complete. PR #456 merged to main."

# 2. Update status to done
linearis issues update BET-789 --state "Done"

Response:

✓ Marked BET-789 as Done
✓ Added completion comment

Quick Reference

Common Mistakes

Not parsing JSON output

• ❌ Don't show raw JSON to user
• ✅ Parse and format relevant fields cleanly

Hardcoding team/project names

• ❌ Don't assume team structure
• ✅ Let user specify or discover via linearis commands

Using issue IDs incorrectly

• ❌ Don't lowercase (bet-123) in commands
• ✅ Use proper case (BET-123) - linearis handles both but be consistent

Real-World Impact

Before (Linear MCP):

• 20k tokens consumed at session start
• All tools loaded in context
• Context budget: 180k/200k remaining

After (Linearis CLI):

• 0 tokens in session (just bash commands)
• JSON parsing lightweight
• Context budget: 200k/200k remaining
• 100% context savings

Performance:

• Linearis usage docs: ~1000 tokens
• MCP tool definitions: ~13000 tokens
• 92% reduction even for reference material

Advanced: Multi-Team Operations

List issues across teams:

linearis issues list --team Frontend -l 5
linearis issues list --team Backend -l 5

Create issue in specific team:

linearis issues create "Fix API timeout" --team Backend

No workspace switching needed - all commands accept --team flag for cross-team operations within same Linear workspace.