Agent skill

linear-cli

This skill should be used when users need to manage Linear issues, tasks, or projects via command line. Triggers on requests mentioning Linear issues, issue tracking, creating issues, updating issue status, managing Linear projects, or Linear CLI operations.

View SKILL.md on GitHub Repository
Stars 1
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/oldwinter/skills/tree/main/lenny-skills/product-skills/linear-cli

SKILL.md

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

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

  2. 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_..."

  3. 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

  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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

oldwinter/skills

fundraising

Plan and run an early-stage fundraising process and produce a Fundraising Pack (raise decision memo, round design brief, pitch narrative + deck outline, investor pipeline + tracker, outreach/follow-up scripts, diligence checklist). Use for fundraising, raising capital, venture capital, pitch deck, investor outreach, pre-seed, seed. Category: Career.

1 0
Explore
oldwinter/skills

ai-evaluation-evals

Create AI evaluation plans with benchmarks, rubrics, and error analysis workflows.

1 0
Explore
oldwinter/skills

giving-presentations

Plan and deliver persuasive, confident presentations and produce a Presentation Pack (brief, narrative, slide outline, Q&A bank, pre-brief plan, rehearsal plan, delivery checklist). Use for presentation, deck, keynote, all-hands, exec review, demo talk track. Category: Communication.

1 0
Explore
oldwinter/skills

personal-productivity

Build a Personal Productivity System Pack (weekly timebox plan, capture+to-do system, daily/weekly review rituals, and a 7-day rollout). Use for timeboxing, calendar blocking, and staying on top of high-volume leadership work. Category: Career.

1 0
Explore
oldwinter/skills

ai-product-strategy

Create an AI Product Strategy Pack (thesis, prioritized use cases, system plan, eval + learning plan, agentic safety plan, roadmap). Use for AI product strategy, LLM/agent strategy, AI roadmap, AI-first product direction.

1 0
Explore
oldwinter/skills

career-transitions

Plan and execute a career transition and produce a Career Transition Pack (progress metric + push/pull map, target archetypes, option scorecard, opportunity pipeline + outreach scripts, skills plan, 4–12 week experiment plan). Use for career change, career pivot, career transition, switching roles. Category: Career.

1 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results