linear-cli

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

Features

• Full API Coverage - Issues, projects, labels, teams, users, cycles, comments, documents, milestones, roadmaps, initiatives, webhooks, custom views
• OAuth 2.0 - Browser-based PKCE auth with auto-refresh, plus API key support
• Issue Workflow - Start, stop, close, archive, assign, move, transfer, comment, link
• 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 with assignee, status, label selection
• Multiple Workspaces - Switch between Linear workspaces seamlessly
• Profiles & Auth - Named profiles with auth login/logout/status/oauth/revoke
• Secure Storage - Optional OS keyring support (Keychain, Credential Manager, Secret Service)
• Bulk Operations - Perform actions on multiple issues at once
• JSON/NDJSON Output - Machine-readable output for scripting and agents
• Smart Sorting - Numeric and date-aware sorting (10 > 9, not "10" < "9")
• Pagination & Filters - --limit, --page-size, --all, --filter, --since, --mine, --label
• Grouping - --group-by for kanban-style output by state, priority, assignee, or project
• Webhooks - Full CRUD + real-time listener with HMAC-SHA256 signature verification
• Raw GraphQL - api query and api mutate for direct API access
• Activity History - --history and --comments flags on issue details
• Markdown Stripping - Clean terminal display of issue descriptions
• Auto-Paging - Output auto-pages through less on Unix terminals
• Reliable - HTTP timeouts, jittered retries, atomic cache writes
• Diagnostics - doctor command for config and connectivity checks
• Fast - Native Rust binary, no runtime dependencies

Installation

# From crates.io
cargo install linear-cli

# With secure storage (OS keyring support)
cargo install linear-cli --features secure-storage

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

Pre-built binaries available at GitHub Releases.

Agent Skills

linear-cli includes Agent Skills for AI coding assistants (Claude Code, Cursor, Codex, etc.).

# Install all skills for your AI agent
npx skills add Finesssee/linear-cli

# Or install specific skills
npx skills add Finesssee/linear-cli --skill linear-list
npx skills add Finesssee/linear-cli --skill linear-workflow

27 skills covering all CLI features:

Skills are 10-50x more token-efficient than MCP tools.

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 list --mine                   # List my issues
linear-cli i list --since 7d               # Issues from last 7 days
linear-cli i list --group-by state         # Group by status (kanban style)
linear-cli i list --count-only             # Just show count
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)
linear-cli i get LIN-123 --history         # Show activity timeline
linear-cli i get LIN-123 --comments        # Show inline comments
linear-cli i assign LIN-123 "Alice"        # Assign to user
linear-cli i assign LIN-123               # Unassign
linear-cli i move LIN-123 "Q2 Project"     # Move to project
linear-cli i transfer LIN-123 ENG          # Transfer to team
linear-cli i comment LIN-123 -b "LGTM"    # Add comment
linear-cli i close LIN-123                 # Mark as done
linear-cli i open LIN-123                  # Open in browser
linear-cli i link LIN-123                  # Print URL

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

# OAuth authentication
linear-cli auth oauth                      # Browser-based OAuth login
linear-cli auth status                     # Show auth type and token info
linear-cli auth revoke                     # Revoke OAuth tokens

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

# Teams & Users
linear-cli t members ENG                   # List team members
linear-cli u get "alice@example.com"       # Look up a user
linear-cli whoami                          # Show current user

# Projects
linear-cli p members "Q1 Roadmap"          # List project members
linear-cli p open "Q1 Roadmap"             # Open in browser

# Cycles
linear-cli c get CYCLE_ID                  # Cycle details with issues
linear-cli c current -t ENG               # Show current cycle

# Milestones
linear-cli ms list -p "Q1 Roadmap"         # List project milestones
linear-cli ms create "Beta" -p PROJECT_ID  # Create milestone

# Labels
linear-cli l update LABEL_ID -n "Renamed"  # Rename a label
linear-cli l update LABEL_ID -c "#FF5733"  # Change label color

# Webhooks
linear-cli wh create https://hook.example.com  # Create webhook
linear-cli wh listen --port 8080               # Listen for events

# Raw GraphQL
linear-cli api query '{ viewer { name } }'     # Raw query
linear-cli api mutate 'mutation { ... }'       # Raw mutation

# Export
linear-cli export csv -t ENG -f issues.csv    # Export to CSV (RFC 4180)
linear-cli export markdown -t ENG             # Export to Markdown

# JSON output (great for AI agents)
linear-cli i get LIN-123 --output json --compact
linear-cli i list --output json --fields identifier,title,state.name
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 (stored in config file)
linear-cli config set-key YOUR_API_KEY

# Or use auth login
linear-cli auth login

# OAuth 2.0 (browser-based, auto-refreshing tokens)
linear-cli auth oauth

# Store in OS keyring (requires --features secure-storage)
linear-cli auth login --secure

# Migrate existing keys to keyring
linear-cli auth migrate

# Check auth status (shows auth type, token expiry)
linear-cli auth status

# Revoke OAuth tokens
linear-cli auth revoke

# Or use environment variable
export LINEAR_API_KEY=lin_api_xxx

# Override profile per invocation
export LINEAR_CLI_PROFILE=work

Auth priority: LINEAR_API_KEY env var > OS keyring > OAuth tokens > config file API key.

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

Cache is scoped per profile at ~/.config/linear-cli/cache/{profile}/.

Documentation

• Agent Skills - 27 skills for AI agents
• AI Agent Integration - Setup for Claude Code, Cursor, OpenAI Codex
• Usage Examples - Detailed command examples
• Workflows - Common workflow patterns
• 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