linear-cli

A fast, comprehensive command-line interface for Linear built in Rust. Manage issues, projects, cycles, sprints, documents, and more -- entirely from your terminal.

Installation

# From crates.io
cargo install linear-cli

# With OS keyring support (Keychain, Credential Manager, Secret Service)
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 are available at GitHub Releases.

Quick Start

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

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

# 2. List your issues
linear-cli i list --mine

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

# 4. When done, mark complete and create a PR
linear-cli done
linear-cli g pr LIN-123

Commands

Issues

Full issue lifecycle management with 16 subcommands.

linear-cli issues list                           # List issues
linear-cli i list -t ENG --mine                  # My issues on a team
linear-cli i list --since 7d --group-by state    # Last 7 days, grouped by status
linear-cli i list --label bug --count-only       # Count bugs
linear-cli i list --view "My Sprint"             # Apply a saved custom view

linear-cli i get LIN-123                         # Issue details
linear-cli i get LIN-123 --history               # Activity timeline
linear-cli i get LIN-123 --comments              # Inline comments
linear-cli i get LIN-1 LIN-2 LIN-3              # Batch fetch

linear-cli i create "Fix login" -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

linear-cli i start LIN-123 --checkout            # Start + checkout branch
linear-cli i stop LIN-123                        # Return to backlog
linear-cli i close LIN-123                       # Mark as Done
linear-cli i assign LIN-123 "Alice"              # Assign to user
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 archive LIN-123                     # Archive
linear-cli i open LIN-123                        # Open in browser
linear-cli i link LIN-123                        # Print URL

List flags: --mine, --team, --state, --assignee, --project, --label, --since, --view, --group-by (state/priority/assignee/project), --count-only, --archived

Projects

Full project CRUD with label management and archiving.

linear-cli projects list                         # List all projects
linear-cli p get "Q1 Roadmap"                    # Project details
linear-cli p create "New Feature" -t ENG         # Create project
linear-cli p update PROJECT_ID --name "Renamed"  # Update project
linear-cli p members "Q1 Roadmap"                # List members
linear-cli p add-labels PROJECT_ID bug           # Add labels
linear-cli p remove-labels PROJECT_ID bug        # Remove labels
linear-cli p set-labels PROJECT_ID bug feat      # Replace all labels
linear-cli p archive PROJECT_ID                  # Archive
linear-cli p unarchive PROJECT_ID                # Unarchive
linear-cli p open "Q1 Roadmap"                   # Open in browser
linear-cli p delete PROJECT_ID                   # Delete

Project Updates

Track project health with status updates (onTrack, atRisk, offTrack).

linear-cli project-updates list PROJECT_ID       # List updates
linear-cli pu get UPDATE_ID                      # Get update details
linear-cli pu create PROJECT_ID -b "On track"    # Create update
linear-cli pu update UPDATE_ID -b "Updated"      # Edit update
linear-cli pu archive UPDATE_ID                  # Archive
linear-cli pu unarchive UPDATE_ID                # Unarchive

Teams

linear-cli teams list                            # List all teams
linear-cli t get ENG                             # Team details
linear-cli t members ENG                         # List members
linear-cli t create "Platform" -k PLT            # Create team
linear-cli t update TEAM_ID --name "Infra"       # Update team
linear-cli t delete TEAM_ID                      # Delete team

Cycles

linear-cli cycles list -t ENG                    # List cycles
linear-cli c current -t ENG                      # Current cycle
linear-cli c get CYCLE_ID                        # Cycle details with issues
linear-cli c create -t ENG --start 2026-03-01 --end 2026-03-14
linear-cli c update CYCLE_ID --name "Sprint 5"
linear-cli c complete CYCLE_ID                   # Complete cycle
linear-cli c delete CYCLE_ID

Sprint Planning

Plan and manage cycle-based sprints with progress visualization, burndown charts, and velocity tracking.

linear-cli sprint status -t ENG                  # Current sprint status
linear-cli sp progress -t ENG                    # Progress bar visualization
linear-cli sp plan -t ENG                        # Next sprint's planned issues
linear-cli sp carry-over -t ENG --force          # Move incomplete to next cycle
linear-cli sp burndown -t ENG                    # ASCII burndown chart
linear-cli sp velocity -t ENG                    # Velocity across past 6 sprints
linear-cli sp velocity -t ENG -n 10              # Velocity across past 10 sprints

Documents, Labels, Comments

# Documents
linear-cli documents list                        # List documents
linear-cli d create "ADR-001" -c "Content..."    # Create document
linear-cli d update DOC_ID -c "Updated"          # Update
linear-cli d delete DOC_ID                       # Delete

