Linear CLI

A modern command-line interface for Linear that brings powerful issue management directly to your terminal.

Features: Advanced filtering with exclusions, smart sorting, native Linear colors, and an intuitive interface inspired by GitHub CLI.

---

Table of Contents

• Features
• Prerequisites
• Installation
• Authentication
• Commands
  • Authentication
  • Issues
  • Comments
• Advanced Usage
  • Filtering
  • Exclusion Filters
  • Sorting
  • Combining Filters
• Examples
• Configuration
• Development
• Troubleshooting

---

Features

• List and view issues with rich, colorized output
• Advanced filtering by status, assignee, labels, and more
• Exclusion filters to remove unwanted results
• Smart sorting by updated date, created date, priority, or title
• Native Linear colors - status and labels use your workspace's configured colors
• Comment management - read and create issue comments
• Clean table layout with proper alignment and color support

---

Prerequisites

• Node.js >= 18.0.0
• npm or yarn
• A Linear account with API access

---

Installation

npm (Recommended)

Install globally via npm:

npm install -g @scmfury/linear-cli

Verify installation:

linear --version
linear --help

From Source (Development)

For development or contributing:

# Clone the repository
git clone https://github.com/otaviosoaresp/linear-cli.git
cd linear-cli

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (makes 'linear' command available)
npm link

---

Authentication

Before using the CLI, you must authenticate with your Linear API key.

Get Your API Key

1. Go to https://linear.app/settings/api
2. Generate a new Personal API Key
3. Copy the key (starts with lin_api_)

Login

linear auth login

You'll be prompted to enter your API key. The key is stored securely in ~/.config/linear-cli/config.json.

Alternative: Environment Variable

export LINEAR_API_KEY="lin_api_your_key_here"

---

Commands

Authentication Commands

linear auth login

Authenticate with your Linear API key.

linear auth login

---

Issue Commands

linear issue list [options]

List issues with optional filtering and sorting.

Options:

--status <status...>           Filter by status (supports multiple values)
--assignee <email...>          Filter by assignee email
--label <label...>             Filter by label
--exclude-status <status...>   Exclude issues with these statuses
--exclude-assignee <email...>  Exclude issues assigned to these users
--exclude-label <label...>     Exclude issues with these labels
--sort <field>                 Sort by: updated, created, priority, title (default: updated)
--order <order>                Sort order: asc, desc (default: desc)
--limit <number>               Limit number of results (default: 50)

Examples:

# List all issues
linear issue list

# List issues with limit
linear issue list --limit 20

# Filter by status
linear issue list --status "In Progress"

# Multiple statuses
linear issue list --status "In Progress" "Todo"

# Exclude completed issues
linear issue list --exclude-status "Done" "Canceled"

# Sort by priority
linear issue list --sort priority

# Filter and sort
linear issue list --status "In Progress" --sort created --limit 10

linear issue view <issue-id>

View detailed information about a specific issue.

Example:

linear issue view LIN-123

Output includes:

• Issue title and identifier
• Status (with color)
• Assignee
• Creator
• Team
• Priority (with color)
• Labels (with colors)
• Dates (created, updated, due)
• Estimate
• Description
• URL

---

Comment Commands

linear issue comment list <issue-id>

List all comments on an issue.

linear issue comment list LIN-123

linear issue comment create <issue-id> --body <text>

Create a new comment on an issue.

linear issue comment create LIN-123 --body "This looks great!"

---

Advanced Usage

Filtering

Filter issues using --status, --assignee, or --label flags. All filters support multiple values.

# Single value
linear issue list --status "In Progress"

# Multiple values
linear issue list --status "In Progress" "Todo" "Backlog"

# Multiple filter types
linear issue list --status "In Progress" --label "bug" --assignee "user@example.com"

Exclusion Filters

Exclude specific issues using exclusion flags. This is perfect for filtering out completed or canceled work.

# Exclude by status
linear issue list --exclude-status "Done" "Canceled"

# Exclude by label
linear issue list --exclude-label "wont-fix" "duplicate"

