# 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 all 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
### Team & Label Management
- **Team Operations**: List teams, switch contexts, manage team-specific configurations
- **Label Management**: Create, update, and apply labels to organize issues effectively
- **User Management**: View team members, workload distribution, and assignment suggestions
### Advanced Capabilities
- **Powerful Search**: Full-text search with advanced query syntax and saved searches
- **Interactive Mode**: Guided issue creation and management workflows
- **Multiple Output Formats**: JSON, table, and plain text formatting options
- **Shell Integration**: Command completion and aliases 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 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 Operations
```bash
# List available teams
linear-cli team list
# Switch default team context
linear-cli team switch "Engineering"
# View team members
linear-cli user list --team "Engineering"
```
## Command Reference
### Issue Commands
```bash
# Create issues
linear-cli issue create --title "Title" --description "Description" --team "TEAM"
linear-cli issue create --interactive # Guided creation
# List and filter issues
linear-cli issue list --status "In Progress" --assignee "user@email.com"
linear-cli issue list --label "bug,urgent" --team "Backend"
# Update issues
linear-cli issue update ISS-123 --status "Done" --assignee "user@email.com"
linear-cli issue update ISS-123 --add-label "critical" --priority "High"
# Delete issues
linear-cli issue delete ISS-123
```
### Bulk Operations
```bash
# Bulk status updates
linear-cli bulk update-status --status "In Progress" --filter "assignee:user@email.com"
# Bulk label management
linear-cli bulk add-label "refactor" --filter "team:Backend"
# Bulk assignment
linear-cli bulk assign "user@email.com" --filter "status:Todo,label:urgent"
```
### Search Operations
```bash
# Basic search
linear-cli search "authentication bug"
# Advanced search with filters
linear-cli search "login" --status "Todo,In Progress" --created-after "2024-01-01"
# Save and manage searches
linear-cli search save "urgent-bugs" "priority:urgent AND status:Todo"
linear-cli search run "urgent-bugs"
```
### Team & User Management
```bash
# Team operations
linear-cli team list
linear-cli team switch "Frontend"
linear-cli team info "Backend"
# User operations
linear-cli user list
linear-cli user workload --team "Engineering"
linear-cli user info "user@email.com"
```
### Label Management
```bash
# List labels
linear-cli label list
# Create labels
linear-cli label create "refactor" --description "Code refactoring tasks" --color "#FF5722"
# Apply labels to issues
linear-cli label apply "bug" ISS-123 ISS-124
```
### Configuration
```bash
# View configuration
linear-cli config show
# Set default values
linear-cli config set default.team "Engineering"
linear-cli config set output.format "table"
# Reset configuration
linear-cli config reset
```
## 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-cli 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"
}
]
```
### Plain Text Format
```bash
linear-cli issue list --format plain
```
## Advanced Usage
### Interactive Mode
For complex operations, use interactive mode:
```bash
linear-cli issue create --interactive
linear-cli search --interactive
```
### Shell Completion
Enable shell completion for faster workflow:
```bash
# Bash
eval "$(_LINEARATOR_COMPLETE=bash_source linear-cli)"
# Zsh
eval "$(_LINEARATOR_COMPLETE=zsh_source linear-cli)"
# Fish
_LINEARATOR_COMPLETE=fish_source linear-cli | source
```
### Command Aliases
Set up aliases for frequently used commands:
```bash
linear-cli config alias "my-issues" "issue list --assignee me"
linear-cli config alias "urgent" "search 'priority:urgent'"
```
## Integration Examples
### CI/CD Integration
```yaml
# GitHub Actions example
- name: Create Linear issue for failed build
run: |
linear-cli issue create \
--title "Build failed: ${{ github.ref }}" \
--description "Build failure in ${{ github.repository }}" \
--label "ci,bug" \
--team "Engineering"
```
### Automation Scripts
```bash
#!/bin/bash
# Daily standup preparation
echo "Your issues for today:"
linear-cli issue list --assignee me --status "In Progress,Todo"
echo "Urgent team issues:"
linear-cli search "priority:urgent AND team:$TEAM"
```
## Development
### Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
# Clone repository
git clone https://github.com/linear-cli/linear-cli.git
cd linear-cli
# Install development dependencies
make install-dev
# Run tests
make test
# Run linting
make lint
# Build documentation
make docs
```
### Running Tests
```bash
# Run all tests
make test
# Run specific test categories
make test-unit
make test-integration
# Run with coverage
make test-coverage
```
## 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
- **Documentation**: [linear-cli.readthedocs.io](https://linear-cli.readthedocs.io)
- **Issues**: [GitHub Issues](https://github.com/linear-cli/linear-cli/issues)
- **Discussions**: [GitHub Discussions](https://github.com/linear-cli/linear-cli/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/ab/b5/d7c6f6d82234864f660f4e22546813b56ee9ed08bf02d3d6a5a5ea9a1282/linearator-1.0.8.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 all 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### Team & Label Management\n- **Team Operations**: List teams, switch contexts, manage team-specific configurations\n- **Label Management**: Create, update, and apply labels to organize issues effectively\n- **User Management**: View team members, workload distribution, and assignment suggestions\n\n### Advanced Capabilities\n- **Powerful Search**: Full-text search with advanced query syntax and saved searches\n- **Interactive Mode**: Guided issue creation and management workflows\n- **Multiple Output Formats**: JSON, table, and plain text formatting options\n- **Shell Integration**: Command completion and aliases 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 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 Operations\n\n```bash\n# List available teams\nlinear-cli team list\n\n# Switch default team context\nlinear-cli team switch \"Engineering\"\n\n# View team members\nlinear-cli user list --team \"Engineering\"\n```\n\n## Command Reference\n\n### Issue Commands\n\n```bash\n# Create issues\nlinear-cli issue create --title \"Title\" --description \"Description\" --team \"TEAM\"\nlinear-cli issue create --interactive # Guided creation\n\n# List and filter issues\nlinear-cli issue list --status \"In Progress\" --assignee \"user@email.com\"\nlinear-cli issue list --label \"bug,urgent\" --team \"Backend\"\n\n# Update issues\nlinear-cli issue update ISS-123 --status \"Done\" --assignee \"user@email.com\"\nlinear-cli issue update ISS-123 --add-label \"critical\" --priority \"High\"\n\n# Delete issues\nlinear-cli issue delete ISS-123\n```\n\n### Bulk Operations\n\n```bash\n# Bulk status updates\nlinear-cli bulk update-status --status \"In Progress\" --filter \"assignee:user@email.com\"\n\n# Bulk label management\nlinear-cli bulk add-label \"refactor\" --filter \"team:Backend\"\n\n# Bulk assignment\nlinear-cli bulk assign \"user@email.com\" --filter \"status:Todo,label:urgent\"\n```\n\n### Search Operations\n\n```bash\n# Basic search\nlinear-cli search \"authentication bug\"\n\n# Advanced search with filters\nlinear-cli search \"login\" --status \"Todo,In Progress\" --created-after \"2024-01-01\"\n\n# Save and manage searches\nlinear-cli search save \"urgent-bugs\" \"priority:urgent AND status:Todo\"\nlinear-cli search run \"urgent-bugs\"\n```\n\n### Team & User Management\n\n```bash\n# Team operations\nlinear-cli team list\nlinear-cli team switch \"Frontend\"\nlinear-cli team info \"Backend\"\n\n# User operations\nlinear-cli user list\nlinear-cli user workload --team \"Engineering\"\nlinear-cli user info \"user@email.com\"\n```\n\n### Label Management\n\n```bash\n# List labels\nlinear-cli label list\n\n# Create labels\nlinear-cli label create \"refactor\" --description \"Code refactoring tasks\" --color \"#FF5722\"\n\n# Apply labels to issues\nlinear-cli label apply \"bug\" ISS-123 ISS-124\n```\n\n### Configuration\n\n```bash\n# View configuration\nlinear-cli config show\n\n# Set default values\nlinear-cli config set default.team \"Engineering\"\nlinear-cli config set output.format \"table\"\n\n# Reset configuration\nlinear-cli config reset\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-cli 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### Plain Text Format\n```bash\nlinear-cli issue list --format plain\n```\n\n## Advanced Usage\n\n### Interactive Mode\n\nFor complex operations, use interactive mode:\n\n```bash\nlinear-cli issue create --interactive\nlinear-cli search --interactive\n```\n\n### Shell Completion\n\nEnable shell completion for faster workflow:\n\n```bash\n# Bash\neval \"$(_LINEARATOR_COMPLETE=bash_source linear-cli)\"\n\n# Zsh\neval \"$(_LINEARATOR_COMPLETE=zsh_source linear-cli)\"\n\n# Fish\n_LINEARATOR_COMPLETE=fish_source linear-cli | source\n```\n\n### Command Aliases\n\nSet up aliases for frequently used commands:\n\n```bash\nlinear-cli config alias \"my-issues\" \"issue list --assignee me\"\nlinear-cli config alias \"urgent\" \"search 'priority:urgent'\"\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-cli issue create \\\n --title \"Build failed: ${{ github.ref }}\" \\\n --description \"Build failure in ${{ github.repository }}\" \\\n --label \"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-cli issue list --assignee me --status \"In Progress,Todo\"\n\necho \"Urgent team issues:\"\nlinear-cli search \"priority:urgent AND team:$TEAM\"\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/linear-cli/linear-cli.git\ncd linear-cli\n\n# Install development dependencies\nmake install-dev\n\n# Run tests\nmake test\n\n# Run linting\nmake lint\n\n# Build documentation\nmake docs\n```\n\n### Running Tests\n\n```bash\n# Run all tests\nmake test\n\n# Run specific test categories\nmake test-unit\nmake test-integration\n\n# Run with coverage\nmake test-coverage\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- **Documentation**: [linear-cli.readthedocs.io](https://linear-cli.readthedocs.io)\n- **Issues**: [GitHub Issues](https://github.com/linear-cli/linear-cli/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/linear-cli/linear-cli/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.0.8",
"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": "39f968927dc76e77c4f70a85cb51573c85ee23d6f7ecfbd341f3a81fe140edc3",
"md5": "26309ff7012c876dc22a6d0eb77a3b14",
"sha256": "2f50e1b55d5a890335fc6f156159a9715ca6da56cd6dc09ecb2edbc120ae0077"
},
"downloads": -1,
"filename": "linearator-1.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "26309ff7012c876dc22a6d0eb77a3b14",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 81437,
"upload_time": "2025-09-09T08:43:34",
"upload_time_iso_8601": "2025-09-09T08:43:34.554213Z",
"url": "https://files.pythonhosted.org/packages/39/f9/68927dc76e77c4f70a85cb51573c85ee23d6f7ecfbd341f3a81fe140edc3/linearator-1.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "abb5d7c6f6d82234864f660f4e22546813b56ee9ed08bf02d3d6a5a5ea9a1282",
"md5": "9d4959f32fc039dd3547bd85c8f48f31",
"sha256": "dff0b802c89bf29862ac4368c75e0192d0fb29d63d5d51fbc2f9beee1def2fdd"
},
"downloads": -1,
"filename": "linearator-1.0.8.tar.gz",
"has_sig": false,
"md5_digest": "9d4959f32fc039dd3547bd85c8f48f31",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 125660,
"upload_time": "2025-09-09T08:43:35",
"upload_time_iso_8601": "2025-09-09T08:43:35.782656Z",
"url": "https://files.pythonhosted.org/packages/ab/b5/d7c6f6d82234864f660f4e22546813b56ee9ed08bf02d3d6a5a5ea9a1282/linearator-1.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-09 08:43:35",
"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
