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

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