linear-app 0.0.1

Add your description here

Linear CLI

A command-line interface for interacting with Linear - list issues, view project details, and manage your workflow from the terminal.

Authentication

Set your Linear API key as an environment variable:

export LINEAR_API_KEY="<linear-api-key>"

Get your API key at: https://linear.app/settings/api

Available Commands

Issues

# List issues with filters
linear issues list [OPTIONS]

# View details of a specific issue
linear issues view <issue-id> [OPTIONS]

# Search issues by title
linear issues search <query> [OPTIONS]

# Create a new issue (interactive if no title provided)
linear issues create [title] [OPTIONS]

List options:

• --assignee <email> - Filter by assignee (use "me" or "self" for yourself)
• --status <status> - Filter by status (e.g., "in progress", "done")
• --priority <0-4> - Filter by priority
• --team <team> - Filter by team name or key
• --project <name> - Filter by project name
• --label <label> - Filter by label (repeatable)
• --limit <n> - Number of results (default: 50)
• --sort <field> - Sort results
• --format <format> - Output format: table (default), json

View options:

• --web/-w - Open issue in browser
• --format/-f <format> - Output format: detail (default), json

Search options:

• --limit <n> - Number of results (default: 50)
• --sort <field> - Sort results
• --format/-f <format> - Output format: table (default), json

Create options:

• --team/-t <team> - Team key (e.g., "ENG")
• --description/-d <text> - Issue description
• --assignee/-a <email> - Assign to user
• --priority/-p <0-4> - Priority level
• --project <name> - Project name
• --label/-l <label> - Add label (repeatable)
• --format/-f <format> - Output format: detail (default), json

Projects

# List projects
linear projects list [OPTIONS]

# View details of a specific project
linear projects view <project-id> [OPTIONS]

List options:

• --state <state> - Filter by state (planned, started, paused, completed, canceled)
• --team <team> - Filter by team name or key
• --limit <n> - Number of results (default: 50)
• --include-archived - Include archived projects
• --format/-f <format> - Output format: table (default), json

View options:

• --format/-f <format> - Output format: detail (default), json

Teams

# List all teams
linear teams list [OPTIONS]

# View details of a specific team
linear teams view <team-id> [OPTIONS]

List options:

• --limit <n> - Number of results (default: 50)
• --include-archived - Include archived teams
• --format/-f <format> - Output format: table (default), json

View options:

• --format/-f <format> - Output format: detail (default), json

Note: Team ID can be a team key (e.g., "ENG") or team ID.

Cycles

# List cycles
linear cycles list [OPTIONS]

# View details of a specific cycle
linear cycles view <cycle-id> [OPTIONS]

List options:

• --team/-t <team> - Filter by team name or key
• --active/-a - Show only active cycles
• --future - Show only future cycles
• --past - Show only past cycles
• --limit/-l <n> - Number of results (default: 50)
• --include-archived - Include archived cycles
• --format/-f <format> - Output format: table (default), json

View options:

• --format/-f <format> - Output format: detail (default), json

Users

# List workspace users
linear users list [OPTIONS]

# View details of a specific user
linear users view <user-id> [OPTIONS]

List options:

• --active-only - Show only active users (default: true)
• --include-disabled - Include disabled users
• --limit/-l <n> - Number of results (default: 50)
• --format/-f <format> - Output format: table (default), json

View options:

• --format/-f <format> - Output format: detail (default), json

Note: User ID can be an email address or user ID.

Labels

# List issue labels
linear labels list [OPTIONS]

List options:

• --team/-t <team> - Filter by team ID or key
• --limit/-l <n> - Number of results (default: 50)
• --include-archived - Include archived labels
• --format/-f <format> - Output format: table (default), json

Common Patterns

Command Aliases: You can use short aliases for all command groups:

• linear i instead of linear issues
• linear p instead of linear projects
• linear t instead of linear teams
• linear c instead of linear cycles
• linear u instead of linear users
• linear l instead of linear labels

Output Formats:

• table - Human-readable table format (default for list commands)
• json - JSON output for scripting and automation
• detail - Detailed view (default for view commands)

Common Flags:

• Most list commands support --limit to control result count
• Most list commands support --include-archived to show archived items
• All commands support --format/-f to change output format

Development

Pre-commit Hooks

This project uses pre-commit to run code quality checks before commits. All hooks use uv run to execute tools from the project's virtual environment:

• ruff check --fix for linting
• ruff format for code formatting
• ty check for type checking

Setup:

# Install dev dependencies (includes pre-commit, ruff, and ty)
uv sync --dev

# Install the pre-commit hooks
uv run pre-commit install

Manual run:

# Run on all files
uv run pre-commit run --all-files

# Run on staged files only
uv run pre-commit run

The hooks will automatically run when you commit changes. If any issues are found and auto-fixed, you'll need to stage the fixes and commit again.

Releases

Setup

1. Generate PyPI API token at https://pypi.org/manage/account/token/
2. Set the environment variable:

   export UV_PUBLISH_TOKEN="pypi-..."
   

Release Process

1. Update version in pyproject.toml

   vim pyproject.toml  # Change version = "X.Y.Z"
   

2. Commit version bump

   git add pyproject.toml
   git commit -m "Bump version to X.Y.Z"
   git push origin main
   

3. Publish to PyPI

   make publish