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

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

# 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

# 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

Contributing

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

License

MIT