Linear CLI

    __    _                       ________    ____
   / /   (_)___  ___  ____  _____/ ____/ /   /  _/
  / /   / / __ \/ _ \/ __ `/ ___/ /   / /    / /
 / /___/ / / / /  __/ /_/ / /  / /___/ /____/ /
/_____/_/_/ /_/\___/\__,_/_/   \____/_____/___/

Fast, scriptable Linear issue management from your terminal

A command-line interface for Linear that lets you manage issues, projects, and teams without leaving your terminal. Built in Rust for speed and reliability.

Quick Start
Installation
Authentication
Features
Usage
Configuration
Shell Completions
Scripting and Integration
Development
Performance
License

Quick Start

git clone https://github.com/TrevorS/linear-cli.git
cd linear-cli
make install

# Authenticate
linear login

# Start using
linear issues --assignee me

Installation

From Source

git clone https://github.com/TrevorS/linear-cli.git
cd linear-cli
make install

Authentication

OAuth

linear login   # Interactive browser-based authentication
linear logout  # Clear stored credentials

API Key

Get a Linear API key at https://linear.app/settings/api:

export LINEAR_API_KEY=lin_api_xxxxx

For development, add to .env:

LINEAR_API_KEY=lin_api_xxxxx

Scopes: mutations that aren't issue/comment creation — such as relate (which calls issueRelationCreate) — require the write scope. Create the key with full access (or include write); a read- or create-only key returns Invalid scope: 'write' required. OAuth logins request read,write automatically.

Features

Issue Management: List, view, create, update, close, reopen, and attach URLs to issues
Rich Terminal Output: Color-coded tables with syntax-highlighted markdown
Flexible Input: CLI arguments, interactive prompts, or markdown files with frontmatter
Smart Terminal Detection: Automatic color/formatting based on TTY capabilities
Multiple Output Formats: Formatted tables, JSON, or YAML
Configuration System: TOML configs with aliases and XDG compliance
Shell Integration: Completions for bash, zsh, fish, and PowerShell
Cross-Platform: Linux, macOS, and Windows support

Usage

List Issues

# Recent issues
linear issues

# Filter by assignee
linear issues --assignee me
linear issues --assignee alice
linear issues --assignee unassigned

# Filter by creator
linear issues --creator me
linear issues --creator katya

# Filter by status
linear issues --status "In Progress"
linear issues --status done

# Filter by team
linear issues --team ENG

# Combine filters
linear issues --assignee me --status todo --team ENG
linear issues --assignee me --creator katya

# JSON output for scripting
linear issues --json | jq '.[] | select(.priority == 1)'

# Pretty printed JSON
linear issues --json --pretty

View Issue Details

linear issue ENG-123              # Full details with description
linear issue ENG-123 --json       # JSON output
linear issue ENG-123 --raw        # Plain markdown

Create Issues

# Interactive mode
linear create

# Command line
linear create \
  --title "Fix authentication timeout" \
  --team ENG \
  --assignee me \
  --priority 1

# With labels, estimate, and cycle
linear create \
  --title "Fix auth timeout" \
  --team ENG \
  --label bug \
  --label backend \
  --estimate 3 \
  --cycle current

# From markdown file
linear create --from-file issue.md

# Dry run (preview without creating)
linear create --title "Test issue" --team ENG --dry-run

# Open created issue in browser
linear create --title "Test issue" --team ENG --open

Creating from Markdown Files

Create issue.md:

---
title: "Fix authentication race condition"
team: ENG
assignee: me
priority: 1
estimate: 3
labels:
  - bug
  - backend
cycle: current
---

# Problem

Users experiencing login failures when multiple tabs are open.

## Steps to Reproduce

1. Open multiple browser tabs
2. Login from each tab simultaneously
3. Some requests fail with timeout errors

## Expected Behavior

All login attempts should succeed or fail gracefully.

Then:

linear create --from-file issue.md

Manage Issues

# Update issue status
linear update ENG-123 --status "In Progress"

# Update labels, estimate, cycle
linear update ENG-123 --label bug --label critical --estimate 5 --cycle current

# Close issue
linear close ENG-123

# Reopen issue
linear reopen ENG-123

# Add comment
linear comment ENG-123 "Fixed in PR #456"

# Attach a URL (e.g., a pull request)
linear attach ENG-123 --url https://github.com/org/repo/pull/42
linear attach ENG-123 --url https://github.com/org/repo/pull/42 --title "Fix PR"

Browse Projects and Teams

# List projects
linear projects

# List teams
linear teams

# View comments on an issue
linear comments ENG-123

# Search across issues
linear search "authentication bug"

Your Work

# See your assigned and created issues
linear my-work

# Morning standup helper
linear issues --assignee me --status "In Progress"

Example Output

┌─────────┬───────────────────────────────────┬──────────┬─────────────┬──────────┐
│ ID      │ Title                             │ Assignee │ Status      │ Priority │
├─────────┼───────────────────────────────────┼──────────┼─────────────┼──────────┤
│ ENG-123 │ Fix authentication timeout        │ alice    │ Todo        │ High     │
│ ENG-124 │ Add user preferences UI           │ bob      │ In Progress │ Medium   │
│ ENG-125 │ Optimize database queries         │ carol    │ In Review   │ Low      │
│ ENG-126 │ Update API documentation          │ dave     │ Done        │ Medium   │
└─────────┴───────────────────────────────────┴──────────┴─────────────┴──────────┘

Configuration

Linear CLI supports TOML configuration files:

Config Locations

./linear-cli.toml (project-specific)
$XDG_CONFIG_HOME/linear-cli/config.toml (user config)
~/.config/linear-cli/config.toml (fallback)

Example Configuration

# Default values
default_team = "ENG"
default_assignee = "me"
preferred_format = "table"

# Command aliases
[aliases]
my = ["issues", "--assignee", "me"]
todo = ["issues", "--status", "todo", "--assignee", "me"]
standup = ["issues", "--team", "ENG", "--updated-after", "yesterday"]

Using Aliases

linear my          # Expands to: linear issues --assignee me
linear todo        # Expands to: linear issues --status todo --assignee me
linear standup     # Show team's recent activity

Shell Completions

Generate and install completions for your shell:

# Generate completions
linear completions bash > ~/.local/share/bash-completion/completions/linear
linear completions zsh > ~/.zfunc/_linear
linear completions fish > ~/.config/fish/completions/linear.fish
linear completions powershell > linear_completions.ps1

Restart your shell or source the completion file.

Scripting and Integration

JSON Output

All commands support --json for machine-readable output:

# Get high-priority issues
linear issues --json | jq '.[] | select(.priority == 1) | .title'

# Count issues by status
linear issues --json | jq 'group_by(.status) | map({status: .[0].status, count: length})'

# Export team's work
linear issues --team ENG --json > team-issues.json

Exit Codes

0: Success
1: General error
2: Authentication error
3: Network error
4: Not found error

Development

The project uses a Make-based workflow:

# Setup development environment
make dev-setup

# Quick development check
make dev          # Format, lint, test

# Run with sample data
make run

# See all available commands
make help

Project Structure

linear-cli/
├── linear-cli/    # Main CLI binary
├── linear-sdk/    # Reusable Linear API client
└── xtask/         # Build automation tools

See CLAUDE.md for detailed development documentation.

License

MIT

TrevorS/linear-cli

README