linear-ticket-cli

Name	linear-ticket-cli JSON
Version	1.0.0 JSON
	download
home_page	None
Summary	A comprehensive command-line tool for managing Linear tickets with AI-agent friendly interfaces
upload_time	2025-10-11 13:45:21
maintainer	None
docs_url	None
author	None
requires_python	>=3.7
license	MIT License Copyright (c) 2024 Linear Ticket Manager CLI Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
keywords	linear cli ticket-management project-management ai-agent automation graphql productivity
VCS
bugtrack_url
requirements	requests fuzzywuzzy python-levenshtein
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Linear Ticket Manager CLI

🎫 **A comprehensive command-line tool for managing Linear tickets with AI-agent friendly interfaces**

This tool provides complete Linear ticket management capabilities through an intuitive CLI, designed to work seamlessly with AI agents, automation scripts, and human users.

## 🚀 Quick Start for AI Agents

```bash
# 1. Set your Linear API token (REQUIRED)
export LINEAR_API_TOKEN="your_token_here"

# 2. Basic usage - create a ticket
linear add --title "Fix authentication bug" --team "Backend"
# Output: ✅ Successfully created ticket: ZIF-123

# 3. Search for tickets  
linear "ZIF-123"
# Output: Full ticket details

# 4. List available resources
linear --teams      # See all teams
linear --projects   # See all projects
linear --assignees  # See all users
```

## 📋 Table of Contents

