linear-cli

name	linear-cli
description	Manages Linear issues via CLI. Use when user wants to view, start, create, or update Linear issues, create PRs from issues, or configure Linear integration.

Linear CLI

Goal

Help users manage Linear issues from the terminal—view current work, start issues, create branches, open PRs, and stay in flow.

When to use

• User asks about their Linear issues or current issue
• User wants to start working on a Linear issue
• User wants to create a PR for a Linear issue
• User needs to create, update, or comment on issues
• User wants to configure Linear CLI for a project

When not to use

• User is asking about Linear the company or product (not CLI usage)
• User wants Linear API integration in code (point them to Linear SDK)
• User needs Jira, GitHub Issues, or other trackers

Prerequisites

• linear CLI installed (brew install schpet/tap/linear)
• LINEAR_API_KEY environment variable set (from linear.app/settings/account/security)
• For PR creation: GitHub CLI (gh) installed and authenticated

Default workflow

1) Check current context

linear issue view        # See current issue (detected from branch)
linear issue id          # Just the issue ID

2) Start an issue

linear issue list        # Show your unstarted issues
linear issue start       # Interactive: pick issue, creates branch
linear issue start ABC-123  # Start specific issue directly

3) Create PR when ready

linear issue pr          # Creates GitHub PR with title/description prefilled

Common commands

Task	Command
View current issue	linear issue view
View in browser	linear issue view -w
List my issues	linear issue list
List all unstarted	linear issue list -A
Start issue	linear issue start or linear issue start ABC-123
Create PR	linear issue pr
Create issue	linear issue create -t "Title" -d "Description"
Add comment	linear issue comment add
List teams	linear team list
Configure	linear config

Configuration

Run linear config to generate .linear.toml in your repo. Key settings:

api_key = "lin_api_..."      # Or use LINEAR_API_KEY env var
team_id = "TEAM_abc123"      # Default team for new issues
workspace = "mycompany"      # Your Linear workspace slug
issue_sort = "priority"      # Or "manual"
vcs = "git"                  # Or "jj" for Jujutsu

Config file locations (checked in order):

1. ./.linear.toml (project root)
2. ~/.config/linear/linear.toml (global)

Validation checklist

• linear --version runs (CLI installed)
• linear issue list works (API key valid)
• linear team list shows teams (workspace configured)
• Branch naming matches Linear's pattern for auto-detection

Troubleshooting

"No issue found for current branch"

• Branch name must contain issue ID (e.g., feat/abc-123-description)
• Or specify issue: linear issue view ABC-123

"Unauthorized" errors

• Check LINEAR_API_KEY is set and valid
• Regenerate key at linear.app/settings/account/security

PR creation fails

• Ensure gh CLI is installed and authenticated (gh auth status)
• Must be on a branch with a Linear issue

Examples

Example 1: Start morning work

$ linear issue list
# Shows unstarted issues assigned to you

$ linear issue start
# Interactive picker → selects issue → creates branch → switches to it

$ linear issue view
# Confirms you're on the right issue

Example 2: Create PR for completed work

$ linear issue view
# Review issue details

$ linear issue pr
# Opens GitHub PR with:
#   - Title: "ABC-123: Issue title"
#   - Description: Issue description + Linear link

Example 3: Quick issue creation

$ linear issue create -t "Fix login timeout" -d "Users report 30s timeout on slow connections"
# Creates issue, outputs issue ID