# Labels
linear-cli labels list                           # List labels
linear-cli l create "priority:p0" -c "#FF0000"   # Create with color
linear-cli l update LABEL_ID -n "Renamed"        # Rename
linear-cli l delete LABEL_ID                     # Delete

# Comments
linear-cli comments list ISSUE_ID                # List comments
linear-cli cm create ISSUE_ID -b "Comment text"  # Add comment
linear-cli cm update COMMENT_ID -b "Edited"      # Edit
linear-cli cm delete COMMENT_ID                  # Delete

Milestones, Roadmaps, Initiatives

# Milestones
linear-cli milestones list -p "Q1 Roadmap"       # List project milestones
linear-cli ms create "Beta" -p PROJECT_ID        # Create milestone
linear-cli ms update MS_ID --name "GA"           # Update
linear-cli ms delete MS_ID                       # Delete

# Roadmaps
linear-cli roadmaps list                         # List roadmaps
linear-cli rm get ROADMAP_ID                     # Roadmap details
linear-cli rm create "2026 Plan"                 # Create
linear-cli rm update RM_ID --name "H1 2026"      # Update
linear-cli rm delete RM_ID                       # Delete

# Initiatives
linear-cli initiatives list                      # List initiatives
linear-cli init get INIT_ID                      # Initiative details
linear-cli init create "Platform Migration"      # Create
linear-cli init update INIT_ID --name "Renamed"  # Update
linear-cli init delete INIT_ID                   # Delete

Custom Views

linear-cli views list                            # List saved views
linear-cli v get VIEW_ID                         # View details
linear-cli v create "My Bugs" -t ENG             # Create view
linear-cli v update VIEW_ID --name "Open Bugs"   # Update
linear-cli v delete VIEW_ID                      # Delete
linear-cli i list --view "My Bugs"               # Apply view to issue list

Relations

linear-cli relations list LIN-123                # List relationships
linear-cli rel add LIN-123 blocks LIN-456        # Add relation
linear-cli rel remove LIN-123 blocks LIN-456     # Remove relation
linear-cli rel parent LIN-456 LIN-123            # Set parent issue
linear-cli rel unparent LIN-456                  # Remove parent

Attachments

linear-cli attachments list ISSUE_ID             # List attachments
linear-cli att get ATTACHMENT_ID                 # Get details
linear-cli att create ISSUE_ID -u URL -t "Doc"   # Create attachment
linear-cli att link-url ISSUE_ID URL             # Link a URL
linear-cli att update ATTACHMENT_ID -t "New"     # Update
linear-cli att delete ATTACHMENT_ID              # Delete

Templates

Local templates and Linear workspace (remote) templates.

# Local templates
linear-cli templates list                        # List local templates
linear-cli tpl create                            # Create interactively
linear-cli tpl show TEMPLATE_NAME                # Show details
linear-cli tpl delete TEMPLATE_NAME              # Delete

# Linear workspace templates
linear-cli tpl remote-list                       # List API templates
linear-cli tpl remote-get TEMPLATE_ID            # Get template
linear-cli tpl remote-create -n "Bug Report"     # Create
linear-cli tpl remote-update TEMPLATE_ID         # Update
linear-cli tpl remote-delete TEMPLATE_ID         # Delete

Notifications

linear-cli notifications list                    # Unread notifications
linear-cli n count                               # Unread count
linear-cli n read NOTIFICATION_ID                # Mark as read
linear-cli n read-all                            # Mark all as read
linear-cli n archive NOTIFICATION_ID             # Archive one
linear-cli n archive-all                         # Archive all

Statuses & Time Tracking

# Statuses
linear-cli statuses list -t ENG                  # List workflow states
linear-cli st update STATUS_ID --name "Review"   # Rename a status

# Time tracking
linear-cli time list ISSUE_ID                    # List time entries
linear-cli tm update ENTRY_ID --hours 2.5        # Update entry

Favorites

linear-cli favorites list                        # List favorites
linear-cli fav add ISSUE_ID                      # Add to favorites
linear-cli fav remove FAVORITE_ID                # Remove

Users

linear-cli users list                            # List workspace users
linear-cli u me                                  # Current user
linear-cli u get "alice@example.com"             # Look up a user
linear-cli whoami                                # Alias for `users me`

Webhooks

Full CRUD plus a local listener with HMAC-SHA256 signature verification.

linear-cli webhooks list                         # List webhooks
linear-cli wh get WEBHOOK_ID                     # Webhook details
linear-cli wh create https://hook.example.com    # Create webhook
linear-cli wh update WEBHOOK_ID --url NEW_URL    # Update
linear-cli wh rotate-secret WEBHOOK_ID           # Rotate signing secret
linear-cli wh delete WEBHOOK_ID                  # Delete
linear-cli wh listen --port 8080                 # Start local listener

