# 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)
```bash
pip install linearator
```
### From AUR
```bash
paru -S linear-cli
# Or:
yay -S linear-cli
```
### From Source
```bash
git clone https://github.com/AdiKsOnDev/linearator.git
cd linearator
pip install -e .
```
### Development Installation
```bash
git clone https://github.com/AdiKsOnDev/linearator.git
cd linearator
make install-dev
```
## Quick Start
### 1. Authentication
First, authenticate with Linear:
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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`:
```toml
[default]
team = "Engineering"
output_format = "table"
[api]
timeout = 30
retries = 3
[display]
colors = true
progress_bars = true
```
### Environment Variables
```bash
export LINEAR_API_KEY="your_api_token"
export LINEARATOR_DEFAULT_TEAM="Engineering"
export LINEARATOR_OUTPUT_FORMAT="json"
```
### Command Line Options
```bash
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
```bash
linear issue list --format json
```
```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
```bash
linear issue list --format yaml
```
## Advanced Usage
### Interactive Mode
Start interactive mode for guided workflows:
```bash
linear interactive
```
### Shell Completion
Enable shell completion for faster workflow:
```bash
# 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
```yaml
# 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
```bash
#!/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](CONTRIBUTING.md) for details.
### Development Setup
```bash
# 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
```bash
# 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](LICENSE) file for details.
## Support
- **Issues**: [GitHub Issues](https://github.com/AdiKsOnDev/linearator/issues)
- **Discussions**: [GitHub Discussions](https://github.com/AdiKsOnDev/linearator/discussions)
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for detailed release notes and version history.
Raw data
{
"_id": null,
"home_page": null,
"name": "linearator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "linear, cli, issue-tracker, project-management, workflow, automation, graphql, api-client, team-collaboration, bulk-operations",
"author": null,
"author_email": "Adil Alizada <adilalizade13@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/fa/c9/35281c7a93292e70b303cc2667941b292d60809c5a08381b9b4e3736071b/linearator-1.2.0.tar.gz",
"platform": null,
"description": "# Linearator\n\nA comprehensive command-line interface for Linear issue management, enabling efficient project workflow automation and team collaboration through the Linear API.\n\n## Overview\n\nLinearator 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.\n\n## Key Features\n\n### Core Issue Management\n- **Full CRUD Operations**: Create, read, update, and delete Linear issues\n- **Advanced Filtering**: Filter issues by status, assignee, labels, teams, and custom criteria\n- **Bulk Operations**: Perform batch updates on multiple issues simultaneously\n- **Status Management**: Update issue states, priorities, and assignments\n\n### Project Management\n- **Project Operations**: List projects, view project details, and track project health\n- **Project Updates**: Create and manage project status updates with health indicators\n- **Project Timeline**: View project update history and track progress over time\n- **Smart Lookup**: Reference projects by both ID and human-readable names\n\n### Team & Label Management\n- **Team Operations**: List teams, view team details, and manage team-specific configurations\n- **Label Management**: Create, update, and apply labels to organize issues effectively\n- **User Management**: View team members and workload analysis\n\n### Advanced Capabilities\n- **Powerful Search**: Full-text search with advanced filtering capabilities\n- **Interactive Mode**: Guided issue creation and management workflows\n- **Multiple Output Formats**: JSON, table, and YAML formatting options\n- **Shell Integration**: Command completion for efficient usage\n\n### Authentication & Security\n- **OAuth Flow**: Secure authentication with Linear's OAuth system\n- **API Key Support**: Alternative authentication method for automation\n- **Credential Management**: Secure storage using system keyring\n- **Token Refresh**: Automatic token renewal and session management\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install linearator\n```\n\n### From AUR\n\n```bash\nparu -S linear-cli\n\n# Or:\nyay -S linear-cli\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/AdiKsOnDev/linearator.git\ncd linearator\npip install -e .\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/AdiKsOnDev/linearator.git\ncd linearator\nmake install-dev\n```\n\n## Quick Start\n\n### 1. Authentication\n\nFirst, authenticate with Linear:\n\n```bash\n# OAuth flow (recommended)\nlinear auth login\n\n# Or use API key\nlinear auth login --api-key YOUR_API_KEY\n\n# Or set environment variable\nexport LINEAR_API_KEY=YOUR_API_KEY\n```\n\n### 2. Basic Usage\n\n```bash\n# List your issues\nlinear issue list\n\n# Create a new issue\nlinear issue create --title \"Bug fix\" --description \"Fix login error\" --team \"ENG\"\n\n# Update issue status\nlinear issue update ISS-123 --status \"In Progress\"\n\n# Search issues\nlinear search \"login bug\" --status \"Todo\" --assignee \"john@company.com\"\n```\n\n### 3. Team and Project Operations\n\n```bash\n# List available teams\nlinear team list\n\n# View team details\nlinear team show \"Engineering\"\n\n# List projects\nlinear project list\n\n# View project details\nlinear project show \"My Project\"\n```\n\n## Command Reference\n\n### Issue Commands\n\n```bash\n# Create issues\nlinear issue create --title \"Title\" --description \"Description\" --team \"TEAM\"\n\n# List and filter issues\nlinear issue list --status \"In Progress\" --assignee \"user@email.com\"\nlinear issue list --labels \"bug,urgent\" --team \"Backend\"\n\n# Update issues\nlinear issue update ISS-123 --status \"Done\" --assignee \"user@email.com\"\nlinear issue update ISS-123 --labels \"critical\" --priority \"High\"\n\n# Show issue details\nlinear issue show ISS-123\n\n# Delete issues\nlinear issue delete ISS-123\n```\n\n### Bulk Operations\n\n```bash\n# Bulk status updates\nlinear bulk update-state --status \"In Progress\" --filter \"assignee:user@email.com\"\n\n# Bulk label management\nlinear bulk label --add \"refactor\" --filter \"team:Backend\"\n\n# Bulk assignment\nlinear bulk assign \"user@email.com\" --filter \"status:Todo\"\n```\n\n### Search Operations\n\n```bash\n# Basic search\nlinear search \"authentication bug\"\n\n# Advanced search with filters\nlinear search \"login\" --state \"Todo\" --priority 3\nlinear search \"bug\" --labels \"urgent\" --assignee \"user@email.com\"\n\n# Advanced search with date filtering\nlinear search-advanced issues \"api bug\" --team \"Backend\" --limit 50\n```\n\n### Team & User Management\n\n```bash\n# Team operations\nlinear team list\nlinear team show \"Backend\"\n\n# User operations\nlinear user list\nlinear user show \"user@email.com\"\nlinear user workload\n```\n\n### Project Management\n\n```bash\n# List all projects\nlinear project list\n\n# View project details\nlinear project show \"My Project\"\n\n# Create project status update\nlinear project update \"My Project\" \"Made good progress this week\" --health onTrack\n\n# View project update history\nlinear project updates \"My Project\"\n```\n\n### Label Management\n\n```bash\n# List labels\nlinear label list\n\n# Create labels\nlinear label create \"refactor\" --description \"Code refactoring tasks\" --color \"#FF5722\"\n\n# Update labels\nlinear label update \"bug\" --description \"Updated description\" --color \"#FF0000\"\n\n# Delete labels\nlinear label delete \"old-label\"\n```\n\n### Configuration\n\n```bash\n# View configuration\nlinear config show\n\n# Set configuration values\nlinear config set default_team \"Engineering\"\nlinear config set output_format \"table\"\n\n# Edit configuration in editor\nlinear config edit\n\n# Reset configuration\nlinear config reset\n\n# Unset configuration values\nlinear config unset default_team\n```\n\n## Configuration\n\nLinear CLI supports configuration through multiple methods:\n\n### Configuration File\n\nCreate `~/.linear-cli/config.toml`:\n\n```toml\n[default]\nteam = \"Engineering\"\noutput_format = \"table\"\n\n[api]\ntimeout = 30\nretries = 3\n\n[display]\ncolors = true\nprogress_bars = true\n```\n\n### Environment Variables\n\n```bash\nexport LINEAR_API_KEY=\"your_api_token\"\nexport LINEARATOR_DEFAULT_TEAM=\"Engineering\"\nexport LINEARATOR_OUTPUT_FORMAT=\"json\"\n```\n\n### Command Line Options\n\n```bash\nlinear --team \"Engineering\" --format json issue list\n```\n\n## Output Formats\n\n### Table Format (Default)\n```\nID Title Status Assignee Labels\nISS-123 Fix authentication In Progress john@co.com bug, urgent\nISS-124 Add user profiles Todo jane@co.com feature\n```\n\n### JSON Format\n```bash\nlinear issue list --format json\n```\n\n```json\n[\n {\n \"id\": \"ISS-123\",\n \"title\": \"Fix authentication\",\n \"status\": \"In Progress\",\n \"assignee\": \"john@company.com\",\n \"labels\": [\"bug\", \"urgent\"],\n \"createdAt\": \"2024-01-15T10:30:00Z\"\n }\n]\n```\n\n### YAML Format\n```bash\nlinear issue list --format yaml\n```\n\n## Advanced Usage\n\n### Interactive Mode\n\nStart interactive mode for guided workflows:\n\n```bash\nlinear interactive\n```\n\n### Shell Completion\n\nEnable shell completion for faster workflow:\n\n```bash\n# Bash\neval \"$(_LINEARATOR_COMPLETE=bash_source linear)\"\n\n# Zsh \neval \"$(_LINEARATOR_COMPLETE=zsh_source linear)\"\n\n# Fish\n_LINEARATOR_COMPLETE=fish_source linear | source\n```\n\n## Integration Examples\n\n### CI/CD Integration\n\n```yaml\n# GitHub Actions example\n- name: Create Linear issue for failed build\n run: |\n linear issue create \\\n --title \"Build failed: ${{ github.ref }}\" \\\n --description \"Build failure in ${{ github.repository }}\" \\\n --labels \"ci,bug\" \\\n --team \"Engineering\"\n```\n\n### Automation Scripts\n\n```bash\n#!/bin/bash\n# Daily standup preparation\necho \"Your issues for today:\"\nlinear issue list --assignee me --state \"In Progress\"\n\necho \"Urgent issues:\"\nlinear search \"bug\" --priority 4 --state \"Todo\"\n```\n\n## Development\n\n### Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/AdiKsOnDev/linearator.git\ncd linearator\n\n# Install development dependencies\nmake install-dev\n\n# Run tests\nmake test\n\n# Run linting and formatting\nmake lint\nmake format\n\n# Run security checks\nmake security-check\n```\n\n### Running Tests\n\n```bash\n# Run all tests\nmake test\n\n# Run tests with coverage\nmake test-coverage\n\n# Run linting checks\nmake lint\n\n# Check code formatting\nmake format-check\n```\n\n## Requirements\n\n- Python 3.12 or higher\n- Linear account with API access\n- Internet connection for Linear API communication\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/AdiKsOnDev/linearator/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/AdiKsOnDev/linearator/discussions)\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for detailed release notes and version history.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive CLI tool for Linear issue management with advanced search, bulk operations, and team collaboration features",
"version": "1.2.0",
"project_urls": {
"Bug Reports": "https://github.com/AdiKsOnDev/linearator/issues",
"Changelog": "https://github.com/AdiKsOnDev/linearator/blob/main/CHANGELOG.md",
"Discussions": "https://github.com/AdiKsOnDev/linearator/discussions",
"Feature Requests": "https://github.com/AdiKsOnDev/linearator/issues/",
"Homepage": "https://github.com/AdiKsOnDev/linearator",
"Release Notes": "https://github.com/AdiKsOnDev/linearator/releases",
"Repository": "https://github.com/AdiKsOnDev/linearator.git"
},
"split_keywords": [
"linear",
" cli",
" issue-tracker",
" project-management",
" workflow",
" automation",
" graphql",
" api-client",
" team-collaboration",
" bulk-operations"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0ee820f1d74abc7d6dbdb4cd1501a691504c63636936653ad0ca329e17922a3a",
"md5": "67865216782938875e5fe953c628e91b",
"sha256": "28eaa705972d8097d50bc173cce243a9aebca1b4db87e51bcd620b4ed12367f0"
},
"downloads": -1,
"filename": "linearator-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "67865216782938875e5fe953c628e91b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 87557,
"upload_time": "2025-09-15T17:08:05",
"upload_time_iso_8601": "2025-09-15T17:08:05.761576Z",
"url": "https://files.pythonhosted.org/packages/0e/e8/20f1d74abc7d6dbdb4cd1501a691504c63636936653ad0ca329e17922a3a/linearator-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fac935281c7a93292e70b303cc2667941b292d60809c5a08381b9b4e3736071b",
"md5": "608cfac152832d2b63b0dded71fbfede",
"sha256": "ef313f8cf3abbc8b31419cf2efac455c108e1137730f75ead78e93216fb6b441"
},
"downloads": -1,
"filename": "linearator-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "608cfac152832d2b63b0dded71fbfede",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 132984,
"upload_time": "2025-09-15T17:08:07",
"upload_time_iso_8601": "2025-09-15T17:08:07.300638Z",
"url": "https://files.pythonhosted.org/packages/fa/c9/35281c7a93292e70b303cc2667941b292d60809c5a08381b9b4e3736071b/linearator-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-15 17:08:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AdiKsOnDev",
"github_project": "linearator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "linearator"
}
JSON
