Linear CLI Skill

This skill provides instructions for managing Linear issues, tasks, and projects using the linear-cli command-line tool. Linear is a modern issue tracker designed for software teams, and the CLI enables workflow management directly from the terminal.

Installation

First, install the linear-cli tool:

# Using Homebrew
brew install schpet/tap/linear

# Or using Deno
deno install -A --reload -f -g -n linear jsr:@schpet/linear-cli

Setup

1. Create an API key at https://linear.app/settings/account/security (requires member access)

2. Add the API key to shell environment:

   # In ~/.bashrc or ~/.zshrc:
   export LINEAR_API_KEY="lin_api_..."
   
   # Or in fish:
   set -Ux LINEAR_API_KEY="lin_api_..."
   

3. Run the configuration wizard in your project repository:

   cd my-project-repo
   linear config
   

   This creates a .linear.toml config file with workspace and team settings.

Issue Management

View Issues

View the current issue (determined from git branch name or jj commit trailer):

linear issue view          # View current issue in terminal
linear issue view ABC-123  # View specific issue
linear issue view -w       # Open issue in web browser
linear issue view -a       # Open issue in Linear.app
linear issue id            # Print issue ID from current branch
linear issue title         # Print issue title
linear issue url           # Print Linear.app URL

List Issues

List issues with filtering and sorting options:

linear issue list           # List unstarted issues assigned to you
linear issue list -A        # List unstarted issues assigned to anyone
linear issue list -s "In Progress"  # Filter by state
linear issue list -w       # Open in web browser
linear issue list -a       # Open in Linear.app

Start Working on an Issue

Create or switch to an issue branch and mark as started:

linear issue start          # Choose an issue interactively
linear issue start ABC-123  # Start specific issue

The CLI creates a git branch with the issue ID and updates the issue status.

Create Issues

Create new issues interactively or with flags:

linear issue create                    # Interactive prompts
linear issue create -t "title" -d "description"

Update Issues

Update existing issue details:

linear issue update         # Interactive prompts for current issue

Delete Issues

Remove an issue from Linear:

linear issue delete

Create Pull Requests

Generate a GitHub PR with issue details via gh pr create:

linear issue pr

Issue Comments

Manage comments on issues:

linear issue comment list          # List comments
linear issue comment add           # Add comment
linear issue comment add -p <id>   # Reply to specific comment
linear issue comment update <id>   # Update comment

Team Management

linear team list       # List teams
linear team id         # Print team ID
linear team members    # List team members
linear team create     # Create a new team
linear team autolinks  # Configure GitHub autolinks

Project Management

linear project list    # List projects
linear project view    # View project details

Milestone Management

linear milestone list --project <projectId>     # List milestones
linear m list --project <projectId>             # Alias
linear milestone view <milestoneId>             # View details
linear m view <milestoneId>                     # Alias
linear milestone create --project <projectId> --name "Q1 Goals" --target-date "2026-03-31"
linear m create --project <projectId>           # Interactive
linear milestone update <milestoneId> --name "New Name"
linear m update <milestoneId> --target-date "2026-04-15"
linear milestone delete <milestoneId>
linear m delete <milestoneId> --force

Document Management

Manage Linear documents (can be attached to projects or issues):

# List documents
linear document list
linear docs list                                # Alias
linear document list --project <projectId>
linear document list --issue TC-123
linear document list --json

# View documents
linear document view <slug>
linear document view <slug> --raw
linear document view <slug> --web
linear document view <slug> --json

# Create documents
linear document create --title "My Doc" --content "# Hello"
linear document create --title "Spec" --content-file ./spec.md
linear document create --title "Doc" --project <projectId>
linear document create --title "Notes" --issue TC-123
cat spec.md | linear document create --title "Spec"

# Update documents
linear document update <slug> --title "New Title"
linear document update <slug> --content-file ./updated.md
linear document update <slug> --edit

# Delete documents
linear document delete <slug>
linear document delete <slug> --permanent
linear document delete --bulk <slug1> <slug2>

Configuration Options

Configure Linear CLI via environment variables or .linear.toml:

Version Control Integration

The CLI works with both git and jj (jujutsu):

• git: Works best when branches include Linear issue IDs (e.g., eng-123-my-feature). Use linear issue start or copy branch names from Linear UI.
• jj: Detects issues from Linear-issue trailers in commit descriptions. Use linear issue start to add the trailer automatically.

Common Workflows

Daily Workflow

1. List assigned issues: linear issue list
2. Start working: linear issue start (choose interactively)
3. View details: linear issue view
4. When done: create PR with linear issue pr

Creating a Task

1. Create issue: linear issue create -t "Task title" -d "Description"
2. Start working: linear issue start <issue-id>
3. Track progress in the branch

Reviewing Issues

1. List all unstarted issues: linear issue list -A
2. View specific issue: linear issue view <issue-id>
3. Check comments: linear issue comment list

Tips

• Use linear issue view to quickly see the current branch’s issue
• Use linear issue pr when ready to create a pull request – it pre-fills title and description from Linear
• The CLI keeps you in the right views in Linear, avoiding context switching
• Git branches with issue IDs are automatically detected by the CLI