Linear Pro CLI

Enhanced Linear CLI with GitHub PR integration, Claude Code context, and TUI dashboard foundation.

Features

• Linear Issue Management: Search, list, and filter issues with status, assignee, labels, priority
• Automated Workflow: Create branches from Linear issues with automatic status updates
• GitHub PR Integration: View PR status, CI checks, and reviews
• PR Creation: Auto-generate PRs from Linear issues with linked descriptions
• Claude Context Persistence: Generate .linear.md with full workflow context
• Workflow Status: Complete pipeline view (issue → branch → PR → CI → reviews)
• TUI Dashboard: Keyboard-navigable PR list (MVP)
• Smart Merge: Auto-merge when checks + approvals are ready

Installation

From Source

deno task install

This installs the linear command globally.

Build Binary

deno task build

Creates a linear-pro executable in the current directory.

Quick Start

1. Configure Linear and GitHub Access

Set environment variables:

export LINEAR_API_KEY=lin_api_xxx
export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_OWNER=your_org
export GITHUB_REPO=your_repo

Or configure via commands:

linear auth linear lin_api_xxx
linear auth github ghp_your_token your_org your_repo

Get your Linear API key at: https://linear.app/settings/api

2. Find and Start Working on an Issue

# Find issues to work on
linear issue list --status "Todo" --assignee me

# Or search for a specific issue
linear issue search "oauth"

# Start working on an issue (creates branch, updates status, generates context)
linear issue start ENG-123

This creates a branch like feature/ENG-123-your-issue-title, updates the issue status to "In Progress", and generates a .linear.md context file.

3. Make Changes and Create PR

# Make your changes
git commit -m "ENG-123: Implement feature"
git push

# Create PR with auto-filled description from Linear
linear issue create-pr

4. Check Workflow Status

linear workflow status

Output:

📊 Linear Pro Workflow Status
════════════════════════════════════════════════════

📋 Issue: ENG-123
   Title: Implement feature
   Status: In Progress
   Priority: 🟡 Medium

🌿 Branch: feature/eng-123
   Commits: 3
   Latest: Fix edge case by John Doe

🔗 Pull Request: #987
   Title: ENG-123: Implement feature
   State: 🟢 Open
   URL: https://github.com/your_org/your_repo/pull/987

   CI Checks: 3/3 passing
     ✅ build
     ✅ test
     ✅ lint

   Reviews: 2/3 approved
     ✅ @alice: approved
     🔄 @bob: changes_requested
     ⏳ @carol: pending

════════════════════════════════════════════════════

5. Generate Claude Context

linear claude context

This generates .linear.md with all issue + branch + PR + CI context. Open it in Claude Code for AI-assisted development.

6. Auto-Merge When Ready

linear pr merge-when-ready

Waits for all checks to pass and all required approvals, then auto-merges (squash by default).

Commands

Issue Management

linear issue list [options]       # List issues with filters
  --status <status>               # Filter by status (repeatable)
  --assignee <assignee>           # me/username/unassigned
  --label <label>                 # Filter by label (repeatable)
  --priority <priority>           # urgent/high/medium/low
  --limit <number>                # Max results (default: 20)

linear issue search <query> [options]  # Search by title/description
  --limit <number>                # Max results (default: 10)

linear issue start <id> [options]      # Start working on issue
  --prefix <prefix>               # Branch prefix (default: feature)

linear issue create-pr [id] [options]  # Create GitHub PR
  --draft                         # Create as draft
  --base <branch>                 # Base branch (default: main)

PR Management

linear pr view              # Show PR linked to current branch
linear pr checks            # Show CI status
linear pr reviews           # Show review status
linear pr merge-when-ready  # Auto-merge when ready (with options)

Workflow

linear workflow status      # Show complete pipeline status

Claude Integration

linear claude context       # Generate .linear.md with full context
linear claude show          # Display current .linear.md

Dashboard

linear tui                  # Launch interactive dashboard

Configuration

linear auth linear <api-key>           # Configure Linear
linear auth github TOKEN OWNER REPO    # Configure GitHub
linear info                            # Show current config

Environment Variables

Required for GitHub Integration

• GITHUB_TOKEN: Personal access token (requires repo and pull scopes)
• GITHUB_OWNER: Repository owner/organization
• GITHUB_REPO: Repository name

Required for Linear Integration