Watch Mode

Poll for real-time changes to issues, projects, or teams.

linear-cli watch issue LIN-123                   # Watch an issue
linear-cli w project PROJECT_ID                  # Watch a project
linear-cli w team ENG                            # Watch a team

Triage

linear-cli triage list -t ENG                    # Unassigned issues
linear-cli tr claim LIN-123                      # Assign to self
linear-cli tr snooze LIN-123                     # Snooze for later

Bulk Operations

linear-cli bulk update-state LIN-1 LIN-2 -s Done   # Bulk status update
linear-cli b assign LIN-1 LIN-2 -a "Alice"         # Bulk assign
linear-cli b label LIN-1 LIN-2 -l bug              # Bulk add label
linear-cli b unassign LIN-1 LIN-2                   # Bulk unassign

Git Integration

Works with both Git and Jujutsu (jj).

linear-cli git checkout LIN-123                  # Create + checkout branch
linear-cli g branch LIN-123                      # Show branch name
linear-cli g create LIN-123                      # Create branch (no checkout)
linear-cli g commits                             # Commits with Linear trailers (jj)
linear-cli g pr LIN-123 --draft                  # Create GitHub PR

Import / Export

Round-trip CSV and JSON import/export with field resolution for status, assignee, and labels.

# Import
linear-cli import csv issues.csv -t ENG          # Import from CSV
linear-cli import json issues.json -t ENG        # Import from JSON
linear-cli import csv issues.csv -t ENG --dry-run  # Preview without creating

# Export
linear-cli export csv -t ENG -f issues.csv       # Export issues to CSV
linear-cli export json -t ENG -f issues.json     # Export issues to JSON
linear-cli export markdown -t ENG                # Export to Markdown
linear-cli export projects-csv -f projects.csv   # Export projects to CSV

Search & Context

linear-cli search issues "auth bug"              # Search issues
linear-cli s projects "platform"                 # Search projects
linear-cli context                               # Issue from current git branch
linear-cli history LIN-123                       # Activity timeline
linear-cli metrics -t ENG                        # Team velocity and stats

Raw GraphQL

Direct API access for anything not covered by built-in commands.

linear-cli api query '{ viewer { name email } }'
linear-cli api mutate 'mutation { issueUpdate(id: "...", input: { ... }) { success } }'

Other Commands

linear-cli done                                  # Mark current branch issue as Done
linear-cli interactive                           # TUI for browsing/managing issues
linear-cli sync status                           # Compare local folders with Linear
linear-cli sync push                             # Create Linear projects from folders

Authentication

Two authentication methods are supported. Both can be used per-profile.

API Key

# Set directly
linear-cli config set-key lin_api_xxxxxxxxxxxxx

# Or interactive login
linear-cli auth login

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

# Or use environment variable (highest priority)
export LINEAR_API_KEY=lin_api_xxx

OAuth 2.0

Browser-based Authorization Code + PKCE flow with automatic token refresh.

linear-cli auth oauth          # Opens browser for authorization
linear-cli auth status         # Show auth type, token expiry
linear-cli auth revoke         # Revoke OAuth tokens
linear-cli auth logout         # Remove stored credentials

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

Configuration

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

linear-cli config show                           # Show current config
linear-cli config get default_team               # Get a value
linear-cli config set default_team ENG           # Set a value

# Multiple workspaces
linear-cli config workspace-add work             # Add workspace profile
linear-cli config workspace-list                 # List profiles
linear-cli config workspace-switch work          # Switch active profile
linear-cli config workspace-current              # Show current
linear-cli config workspace-remove work          # Remove profile

# Per-invocation profile override
linear-cli --profile work i list
export LINEAR_CLI_PROFILE=work

Setup & Diagnostics

linear-cli setup                                 # Guided onboarding wizard
linear-cli doctor                                # Check config + connectivity
linear-cli doctor --fix                          # Auto-remediate issues
linear-cli cache status                          # Cache stats
linear-cli cache clear                           # Clear cache

Shell Completions

Static Completions

Generate tab completions for command names and flags.

# Bash
linear-cli completions static bash > ~/.bash_completion.d/linear-cli

# Zsh
linear-cli completions static zsh > ~/.zfunc/_linear-cli

# Fish
linear-cli completions static fish > ~/.config/fish/completions/linear-cli.fish

# PowerShell
linear-cli completions static powershell > linear-cli.ps1

Dynamic Completions

Context-aware completions that query the Linear API for team names, project names, issue identifiers, statuses, and more.

