Linearator

A comprehensive command-line interface for Linear issue management, enabling efficient project workflow automation and team collaboration through the Linear API.

Overview

Linearator is a powerful CLI tool that streamlines Linear project management workflows by providing command-line access to core Linear functionality. Built with Python and designed for developers, project managers, and teams who prefer terminal-based workflows or need to automate Linear operations.

Key Features

Core Issue Management

• Full CRUD Operations: Create, read, update, and delete Linear issues
• Advanced Filtering: Filter issues by status, assignee, labels, teams, and custom criteria
• Bulk Operations: Perform batch updates on multiple issues simultaneously
• Status Management: Update issue states, priorities, and assignments

Project Management

• Project Operations: List projects, view project details, and track project health
• Project Updates: Create and manage project status updates with health indicators
• Project Timeline: View project update history and track progress over time
• Smart Lookup: Reference projects by both ID and human-readable names

Team & Label Management

• Team Operations: List teams, view team details, and manage team-specific configurations
• Label Management: Create, update, and apply labels to organize issues effectively
• User Management: View team members and workload analysis

Advanced Capabilities

• Powerful Search: Full-text search with advanced filtering capabilities
• Interactive Mode: Guided issue creation and management workflows
• Multiple Output Formats: JSON, table, and YAML formatting options
• Shell Integration: Command completion for efficient usage

Authentication & Security

• OAuth Flow: Secure authentication with Linear's OAuth system
• API Key Support: Alternative authentication method for automation
• Credential Management: Secure storage using system keyring
• Token Refresh: Automatic token renewal and session management

Installation

From PyPI (Recommended)

pip install linearator

From AUR

paru -S linear-cli

# Or:
yay -S linear-cli

From Source

git clone https://github.com/AdiKsOnDev/linearator.git
cd linearator
pip install -e .

Development Installation

git clone https://github.com/AdiKsOnDev/linearator.git
cd linearator
make install-dev

Quick Start

1. Authentication

First, authenticate with Linear:

# OAuth flow (recommended)
linear auth login

# Or use API key
linear auth login --api-key YOUR_API_KEY

# Or set environment variable
export LINEAR_API_KEY=YOUR_API_KEY

2. Basic Usage

# List your issues
linear issue list

# Create a new issue
linear issue create --title "Bug fix" --description "Fix login error" --team "ENG"

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

# Search issues
linear search "login bug" --status "Todo" --assignee "john@company.com"

3. Team and Project Operations

# List available teams
linear team list

# View team details
linear team show "Engineering"

# List projects
linear project list

# View project details
linear project show "My Project"

Command Reference

Issue Commands

# Create issues
linear issue create --title "Title" --description "Description" --team "TEAM"

# List and filter issues
linear issue list --status "In Progress" --assignee "user@email.com"
linear issue list --labels "bug,urgent" --team "Backend"

# Update issues
linear issue update ISS-123 --status "Done" --assignee "user@email.com"
linear issue update ISS-123 --labels "critical" --priority "High"

# Show issue details
linear issue show ISS-123

# Delete issues
linear issue delete ISS-123

Bulk Operations

# Bulk status updates
linear bulk update-state --status "In Progress" --filter "assignee:user@email.com"

# Bulk label management
linear bulk label --add "refactor" --filter "team:Backend"

# Bulk assignment
linear bulk assign "user@email.com" --filter "status:Todo"

Search Operations

# Basic search
linear search "authentication bug"

# Advanced search with filters
linear search "login" --state "Todo" --priority 3
linear search "bug" --labels "urgent" --assignee "user@email.com"

# Advanced search with date filtering
linear search-advanced issues "api bug" --team "Backend" --limit 50

Team & User Management

# Team operations
linear team list
linear team show "Backend"

# User operations
linear user list
linear user show "user@email.com"
linear user workload

Project Management

# List all projects
linear project list

# View project details
linear project show "My Project"

# Create project status update
linear project update "My Project" "Made good progress this week" --health onTrack

# View project update history
linear project updates "My Project"

Label Management

# List labels
linear label list

# Create labels
linear label create "refactor" --description "Code refactoring tasks" --color "#FF5722"

# Update labels
linear label update "bug" --description "Updated description" --color "#FF0000"

# Delete labels
linear label delete "old-label"

Configuration

# View configuration
linear config show

# Set configuration values
linear config set default_team "Engineering"
linear config set output_format "table"

# Edit configuration in editor
linear config edit

# Reset configuration
linear config reset

# Unset configuration values
linear config unset default_team

Configuration

Linear CLI supports configuration through multiple methods:

Configuration File

Create ~/.linear-cli/config.toml:

[default]
team = "Engineering"
output_format = "table"

[api]
timeout = 30
retries = 3

[display]
colors = true
progress_bars = true

Environment Variables

export LINEAR_API_KEY="your_api_token"
export LINEARATOR_DEFAULT_TEAM="Engineering"
export LINEARATOR_OUTPUT_FORMAT="json"

Command Line Options

linear --team "Engineering" --format json issue list

Output Formats

Table Format (Default)

ID      Title              Status        Assignee      Labels
ISS-123 Fix authentication In Progress   john@co.com   bug, urgent
ISS-124 Add user profiles  Todo          jane@co.com   feature

JSON Format

linear issue list --format json

[
  {
    "id": "ISS-123",
    "title": "Fix authentication",
    "status": "In Progress",
    "assignee": "john@company.com",
    "labels": ["bug", "urgent"],
    "createdAt": "2024-01-15T10:30:00Z"
  }
]

YAML Format

linear issue list --format yaml

Advanced Usage

Interactive Mode

Start interactive mode for guided workflows:

linear interactive

Shell Completion

Enable shell completion for faster workflow:

# Bash
eval "$(_LINEARATOR_COMPLETE=bash_source linear)"

# Zsh  
eval "$(_LINEARATOR_COMPLETE=zsh_source linear)"

# Fish
_LINEARATOR_COMPLETE=fish_source linear | source

Integration Examples

CI/CD Integration

# GitHub Actions example
- name: Create Linear issue for failed build
  run: |
    linear issue create \
      --title "Build failed: ${{ github.ref }}" \
      --description "Build failure in ${{ github.repository }}" \
      --labels "ci,bug" \
      --team "Engineering"

Automation Scripts

#!/bin/bash
# Daily standup preparation
echo "Your issues for today:"
linear issue list --assignee me --state "In Progress"

echo "Urgent issues:"
linear search "bug" --priority 4 --state "Todo"

Development

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/AdiKsOnDev/linearator.git
cd linearator

# Install development dependencies
make install-dev

# Run tests
make test

# Run linting and formatting
make lint
make format

# Run security checks
make security-check

Running Tests

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run linting checks
make lint

# Check code formatting
make format-check

Requirements

• Python 3.12 or higher
• Linear account with API access
• Internet connection for Linear API communication

License

This project is licensed under the MIT License. See LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Changelog

See CHANGELOG.md for detailed release notes and version history.