• LINEAR_API_KEY: Linear API key (get at https://linear.app/settings/api)

Optional

• LINEAR_WORKSPACE: Linear workspace ID

Generated Context File (.linear.md)

When you run linear claude context, a .linear.md file is generated with:

# Linear Pro Context

*Last updated: 2025-01-15T10:30:00Z*

## Issue
- **ID**: ENG-123
- **Title**: Implement feature
- **Status**: In Progress
- **Priority**: 🟡 Medium
- **Created**: 1/15/2025

## Git Branch
- **Branch**: `feature/eng-123`
- **Commits**: 3
  - Latest commits:
    - `a1b2c3d` - Fix edge case (John Doe)
    - `e4f5g6h` - Add tests (Jane Smith)
    - `i7j8k9l` - Initial implementation (John Doe)
- **Remote**: https://github.com/your_org/your_repo

## GitHub PR
- **Number**: #987
- **Title**: ENG-123: Implement feature
- **URL**: https://github.com/your_org/your_repo/pull/987
- **CI Status**: ✅ All passing
- **Reviews**:
  - Approved: 2
  - Changes Requested: 0
  - Pending: 1

## Focus Areas
- Add error handling
- Increase test coverage
- Document security implications

## Notes
Key considerations for this feature...

---

> This file is generated by `linear claude context`. Open it in Claude Code for AI-assisted context about your Linear issue workflow.

Claude Code can read this file to understand your workflow context automatically.

Architecture

linear-pro/
├── src/
│   ├── main.ts                 # Entry point
│   ├── cli.ts                  # Command router
│   ├── types.ts                # TypeScript types
│   ├── linear/
│   │   └── client.ts           # Linear API wrapper (GraphQL)
│   ├── github/
│   │   └── client.ts           # GitHub REST API wrapper
│   ├── git/
│   │   ├── context.ts          # Git context helpers (read-only)
│   │   └── operations.ts       # Git write operations (branch creation, checkout)
│   ├── context/
│   │   └── manager.ts          # .linear.md persistence
│   ├── commands/
│   │   ├── issue.ts            # Issue management commands
│   │   ├── pr.ts               # PR commands
│   │   ├── workflow.ts         # Workflow commands
│   │   └── claude.ts           # Claude context commands
│   └── tui/
│       └── dashboard.ts        # TUI dashboard
├── test/
│   ├── linear_client.test.ts
│   ├── github_client.test.ts
│   └── context_manager.test.ts
├── deno.json                   # Deno config
└── README.md

Development

Run in Dev Mode

deno task dev              # Run CLI
deno task dev:tui          # Run TUI

Run Tests

deno task test

Build Binary

deno task build

Roadmap

MVP (Complete)

• ✅ GitHub PR integration
• ✅ PR status viewing
• ✅ CI check status
• ✅ Review status
• ✅ Auto-merge when ready
• ✅ Workflow status pipeline
• ✅ Claude context generation
• ✅ Basic TUI dashboard

Phase 2 (Future)

• Linear API integration (read issues, update status)
• Slack notifications
• Advanced TUI (search, filter, comments)
• Claude suggestion API integration
• Workspace-level dashboard
• Branch protection rules integration
• Automated commit message validation

Integration with linear-cli

linear-pro extends linear-cli with:

1. GitHub integration - PR status and CI checks
2. Context persistence - Automatic .linear.md generation
3. Workflow orchestration - Complete pipeline view
4. TUI dashboard - Keyboard-navigable interface

Existing linear-cli commands are not modified - linear-pro adds new functionality on top.

Troubleshooting

"GITHUB_TOKEN environment variable not set"

Set your GitHub token:

export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_OWNER=your_org
export GITHUB_REPO=your_repo

"No PR found for issue ENG-123"

Make sure:

1. The PR title or body contains the issue number (e.g., "ENG-123")
2. The branch name follows the pattern feature/ENG-123 or similar
3. The PR exists in the repository

"Could not find issue number in branch name"

Use branch names that include the issue identifier:

• feature/eng-123
• fix/ENG-123-bug
• eng-123-implement-feature

TUI not launching

Make sure:

1. GitHub is configured (see above)
2. You're in a git repository
3. Terminal supports raw input mode

License

MIT

Contributing

Contributions welcome! Please submit PRs to improve the tool.

---

Linear Pro - The bridge between Linear workflows and Claude Code orchestration.