---
name: linear
description: Expert guidance for Linear issue management and workflows using linear-cli - streamline issue tracking, project planning, and team collaboration from the command line
tags: [linear, issue-tracking, project-management, workflow, productivity]
version: 1.0.0
---

# Linear CLI Skill

Expert assistance for managing Linear issues, projects, and teams using the linear-cli tool. This skill helps you work efficiently with Linear's issue tracking platform directly from your terminal, with built-in awareness of Git and Jujutsu version control workflows.

## What is Linear?

Linear is a purpose-built software development platform for modern product teams. It provides:
- **Issue & Task Tracking**: Optimized for fast, focused work
- **Project Planning**: Visual timelines, milestones, and specifications
- **Sprint Management**: Cycles for building healthy team routines
- **Triage**: Manage incoming bugs and feature requests
- **Analytics**: Real-time insights and reporting
- **Integrations**: 100+ external tools including Git, Figma, and AI assistants

## What is linear-cli?

linear-cli is a command-line tool that bridges Linear issue tracking with development workflows. It's VCS-aware (works with both Git and Jujutsu) to keep you in the right views in Linear based on your current branch or commit.

**Key Benefits:**
- Manage issues without leaving the terminal
- Automatic issue detection from Git branches (e.g., `eng-123-my-feature`)
- Jujutsu integration via `Linear-issue` trailers in commit descriptions
- Create pull requests with auto-populated issue details
- Quick navigation to issues in browser, desktop app, or terminal

## Core Capabilities

### Issue Management

**View and Navigate Issues:**
```bash
# View issue details (auto-detects from current branch/commit)
linear issue view
linear issue view ENG-123

# Open issue in browser or Linear app
linear issue view --web
linear issue view --app

# Get issue information
linear issue id              # Print issue ID from current branch
linear issue title           # Print issue title
linear issue url             # Print issue URL
linear issue describe        # Print title and Linear-issue trailer
```

**List and Search:**
```bash
# List your issues
linear issue list

# Filter and search options available via the list command
```

**Create and Update:**
```bash
# Create a new issue (interactive)
linear issue create

# Update an issue
linear issue update          # Updates current issue
linear issue update ENG-123  # Updates specific issue

# Delete an issue
linear issue delete ENG-123
```

**Workflow Actions:**
```bash
# Start working on an issue
linear issue start           # Start current issue
linear issue start ENG-123   # Start specific issue

# Create GitHub PR with Linear issue details
linear issue pr              # For current issue
linear issue pr ENG-123      # For specific issue
```

### Team Management

```bash
# List teams
linear team list

# Get configured team ID
linear team id

# List team members
linear team members          # Current team
linear team members ENG      # Specific team

# Create a team
linear team create

# Configure GitHub repository autolinks
linear team autolinks
```

### Project Management

```bash
# List projects
linear project list

# View project details
linear project view PROJECT-123
linear project v PROJECT-123  # Shorthand
```

### Configuration

```bash
# Initial setup (creates .linear.toml)
linear config

# Generate shell completions
linear completions
```

## Configuration Setup

First-time setup requires:
1. Linear API key (get from Linear settings)
2. Workspace selection
3. Default team selection

The tool creates a `.linear.toml` file with these settings.

## Version Control Integration

### Git Integration
- Automatically detects issue IDs from branch names
- Common patterns: `eng-123-feature-name`, `ENG-123-bug-fix`
- Commands like `linear issue view` auto-detect the current issue

### Jujutsu (jj) Integration
- Reads `Linear-issue` trailers from commit descriptions
- Use `linear issue describe` to generate proper trailer format
- Seamless workflow with jj's change-centric model

## Common Workflows

### Starting Work on an Issue
```bash
# 1. List available issues
linear issue list

# 2. Start working on an issue (updates status)
linear issue start ENG-123

# 3. Create branch (if using Git)
git checkout -b eng-123-feature-name

# 4. Or with jj, add trailer to description
jj describe -m "Implement feature\n\nLinear-issue: ENG-123"
```

### Creating a Pull Request
```bash
# Auto-populate PR with Linear issue details
linear issue pr

# This creates a GitHub PR with:
# - Issue title in PR title
# - Issue description in PR body
# - Automatic linking back to Linear
```

### Quick Issue Lookup
```bash
# From any branch, quickly check what you're working on
linear issue title
linear issue url --web  # Open in browser
```

## Tips and Best Practices

1. **Branch Naming**: Use consistent patterns like `team-key-123-description` for automatic issue detection
2. **Configuration**: Run `linear config` in each project directory for project-specific settings
3. **Shell Completions**: Install completions for faster command entry
4. **Issue IDs**: Most commands accept optional `issueId` - omit it to use current branch/commit
5. **PR Integration**: Use `linear issue pr` to maintain Linear ↔ GitHub linkage
6. **Quick Access**: Alias common commands (e.g., `alias li='linear issue'`)

## Command Reference

| Command | Alias | Description |
|---------|-------|-------------|
| `linear issue` | `linear i` | Manage issues |
| `linear team` | `linear t` | Manage teams |
| `linear project` | `linear p` | Manage projects |
| `linear issue view` | `linear i v` | View issue details |
| `linear issue pull-request` | `linear i pr` | Create GitHub PR |
| `linear issue delete` | `linear i d` | Delete issue |

## Help and Documentation

- `linear --help`: Main help
- `linear issue --help`: Issue command help
- `linear team --help`: Team command help
- `linear project --help`: Project command help
- Repository: https://github.com/schpet/linear-cli
- Linear Platform: https://linear.app/

## Common Issues and Solutions

**Issue ID Not Detected:**
- Check branch name format matches expected patterns
- Use explicit issue ID: `linear issue view ENG-123`
- For jj, ensure `Linear-issue` trailer is in description

**Configuration Not Found:**
- Run `linear config` in project directory
- Verify `.linear.toml` exists and has correct API key

**Permission Errors:**
- Check Linear API key has correct permissions
- Verify team/workspace access

## Assistant Guidelines

When helping users with Linear CLI:

1. **Context Awareness**: Check if they're using Git or Jujutsu and provide appropriate guidance
2. **Issue Detection**: Remind users that many commands auto-detect issues from current branch/commit
3. **Workflow Integration**: Suggest ways to integrate Linear CLI into their development workflow
4. **Configuration First**: If errors occur, verify `linear config` has been run
5. **Shell Integration**: Recommend completions and aliases for power users
6. **Best Practices**: Encourage consistent branch naming and proper issue linking

Always use the actual linear-cli commands available on the system rather than making assumptions about functionality.