linear-cli

A fast, powerful command-line interface for Linear built with Rust.

Features

• Full API Coverage - Projects, issues, labels, teams, users, cycles, comments, documents
• Git Integration - Checkout branches for issues, create PRs linked to issues
• jj (Jujutsu) Support - First-class support for Jujutsu VCS alongside Git
• Interactive Mode - TUI for browsing and managing issues
• Multiple Workspaces - Switch between Linear workspaces seamlessly
• Profiles & Auth - Named profiles with auth login/logout/status
• Bulk Operations - Perform actions on multiple issues at once
• JSON/NDJSON Output - Machine-readable output for scripting and agents
• Pagination & Filters - --limit, --page-size, --all, --filter
• Diagnostics - doctor command for config and connectivity checks
• Fast - Native Rust binary, no runtime dependencies

Installation

# From crates.io
cargo install linear-cli

# From source
git clone https://github.com/Finesssee/linear-cli.git
cd linear-cli && cargo build --release

Pre-built binaries available at GitHub Releases.

Quick Start

# 1. Configure your API key (get one at https://linear.app/settings/api)
linear-cli config set-key lin_api_xxxxxxxxxxxxx

# 2. List your issues
linear-cli i list

# 3. Start working on an issue (assigns, sets In Progress, creates branch)
linear-cli i start LIN-123 --checkout

# 4. Create a PR when done
linear-cli g pr LIN-123

Commands

Command	Alias	Description
issues	i	Manage issues
projects	p	Manage projects
git	g	Git branch operations and PR creation
search	s	Search issues and projects
comments	cm	Manage issue comments
uploads	up	Fetch uploads/attachments
bulk	b	Bulk operations on issues
labels	l	Manage labels
teams	t	List and view teams
cycles	c	Manage sprint cycles
relations	rel	Manage issue relations (blocks, duplicates, etc.)
export	ex	Export issues to JSON/CSV
favorites	fav	Manage favorites
history	hist	View issue history and audit logs
initiatives	init	Manage initiatives
metrics	met	View workspace metrics
roadmaps	rm	Manage roadmaps
triage	tr	Triage responsibility management
watch	w	Watch issues for changes
sync	sy	Sync local folders with Linear
interactive	ui	Interactive TUI mode
config	-	CLI configuration
common	tasks	Common tasks and examples
agent	-	Agent-focused capabilities and examples
auth	-	API key management and status
doctor	-	Diagnose config and connectivity
cache	ca	Cache inspection and clearing

Run linear-cli <command> --help for detailed usage.

Common Examples

# Issues
linear-cli i list -t Engineering           # List team's issues
linear-cli i create "Bug" -t ENG -p 1      # Create urgent issue
linear-cli i update LIN-123 -s Done        # Update status
linear-cli i update LIN-123 -l bug -l urgent  # Add labels
linear-cli i update LIN-123 --due tomorrow    # Set due date
linear-cli i update LIN-123 -e 3              # Set estimate (3 points)

# Git workflow
linear-cli g checkout LIN-123              # Create branch for issue
linear-cli g pr LIN-123 --draft            # Create draft PR

# Search
linear-cli s issues "auth bug"             # Search issues

# Export
linear-cli export issues -t ENG -o issues.json  # Export to JSON
linear-cli export issues -t ENG --csv           # Export to CSV

# Relations
linear-cli rel add LIN-123 blocks LIN-456       # LIN-123 blocks LIN-456
linear-cli rel list LIN-123                     # List issue relations

# JSON output (great for AI agents)
linear-cli i get LIN-123 --output json
linear-cli cm list ISSUE_ID --output ndjson

# Pagination + filters
linear-cli i list --limit 25 --sort identifier
linear-cli i list --all --page-size 100 --filter state.name=In\ Progress

# Template output
linear-cli i list --format "{{identifier}} {{title}}"

# Profiles
linear-cli --profile work auth login
linear-cli --profile work i list

# Disable color for logs/CI
linear-cli i list --no-color

See docs/examples.md for comprehensive examples.

Configuration

# Set API key
linear-cli config set-key YOUR_API_KEY

# Or use auth login
linear-cli auth login

# Or use environment variable
export LINEAR_API_KEY=lin_api_xxx

# Override profile per invocation
export LINEAR_CLI_PROFILE=work

Config stored at ~/.config/linear-cli/config.toml (Linux/macOS) or %APPDATA%\linear-cli\config.toml (Windows).

Documentation

• Usage Examples - Detailed command examples
• Workflows - Common workflow patterns
• AI Agent Integration - Setup for Claude Code, Cursor, OpenAI Codex
• Agent Skills - Pre-built skills for Claude Code and OpenAI Codex
• JSON Samples - Example JSON output shapes
• JSON Schema - Schema version reference
• Shell Completions - Tab completion setup

Comparison with Other CLIs

Feature	@linear/cli	linear-go	linear-cli
Last updated	2021	2023	2026
Git PR creation	No	No	Yes
jj (Jujutsu) support	No	No	Yes
Interactive TUI	No	No	Yes
Bulk operations	No	No	Yes
Multiple workspaces	No	No	Yes
JSON output	No	Yes	Yes

Contributing

Contributions welcome! Please open an issue or submit a pull request.

License

MIT