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:

bash

# Using Homebrew
brew install schpet/tap/linear

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

Setup

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

Add the API key to shell environment:

bash

# In ~/.bashrc or ~/.zshrc:
export LINEAR_API_KEY="lin_api_..."

# Or in fish:
set -Ux LINEAR_API_KEY="lin_api_..."

Run the configuration wizard in your project repository:
bash
```
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):

bash

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:

bash

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:

bash

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:

bash

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

Update Issues

Update existing issue details:

bash

linear issue update         # Interactive prompts for current issue

Delete Issues

Remove an issue from Linear:

bash

linear issue delete

Create Pull Requests

Generate a GitHub PR with issue details via

gh pr create

bash

linear issue pr

Issue Comments

Manage comments on issues:

bash

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

bash

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

bash

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

Milestone Management

bash

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):

bash

# 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

Option	Environment Variable	TOML Key	Example
API key	`LINEAR_API_KEY`	`api_key`	`"lin_api_..."`
Team ID	`LINEAR_TEAM_ID`	`team_id`	`"TEAM_abc123"`
Workspace	`LINEAR_WORKSPACE`	`workspace`	`"mycompany"`
Issue sort	`LINEAR_ISSUE_SORT`	`issue_sort`	`"priority"` or `"manual"`
VCS	`LINEAR_VCS`	`vcs`	`"git"` or `"jj"`
Download images	`LINEAR_DOWNLOAD_IMAGES`	`download_images`	`true` or `false`

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

List assigned issues:
```
linear issue list
```
Start working:
```
linear issue start
```
(choose interactively)
View details:
```
linear issue view
```
When done: create PR with
```
linear issue pr
```

Creating a Task

Create issue:

linear issue create -t "Task title" -d "Description"

Start working:
```
linear issue start <issue-id>
```
Track progress in the branch

Reviewing Issues

List all unstarted issues:
```
linear issue list -A
```
View specific issue:
```
linear issue view <issue-id>
```
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

linear-cli

NPX Install

Tags

SKILL.md Content

Linear CLI Skill

Installation

Setup

Issue Management

View Issues

List Issues

Start Working on an Issue

Create Issues

Update Issues

Delete Issues

Create Pull Requests

Issue Comments

Team Management

Project Management

Milestone Management

Document Management

Configuration Options

Version Control Integration

Common Workflows

Daily Workflow

Creating a Task

Reviewing Issues

Tips