# Exclude by assignee
linear issue list --exclude-assignee "bot@example.com"

# Combine inclusion and exclusion
linear issue list --status "In Progress" --exclude-label "blocked"

Sorting

Sort results using the --sort flag.

Available sort fields:

• updated - Last updated date (default)
• created - Creation date
• priority - Priority level
• title - Alphabetical by title

Sort order:

• desc - Descending (default)
• asc - Ascending

# Most recently updated (default)
linear issue list --sort updated

# Oldest first
linear issue list --sort created --order asc

# Highest priority first
linear issue list --sort priority

# Alphabetical
linear issue list --sort title --order asc

Combining Filters

Combine multiple filters, exclusions, and sorting for powerful queries.

# Active bugs, sorted by priority
linear issue list --label "bug" --exclude-status "Done" --sort priority

# My issues that aren't blocked
linear issue list --assignee "me@example.com" --exclude-label "blocked"

# Recent backlog items
linear issue list --status "Backlog" --sort created --limit 20

# Everything except done/canceled, sorted by update
linear issue list --exclude-status "Done" "Canceled" --sort updated

---

Examples

Daily Workflow

# Check what's in progress
linear issue list --status "In Progress"

# See your assigned issues
linear issue list --assignee "your.email@company.com"

# Review backlog by priority
linear issue list --status "Backlog" --sort priority --limit 10

Bug Triage

# All open bugs
linear issue list --label "bug" --exclude-status "Done"

# High priority bugs
linear issue list --label "bug" --sort priority --limit 5

# Unassigned bugs
linear issue list --label "bug" --exclude-status "Done" --assignee "Unassigned"

Sprint Planning

# Everything except done/canceled
linear issue list --exclude-status "Done" "Canceled" --limit 50

# Backlog sorted by priority
linear issue list --status "Backlog" --sort priority

# Recently updated issues
linear issue list --sort updated --limit 20

Issue Investigation

# View issue details
linear issue view CAR-123

# Read comments
linear issue comment list CAR-123

# Add a comment
linear issue comment create CAR-123 --body "Investigating this issue"

---

Configuration

Configuration is stored in ~/.config/linear-cli/config.json

Structure:

{
  "apiKey": "lin_api_..."
}

You can also use the LINEAR_API_KEY environment variable, which takes precedence over the config file.

---

Development

Build

npm run build

Watch Mode

npm run dev

Project Structure

linear-cli/
├── src/
│   ├── commands/
│   │   ├── auth/
│   │   │   └── login.ts           # Authentication
│   │   └── issue/
│   │       ├── list.ts            # List issues with filters
│   │       ├── view.ts            # View issue details
│   │       └── comment.ts         # Comment management
│   ├── core/
│   │   ├── config.ts              # Config management
│   │   └── client.ts              # Linear API client
│   ├── utils/
│   │   ├── colors.ts              # Color conversion and badges
│   │   ├── display.ts             # Table and output formatting
│   │   ├── errors.ts              # Error handling
│   │   └── filters.ts             # Filter parsing and building
│   └── index.ts                   # CLI entry point
├── dist/                          # Compiled output
├── package.json
├── tsconfig.json
└── README.md

---

Troubleshooting

Command not found: linear

Make sure you ran npm link after building:

npm run build
npm link

Authentication errors

Verify your API key is valid:

# Re-authenticate
linear auth login

# Or set environment variable
export LINEAR_API_KEY="lin_api_your_key_here"

Colors not showing

Colors should work automatically in most terminals. If colors aren't appearing, ensure your terminal supports ANSI colors.

Issues not showing

Check your filters - you might be excluding everything:

# List without filters first
linear issue list --limit 5

TypeScript errors during build

Make sure you have the correct Node.js version and all dependencies installed:

node --version  # Should be >= 18.0.0
npm install
npm run build

---

Tech Stack

• TypeScript - Type-safe development
• Linear SDK - Official Linear GraphQL client
• Commander.js - CLI framework
• Picocolors - Terminal colors

---

License

MIT

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.