- [Installation](#installation)
- [Authentication](#authentication)
- [Core Features](#core-features)
- [AI Agent Usage Guide](#ai-agent-usage-guide)
- [Command Reference](#command-reference)
- [Examples](#examples)
- [Automation & Scripting](#automation--scripting)
- [Troubleshooting](#troubleshooting)

## 🛠 Installation

### Prerequisites
- Python 3.7 or higher
- Linear workspace access
- Linear API token

### 🚀 Quick Installation (Recommended)

**Install via pip (coming soon to PyPI):**
```bash
pip install linear-cli
```

**Install directly from GitHub:**
```bash
pip install git+https://github.com/vittoridavide/linear-cli.git
```

After installation, you can use the `linear` command directly:
```bash
linear --help
```

### 🔧 Development Installation

**Option 1: Quick Setup (Recommended)**
```bash
git clone https://github.com/vittoridavide/linear-cli.git
cd linear-cli
./dev-setup.sh
```

**Option 2: Manual Setup**
```bash
git clone https://github.com/vittoridavide/linear-cli.git
cd linear-cli
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .
```

**Option 3: Legacy Method (Clone and Run)**
```bash
git clone https://github.com/vittoridavide/linear-cli.git
cd linear-cli
pip install -r requirements.txt
# Use: python linear_search.py instead of linear
```

### 🔑 Authentication Setup

1. **Get Linear API Token**
   - Go to Linear → Settings → API → Personal API tokens
   - Create new token with read/write permissions
   - Copy the token

2. **Configure Authentication**
   ```bash
   export LINEAR_API_TOKEN="your_linear_api_token_here"
   # Add to ~/.zshrc or ~/.bashrc for persistence
   ```

## 🔐 Authentication

**Environment Variable (Recommended):**
```bash
export LINEAR_API_TOKEN="lin_api_..."
```

**Command Line Override:**
```bash
linear --token "lin_api_..." add --title "Test ticket"
```

## ✨ Core Features

- 🔍 **Smart Ticket Search** - Natural language queries, direct ID lookup
- 🎯 **Ticket Creation** - Full metadata support (teams, projects, assignees, labels)
- ✏️ **Ticket Updates** - Status, title, description, priority, assignee changes
- 📊 **Resource Discovery** - List teams, projects, users, labels, workflow states
- 🤖 **AI-Agent Friendly** - Detailed help text, consistent output formats
- 📝 **Script Integration** - JSON output modes, exit codes, ID-only responses
- ⚡ **Performance** - Local caching for fast searches
- 🔄 **Real-time Sync** - Automatic cache refresh after modifications

## 🤖 AI Agent Usage Guide

### Step-by-Step Workflow for AI Agents

#### 1. Resource Discovery (ALWAYS DO THIS FIRST)
```bash
# Get available teams (required for ticket creation)
linear --teams
# Output: 1. Backend, 2. Frontend Engineering, 3. DevOps

# Get available projects  
linear --projects
# Output: 1. Q4 Features, 2. Bug Fixes, 3. Technical Debt

# Get available users for assignment
linear --assignees  
# Output: 1. John Smith (john@company.com), 2. Jane Doe (jane@company.com)

# Get workflow states for status updates
linear --states
# Output: Backend: Todo, In Progress, In Review, Done
```

#### 2. Create Tickets with Validation
```bash
# Basic creation (minimal required info)
linear add --title "Fix login issue" --team "Backend"
# Output: ✅ Successfully created ticket: ZIF-124

# Full creation with all metadata
linear add \
  --title "Add user dashboard" \
  --description "Create comprehensive user management interface" \
  --team "Frontend Engineering" \
  --project "Q4 Features" \
  --assignee "john@company.com" \
  --priority high \
  --labels "feature,frontend,ui"
# Output: ✅ Successfully created ticket: ZIF-125
```

#### 3. Script-Friendly Operations
```bash
# Get only ticket ID for automation
TICKET_ID=$(linear add --title "Automated task" --team "Backend" --id-only)
echo "Created: $TICKET_ID"
# Output: Created: ZIF-126

# Search and update
linear "$TICKET_ID" --status "In Progress" --assignee "jane@company.com"
# Output: ✅ Updated ticket: ZIF-126
```

### AI Agent Best Practices

1. **Always validate resources first** - Run `--teams`, `--projects`, `--assignees` before creating tickets
2. **Use exact names** - Team and project names are case-sensitive
3. **Wrap parameters in quotes** - Especially for titles, descriptions, and names with spaces
4. **Check exit codes** - Non-zero exit codes indicate errors
5. **Use `--id-only` for scripting** - Clean output perfect for variable capture
6. **Handle errors gracefully** - Commands show specific error messages with suggestions

## 📖 Command Reference

### Ticket Creation
```bash
linear add [OPTIONS]

Required:
  --title "Ticket Title"              # Main ticket heading

Optional:
  --description "Detailed description" # Supports markdown
  --team "Team Name"                   # From --teams output
  --project "Project Name"             # From --projects output  
  --assignee "user@email.com"          # From --assignees output
  --priority urgent|high|normal|low    # Or numeric 1|2|3|4
  --labels "bug,frontend,critical"     # Comma-separated, no spaces
  --parent "ZIF-19"                    # Parent ticket ID
  --id-only                            # Return only ticket ID

Examples:
  linear add --title "Fix bug" --team "Backend"
  linear add --title "New feature" --team "Frontend" --project "Q4" --id-only
```

### Ticket Search
```bash
linear "QUERY" [OPTIONS]

Query Types:
  "ZIF-19"                            # Direct ticket lookup
  "project: Issues, Epic 1"           # Project + epic search
  "bug authentication"                # Keyword search
  
Options:
  --limit 5                           # Max results (default: 10)

Examples:
  linear "ZIF-123"
  linear "project: Backend database" --limit 5
  linear "critical bug" --limit 3
```

### Ticket Updates
```bash
linear "TICKET-ID" [UPDATE_OPTIONS]

Update Options:
  --status "Status Name"              # From --states output
  --title "New Title"                 # Replace existing title
  --description "New description"     # Replace existing description
  --priority urgent|high|normal|low   # Or numeric 1|2|3|4
  --assignee "user@email.com"         # From --assignees, or "none" to unassign

Examples:
  linear "ZIF-19" --status "Done"
  linear "ZIF-19" --assignee "user@company.com" --priority high
  linear "ZIF-19" --title "Updated title" --status "In Review"
```

### Utility Commands
```bash
linear --teams                        # List all teams
linear --projects                     # List all projects  
linear --assignees                    # List all users
linear --labels                       # List all labels
linear --states                       # List workflow states
linear --refresh                      # Update local cache
```

## 💡 Examples

### For AI Agents - Complete Workflows

#### Create and Track a Bug Report
```bash
# 1. Discover resources
TEAMS=$(linear --teams)
USERS=$(linear --assignees) 

# 2. Create bug ticket
BUG_ID=$(linear add \
  --title "Login fails with OAuth" \
  --description "Users cannot authenticate via OAuth provider" \
  --team "Backend" \
  --assignee "backend-lead@company.com" \
  --priority urgent \
  --labels "bug,authentication,critical" \
  --id-only)

echo "Created bug report: $BUG_ID"

# 3. Update as work progresses
linear "$BUG_ID" --status "In Progress"
linear "$BUG_ID" --description "Root cause identified: OAuth callback URL misconfigured"
linear "$BUG_ID" --status "In Review"
linear "$BUG_ID" --status "Done"
```

#### Create Feature with Sub-tasks
```bash
# 1. Create parent feature
FEATURE_ID=$(linear add \
  --title "User Dashboard v2" \
  --description "Redesigned user dashboard with analytics" \
  --team "Frontend" \
  --project "Q4 Features" \
  --priority high \
  --id-only)

# 2. Create sub-tasks
SUBTASK1=$(linear add \
  --title "Dashboard layout component" \
  --parent "$FEATURE_ID" \
  --team "Frontend" \
  --assignee "ui-dev@company.com" \
  --id-only)

SUBTASK2=$(linear add \
  --title "Analytics integration" \
  --parent "$FEATURE_ID" \
  --team "Frontend" \
  --assignee "data-dev@company.com" \
  --id-only)

echo "Feature: $FEATURE_ID, Subtasks: $SUBTASK1, $SUBTASK2"
```

### For Humans - Interactive Usage

#### Daily Ticket Management
```bash
# Check my assigned tickets
linear "assignee: john@company.com"

# Create quick ticket
linear add --title "Fix header alignment" --team "Frontend"

# Update ticket status
linear "ZIF-45" --status "Done"

# Search for recent bugs
linear "bug" --limit 5
```

## 🔧 Automation & Scripting

### Exit Codes
- `0` - Success
- `1` - Error (validation failed, API error, ticket not found)
- `2` - Invalid arguments

### Scripting Examples

#### CI/CD Integration
```bash
#!/bin/bash

# Create deployment ticket
DEPLOY_ID=$(linear add \
  --title "Deploy v${VERSION} to production" \
  --description "Automated deployment of version ${VERSION}" \
  --team "DevOps" \
  --assignee "$DEPLOY_ENGINEER" \
  --labels "deployment,production" \
  --id-only)

if [ $? -eq 0 ]; then
  echo "Deployment tracked in ticket: $DEPLOY_ID"
  
  # Update ticket during deployment
  linear "$DEPLOY_ID" --status "In Progress"
  
  # Deploy application...
  if deploy_application; then
    linear "$DEPLOY_ID" --status "Done" --description "Successfully deployed v${VERSION}"
  else
    linear "$DEPLOY_ID" --status "Failed" --description "Deployment failed: check logs"
    exit 1
  fi
else
  echo "Failed to create deployment ticket"
  exit 1
fi
```

#### Batch Operations
```bash
#!/bin/bash

# Process multiple tickets
TICKETS=("ZIF-10" "ZIF-11" "ZIF-12")

for ticket in "${TICKETS[@]}"; do
  echo "Processing $ticket..."
  linear "$ticket" --status "Done" --assignee "none"
  if [ $? -eq 0 ]; then
    echo "✅ Updated $ticket"
  else
    echo "❌ Failed to update $ticket"
  fi
done
```

## 🐛 Troubleshooting

### Common Issues

#### Authentication Errors
```bash
# Problem: "LINEAR_API_TOKEN environment variable not set"
# Solution:
export LINEAR_API_TOKEN="your_token_here"

# Problem: "400 Client Error: Bad Request"  
# Solution: Check token permissions in Linear settings
```

#### Validation Errors
```bash
# Problem: "Team 'backend' not found"
# Solution: Check exact team name
linear --teams  # See available teams

# Problem: "User 'john' not found"
# Solution: Use email or exact display name
linear --assignees  # See available users
```

#### Search Issues
```bash
# Problem: "No tickets found"
# Solution: Refresh cache and check query
linear --refresh
linear --projects  # Verify project names
```

### Debug Mode
```bash
# Add --token flag to see API requests
linear --token "$LINEAR_API_TOKEN" add --title "Debug test"
```

### Getting Help
```bash
linear --help              # Main help
linear add --help          # Ticket creation help
```

## 📂 Project Structure

```
linear-cli/
├── linear_search.py       # Main CLI application
├── linear_client.py       # Linear API client
├── ticket_search.py       # Search engine and ticket operations  
├── requirements.txt       # Python dependencies
├── setup_alias.sh         # Installation helper
├── .env.example          # Environment template
├── .gitignore            # Git ignore rules
└── README.md             # This file
```

## 🤝 Contributing

We welcome contributions! This tool is designed to be AI-agent friendly while maintaining excellent usability for humans.

### Quick Start for Contributors

1. **Fork the repository** on GitHub
2. **Clone your fork** locally
3. **Set up development environment** (see Installation section)
4. **Make your changes** following our development principles
5. **Test thoroughly** with real Linear workspaces
6. **Submit a pull request** with detailed description

### Development Principles

When extending functionality:

1. **Add detailed help text** - Include examples and validation notes
2. **Use consistent output formats** - Maintain JSON-friendly responses
3. **Handle errors gracefully** - Provide actionable error messages
4. **Document new features** - Update README with AI-agent examples
5. **Test with real scenarios** - Validate against actual Linear workspaces

For detailed contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built for the Linear community
- Designed with AI agents in mind
- Inspired by the need for powerful CLI tools in modern development workflows

## 📞 Support

If you encounter issues or have questions:
1. Check the [troubleshooting section](#-troubleshooting) in this README
2. Review existing [issues](https://github.com/vittoridavide/linear-cli/issues)
3. Create a new issue with detailed information
4. Consider contributing a fix!

## 🔗 Related Projects

- [Linear](https://linear.app) - The excellent project management tool this CLI interacts with
- [Linear API](https://developers.linear.app) - Official Linear API documentation

---

**Built for AI agents, humans, and automation. Happy ticket managing! 🎫**

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "linear-ticket-cli",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "Davide Vittori <me@vittoridavid.com>",
    "keywords": "linear, cli, ticket-management, project-management, ai-agent, automation, graphql, productivity",
    "author": null,
    "author_email": "Davide Vittori <me@vittoridavid.com>",
    "download_url": "https://files.pythonhosted.org/packages/d2/dc/9969ce90eb43319aae86804ff72efc13875c219c77de9f0527eb963b50aa/linear_ticket_cli-1.0.0.tar.gz",
    "platform": null,
    "description": "# Linear Ticket Manager CLI\n\n\ud83c\udfab **A comprehensive command-line tool for managing Linear tickets with AI-agent friendly interfaces**\n\nThis tool provides complete Linear ticket management capabilities through an intuitive CLI, designed to work seamlessly with AI agents, automation scripts, and human users.\n\n## \ud83d\ude80 Quick Start for AI Agents\n\n```bash\n# 1. Set your Linear API token (REQUIRED)\nexport LINEAR_API_TOKEN=\"your_token_here\"\n\n# 2. Basic usage - create a ticket\nlinear add --title \"Fix authentication bug\" --team \"Backend\"\n# Output: \u2705 Successfully created ticket: ZIF-123\n\n# 3. Search for tickets  \nlinear \"ZIF-123\"\n# Output: Full ticket details\n\n# 4. List available resources\nlinear --teams      # See all teams\nlinear --projects   # See all projects\nlinear --assignees  # See all users\n```\n\n## \ud83d\udccb Table of Contents\n\n- [Installation](#installation)\n- [Authentication](#authentication)\n- [Core Features](#core-features)\n- [AI Agent Usage Guide](#ai-agent-usage-guide)\n- [Command Reference](#command-reference)\n- [Examples](#examples)\n- [Automation & Scripting](#automation--scripting)\n- [Troubleshooting](#troubleshooting)\n\n## \ud83d\udee0 Installation\n\n### Prerequisites\n- Python 3.7 or higher\n- Linear workspace access\n- Linear API token\n\n### \ud83d\ude80 Quick Installation (Recommended)\n\n**Install via pip (coming soon to PyPI):**\n```bash\npip install linear-cli\n```\n\n**Install directly from GitHub:**\n```bash\npip install git+https://github.com/vittoridavide/linear-cli.git\n```\n\nAfter installation, you can use the `linear` command directly:\n```bash\nlinear --help\n```\n\n### \ud83d\udd27 Development Installation\n\n**Option 1: Quick Setup (Recommended)**\n```bash\ngit clone https://github.com/vittoridavide/linear-cli.git\ncd linear-cli\n./dev-setup.sh\n```\n\n**Option 2: Manual Setup**\n```bash\ngit clone https://github.com/vittoridavide/linear-cli.git\ncd linear-cli\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\npip install -e .\n```\n\n**Option 3: Legacy Method (Clone and Run)**\n```bash\ngit clone https://github.com/vittoridavide/linear-cli.git\ncd linear-cli\npip install -r requirements.txt\n# Use: python linear_search.py instead of linear\n```\n\n### \ud83d\udd11 Authentication Setup\n\n1. **Get Linear API Token**\n   - Go to Linear \u2192 Settings \u2192 API \u2192 Personal API tokens\n   - Create new token with read/write permissions\n   - Copy the token\n\n2. **Configure Authentication**\n   ```bash\n   export LINEAR_API_TOKEN=\"your_linear_api_token_here\"\n   # Add to ~/.zshrc or ~/.bashrc for persistence\n   ```\n\n## \ud83d\udd10 Authentication\n\n**Environment Variable (Recommended):**\n```bash\nexport LINEAR_API_TOKEN=\"lin_api_...\"\n```\n\n**Command Line Override:**\n```bash\nlinear --token \"lin_api_...\" add --title \"Test ticket\"\n```\n\n## \u2728 Core Features\n\n- \ud83d\udd0d **Smart Ticket Search** - Natural language queries, direct ID lookup\n- \ud83c\udfaf **Ticket Creation** - Full metadata support (teams, projects, assignees, labels)\n- \u270f\ufe0f **Ticket Updates** - Status, title, description, priority, assignee changes\n- \ud83d\udcca **Resource Discovery** - List teams, projects, users, labels, workflow states\n- \ud83e\udd16 **AI-Agent Friendly** - Detailed help text, consistent output formats\n- \ud83d\udcdd **Script Integration** - JSON output modes, exit codes, ID-only responses\n- \u26a1 **Performance** - Local caching for fast searches\n- \ud83d\udd04 **Real-time Sync** - Automatic cache refresh after modifications\n\n## \ud83e\udd16 AI Agent Usage Guide\n\n### Step-by-Step Workflow for AI Agents\n\n#### 1. Resource Discovery (ALWAYS DO THIS FIRST)\n```bash\n# Get available teams (required for ticket creation)\nlinear --teams\n# Output: 1. Backend, 2. Frontend Engineering, 3. DevOps\n\n# Get available projects  \nlinear --projects\n# Output: 1. Q4 Features, 2. Bug Fixes, 3. Technical Debt\n\n# Get available users for assignment\nlinear --assignees  \n# Output: 1. John Smith (john@company.com), 2. Jane Doe (jane@company.com)\n\n# Get workflow states for status updates\nlinear --states\n# Output: Backend: Todo, In Progress, In Review, Done\n```\n\n#### 2. Create Tickets with Validation\n```bash\n# Basic creation (minimal required info)\nlinear add --title \"Fix login issue\" --team \"Backend\"\n# Output: \u2705 Successfully created ticket: ZIF-124\n\n# Full creation with all metadata\nlinear add \\\n  --title \"Add user dashboard\" \\\n  --description \"Create comprehensive user management interface\" \\\n  --team \"Frontend Engineering\" \\\n  --project \"Q4 Features\" \\\n  --assignee \"john@company.com\" \\\n  --priority high \\\n  --labels \"feature,frontend,ui\"\n# Output: \u2705 Successfully created ticket: ZIF-125\n```\n\n#### 3. Script-Friendly Operations\n```bash\n# Get only ticket ID for automation\nTICKET_ID=$(linear add --title \"Automated task\" --team \"Backend\" --id-only)\necho \"Created: $TICKET_ID\"\n# Output: Created: ZIF-126\n\n# Search and update\nlinear \"$TICKET_ID\" --status \"In Progress\" --assignee \"jane@company.com\"\n# Output: \u2705 Updated ticket: ZIF-126\n```\n\n### AI Agent Best Practices\n\n1. **Always validate resources first** - Run `--teams`, `--projects`, `--assignees` before creating tickets\n2. **Use exact names** - Team and project names are case-sensitive\n3. **Wrap parameters in quotes** - Especially for titles, descriptions, and names with spaces\n4. **Check exit codes** - Non-zero exit codes indicate errors\n5. **Use `--id-only` for scripting** - Clean output perfect for variable capture\n6. **Handle errors gracefully** - Commands show specific error messages with suggestions\n\n## \ud83d\udcd6 Command Reference\n\n### Ticket Creation\n```bash\nlinear add [OPTIONS]\n\nRequired:\n  --title \"Ticket Title\"              # Main ticket heading\n\nOptional:\n  --description \"Detailed description\" # Supports markdown\n  --team \"Team Name\"                   # From --teams output\n  --project \"Project Name\"             # From --projects output  \n  --assignee \"user@email.com\"          # From --assignees output\n  --priority urgent|high|normal|low    # Or numeric 1|2|3|4\n  --labels \"bug,frontend,critical\"     # Comma-separated, no spaces\n  --parent \"ZIF-19\"                    # Parent ticket ID\n  --id-only                            # Return only ticket ID\n\nExamples:\n  linear add --title \"Fix bug\" --team \"Backend\"\n  linear add --title \"New feature\" --team \"Frontend\" --project \"Q4\" --id-only\n```\n\n### Ticket Search\n```bash\nlinear \"QUERY\" [OPTIONS]\n\nQuery Types:\n  \"ZIF-19\"                            # Direct ticket lookup\n  \"project: Issues, Epic 1\"           # Project + epic search\n  \"bug authentication\"                # Keyword search\n  \nOptions:\n  --limit 5                           # Max results (default: 10)\n\nExamples:\n  linear \"ZIF-123\"\n  linear \"project: Backend database\" --limit 5\n  linear \"critical bug\" --limit 3\n```\n\n### Ticket Updates\n```bash\nlinear \"TICKET-ID\" [UPDATE_OPTIONS]\n\nUpdate Options:\n  --status \"Status Name\"              # From --states output\n  --title \"New Title\"                 # Replace existing title\n  --description \"New description\"     # Replace existing description\n  --priority urgent|high|normal|low   # Or numeric 1|2|3|4\n  --assignee \"user@email.com\"         # From --assignees, or \"none\" to unassign\n\nExamples:\n  linear \"ZIF-19\" --status \"Done\"\n  linear \"ZIF-19\" --assignee \"user@company.com\" --priority high\n  linear \"ZIF-19\" --title \"Updated title\" --status \"In Review\"\n```\n\n### Utility Commands\n```bash\nlinear --teams                        # List all teams\nlinear --projects                     # List all projects  \nlinear --assignees                    # List all users\nlinear --labels                       # List all labels\nlinear --states                       # List workflow states\nlinear --refresh                      # Update local cache\n```\n\n## \ud83d\udca1 Examples\n\n### For AI Agents - Complete Workflows\n\n#### Create and Track a Bug Report\n```bash\n# 1. Discover resources\nTEAMS=$(linear --teams)\nUSERS=$(linear --assignees) \n\n# 2. Create bug ticket\nBUG_ID=$(linear add \\\n  --title \"Login fails with OAuth\" \\\n  --description \"Users cannot authenticate via OAuth provider\" \\\n  --team \"Backend\" \\\n  --assignee \"backend-lead@company.com\" \\\n  --priority urgent \\\n  --labels \"bug,authentication,critical\" \\\n  --id-only)\n\necho \"Created bug report: $BUG_ID\"\n\n# 3. Update as work progresses\nlinear \"$BUG_ID\" --status \"In Progress\"\nlinear \"$BUG_ID\" --description \"Root cause identified: OAuth callback URL misconfigured\"\nlinear \"$BUG_ID\" --status \"In Review\"\nlinear \"$BUG_ID\" --status \"Done\"\n```\n\n#### Create Feature with Sub-tasks\n```bash\n# 1. Create parent feature\nFEATURE_ID=$(linear add \\\n  --title \"User Dashboard v2\" \\\n  --description \"Redesigned user dashboard with analytics\" \\\n  --team \"Frontend\" \\\n  --project \"Q4 Features\" \\\n  --priority high \\\n  --id-only)\n\n# 2. Create sub-tasks\nSUBTASK1=$(linear add \\\n  --title \"Dashboard layout component\" \\\n  --parent \"$FEATURE_ID\" \\\n  --team \"Frontend\" \\\n  --assignee \"ui-dev@company.com\" \\\n  --id-only)\n\nSUBTASK2=$(linear add \\\n  --title \"Analytics integration\" \\\n  --parent \"$FEATURE_ID\" \\\n  --team \"Frontend\" \\\n  --assignee \"data-dev@company.com\" \\\n  --id-only)\n\necho \"Feature: $FEATURE_ID, Subtasks: $SUBTASK1, $SUBTASK2\"\n```\n\n### For Humans - Interactive Usage\n\n#### Daily Ticket Management\n```bash\n# Check my assigned tickets\nlinear \"assignee: john@company.com\"\n\n# Create quick ticket\nlinear add --title \"Fix header alignment\" --team \"Frontend\"\n\n# Update ticket status\nlinear \"ZIF-45\" --status \"Done\"\n\n# Search for recent bugs\nlinear \"bug\" --limit 5\n```\n\n## \ud83d\udd27 Automation & Scripting\n\n### Exit Codes\n- `0` - Success\n- `1` - Error (validation failed, API error, ticket not found)\n- `2` - Invalid arguments\n\n### Scripting Examples\n\n#### CI/CD Integration\n```bash\n#!/bin/bash\n\n# Create deployment ticket\nDEPLOY_ID=$(linear add \\\n  --title \"Deploy v${VERSION} to production\" \\\n  --description \"Automated deployment of version ${VERSION}\" \\\n  --team \"DevOps\" \\\n  --assignee \"$DEPLOY_ENGINEER\" \\\n  --labels \"deployment,production\" \\\n  --id-only)\n\nif [ $? -eq 0 ]; then\n  echo \"Deployment tracked in ticket: $DEPLOY_ID\"\n  \n  # Update ticket during deployment\n  linear \"$DEPLOY_ID\" --status \"In Progress\"\n  \n  # Deploy application...\n  if deploy_application; then\n    linear \"$DEPLOY_ID\" --status \"Done\" --description \"Successfully deployed v${VERSION}\"\n  else\n    linear \"$DEPLOY_ID\" --status \"Failed\" --description \"Deployment failed: check logs\"\n    exit 1\n  fi\nelse\n  echo \"Failed to create deployment ticket\"\n  exit 1\nfi\n```\n\n#### Batch Operations\n```bash\n#!/bin/bash\n\n# Process multiple tickets\nTICKETS=(\"ZIF-10\" \"ZIF-11\" \"ZIF-12\")\n\nfor ticket in \"${TICKETS[@]}\"; do\n  echo \"Processing $ticket...\"\n  linear \"$ticket\" --status \"Done\" --assignee \"none\"\n  if [ $? -eq 0 ]; then\n    echo \"\u2705 Updated $ticket\"\n  else\n    echo \"\u274c Failed to update $ticket\"\n  fi\ndone\n```\n\n## \ud83d\udc1b Troubleshooting\n\n### Common Issues\n\n#### Authentication Errors\n```bash\n# Problem: \"LINEAR_API_TOKEN environment variable not set\"\n# Solution:\nexport LINEAR_API_TOKEN=\"your_token_here\"\n\n# Problem: \"400 Client Error: Bad Request\"  \n# Solution: Check token permissions in Linear settings\n```\n\n#### Validation Errors\n```bash\n# Problem: \"Team 'backend' not found\"\n# Solution: Check exact team name\nlinear --teams  # See available teams\n\n# Problem: \"User 'john' not found\"\n# Solution: Use email or exact display name\nlinear --assignees  # See available users\n```\n\n#### Search Issues\n```bash\n# Problem: \"No tickets found\"\n# Solution: Refresh cache and check query\nlinear --refresh\nlinear --projects  # Verify project names\n```\n\n### Debug Mode\n```bash\n# Add --token flag to see API requests\nlinear --token \"$LINEAR_API_TOKEN\" add --title \"Debug test\"\n```\n\n### Getting Help\n```bash\nlinear --help              # Main help\nlinear add --help          # Ticket creation help\n```\n\n## \ud83d\udcc2 Project Structure\n\n```\nlinear-cli/\n\u251c\u2500\u2500 linear_search.py       # Main CLI application\n\u251c\u2500\u2500 linear_client.py       # Linear API client\n\u251c\u2500\u2500 ticket_search.py       # Search engine and ticket operations  \n\u251c\u2500\u2500 requirements.txt       # Python dependencies\n\u251c\u2500\u2500 setup_alias.sh         # Installation helper\n\u251c\u2500\u2500 .env.example          # Environment template\n\u251c\u2500\u2500 .gitignore            # Git ignore rules\n\u2514\u2500\u2500 README.md             # This file\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! This tool is designed to be AI-agent friendly while maintaining excellent usability for humans.\n\n### Quick Start for Contributors\n\n1. **Fork the repository** on GitHub\n2. **Clone your fork** locally\n3. **Set up development environment** (see Installation section)\n4. **Make your changes** following our development principles\n5. **Test thoroughly** with real Linear workspaces\n6. **Submit a pull request** with detailed description\n\n### Development Principles\n\nWhen extending functionality:\n\n1. **Add detailed help text** - Include examples and validation notes\n2. **Use consistent output formats** - Maintain JSON-friendly responses\n3. **Handle errors gracefully** - Provide actionable error messages\n4. **Document new features** - Update README with AI-agent examples\n5. **Test with real scenarios** - Validate against actual Linear workspaces\n\nFor detailed contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Built for the Linear community\n- Designed with AI agents in mind\n- Inspired by the need for powerful CLI tools in modern development workflows\n\n## \ud83d\udcde Support\n\nIf you encounter issues or have questions:\n1. Check the [troubleshooting section](#-troubleshooting) in this README\n2. Review existing [issues](https://github.com/vittoridavide/linear-cli/issues)\n3. Create a new issue with detailed information\n4. Consider contributing a fix!\n\n## \ud83d\udd17 Related Projects\n\n- [Linear](https://linear.app) - The excellent project management tool this CLI interacts with\n- [Linear API](https://developers.linear.app) - Official Linear API documentation\n\n---\n\n**Built for AI agents, humans, and automation. Happy ticket managing! \ud83c\udfab**\n",
    "bugtrack_url": null,
    "license": "MIT License\n        \n        Copyright (c) 2024 Linear Ticket Manager CLI\n        \n        Permission is hereby granted, free of charge, to any person obtaining a copy\n        of this software and associated documentation files (the \"Software\"), to deal\n        in the Software without restriction, including without limitation the rights\n        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n        copies of the Software, and to permit persons to whom the Software is\n        furnished to do so, subject to the following conditions:\n        \n        The above copyright notice and this permission notice shall be included in all\n        copies or substantial portions of the Software.\n        \n        THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n        SOFTWARE.",
    "summary": "A comprehensive command-line tool for managing Linear tickets with AI-agent friendly interfaces",
    "version": "1.0.0",
    "project_urls": {
        "Documentation": "https://github.com/vittoridavide/linear-cli#readme",
        "Homepage": "https://github.com/vittoridavide/linear-cli",
        "Issues": "https://github.com/vittoridavide/linear-cli/issues",
        "Repository": "https://github.com/vittoridavide/linear-cli"
    },
    "split_keywords": [
        "linear",
        " cli",
        " ticket-management",
        " project-management",
        " ai-agent",
        " automation",
        " graphql",
        " productivity"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "dddd9fa723437155badba6070ca87699a0414563595672a61f83d4725f263aaf",
                "md5": "7359d3e147906bca8af66e4c960aa179",
                "sha256": "58ed4d94a7399c7d7b2d0ad9e6518553d7fcd1eae1ca188e743f1c184805f019"
            },
            "downloads": -1,
            "filename": "linear_ticket_cli-1.0.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "7359d3e147906bca8af66e4c960aa179",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 30352,
            "upload_time": "2025-10-11T13:45:20",
            "upload_time_iso_8601": "2025-10-11T13:45:20.019023Z",
            "url": "https://files.pythonhosted.org/packages/dd/dd/9fa723437155badba6070ca87699a0414563595672a61f83d4725f263aaf/linear_ticket_cli-1.0.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "d2dc9969ce90eb43319aae86804ff72efc13875c219c77de9f0527eb963b50aa",
                "md5": "39e75cea3dd0ad1d6c2b759a4baa7d0c",
                "sha256": "7f972707235208652ef4a76d8dfaca87f58a975598e7498e297d3c94dd542575"
            },
            "downloads": -1,
            "filename": "linear_ticket_cli-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "39e75cea3dd0ad1d6c2b759a4baa7d0c",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 45116,
            "upload_time": "2025-10-11T13:45:21",
            "upload_time_iso_8601": "2025-10-11T13:45:21.566327Z",
            "url": "https://files.pythonhosted.org/packages/d2/dc/9969ce90eb43319aae86804ff72efc13875c219c77de9f0527eb963b50aa/linear_ticket_cli-1.0.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-11 13:45:21",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "vittoridavide",
    "github_project": "linear-cli#readme",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "requirements": [
        {
            "name": "requests",
            "specs": [
                [
                    ">=",
                    "2.31.0"
                ]
            ]
        },
        {
            "name": "fuzzywuzzy",
            "specs": [
                [
                    ">=",
                    "0.18.0"
                ]
            ]
        },
        {
            "name": "python-levenshtein",
            "specs": [
                [
                    ">=",
                    "0.21.0"
                ]
            ]
        }
    ],
    "lcname": "linear-ticket-cli"
}