linear-cli completions dynamic bash              # Dynamic bash completions
linear-cli completions dynamic zsh               # Dynamic zsh completions
linear-cli completions dynamic fish              # Dynamic fish completions
linear-cli completions dynamic powershell        # Dynamic PowerShell completions

Legacy alias: linear-cli config completions <shell> also generates static completions.

Agent & Automation Usage

linear-cli is designed to work well with AI agents and scripts. Every command supports machine-readable output.

Output Flags

Flag	Purpose
--output json	JSON output (also ndjson)
--compact	Compact JSON (no pretty-printing)
--fields a,b,c	Limit JSON to specific fields (dot paths supported)
--sort field	Sort JSON arrays by field
--order asc|desc	Sort direction
--quiet	Suppress decorative output
--id-only	Only output resource ID (for chaining)
--format tpl	Template output, e.g. "{{identifier}} {{title}}"
--filter f=v	Client-side filter (=, !=, ~=; dot paths; case-insensitive)
--fail-on-empty	Non-zero exit when list is empty
--dry-run	Preview without making changes
--yes	Auto-confirm all prompts
--no-pager	Disable auto-paging
--no-cache	Bypass cache

Scripting Examples

# Get issue ID for chaining
ID=$(linear-cli i create "Bug" -t ENG --id-only --quiet)

# JSON output for programmatic consumption
linear-cli i list --output json --fields identifier,title,state.name --compact

# Pipe description from file
cat desc.md | linear-cli i create "Title" -t ENG -d -

# JSON input for structured create/update
cat issue.json | linear-cli i create "Title" -t ENG --data -

# Default JSON for entire session
export LINEAR_CLI_OUTPUT=json

# Batch get with structured output
linear-cli i get LIN-1 LIN-2 LIN-3 --output json --compact

Exit Codes

Code	Meaning
0	Success
1	General error
2	Not found
3	Auth error
4	Rate limited

Pagination

linear-cli i list --limit 25                     # Limit results
linear-cli i list --all --page-size 100           # Fetch all pages
linear-cli i list --after CURSOR                  # Cursor-based pagination

Agent Skills

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

# Install all skills
npx skills add Finesssee/linear-cli

# Install specific skill
npx skills add Finesssee/linear-cli --skill linear-workflow

27 skills covering issues, git, planning, organization, operations, and tracking. Skills are 10-50x more token-efficient than MCP tools. See docs/skills.md for details.

Key Features

• 50+ commands across 30+ command groups with short aliases
• OAuth 2.0 + PKCE authentication alongside API key auth
• Dynamic shell completions for bash, zsh, fish, and PowerShell
• Import/Export with round-trip CSV and JSON support
• Sprint planning with progress bars, burndown charts, velocity tracking, and carry-over between cycles
• Webhook listener with HMAC-SHA256 signature verification
• Watch mode for real-time polling on issues, projects, and teams
• Custom views that can be applied to issue and project lists
• Bulk operations for updating, assigning, and labeling multiple issues
• Git and Jujutsu (jj) support for branch management and PR creation
• Interactive TUI for browsing and managing issues
• Template system with both local and Linear workspace templates
• Auto-paging output through less on Unix terminals
• Multiple workspaces with named profiles and seamless switching
• Reliable networking with HTTP timeouts, jittered retries, and atomic cache writes

Documentation

• Agent Skills -- 27 skills for AI agents
• AI Agent Integration -- Setup for Claude Code, Cursor, Codex
• Usage Examples -- Detailed command examples
• Workflows -- Common workflow patterns
• JSON Samples -- Example JSON output shapes
• Shell Completions -- Tab completion setup

Comparison with Other CLIs

Feature	@linear/cli	linear-go	linear-cli
Last updated	2021	2023	2026
Commands	~10	~10	50+
Agent Skills	No	No	27 skills
OAuth 2.0 (PKCE)	No	No	Yes
Sprint planning	No	No	status, progress, burndown, velocity, carry-over
Import/Export	No	No	CSV, JSON, Markdown
Webhooks + listener	No	No	CRUD + HMAC-SHA256 listener
Custom views	No	No	Full CRUD + apply
Project updates	No	No	CRUD + health status
Templates (local + remote)	No	No	Full CRUD
Dynamic completions	No	No	bash/zsh/fish/pwsh
Issue workflow actions	No	No	assign, move, transfer, close, archive
Bulk operations	No	No	Yes
Watch mode	No	No	issue, project, team
Raw GraphQL API	No	No	query + mutate
Git + jj support	No	No	Yes
Interactive TUI	No	No	Yes
Multiple workspaces	No	No	Yes
JSON output	No	Yes	JSON, NDJSON, templates

Contributing

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

License

MIT