Linear CLI

A command-line interface for Linear project management, designed for efficient workflows and Claude agent integration.

Installation

cd linear-cli
make build
make install  # Installs to ~/.local/bin/linear

Configuration

Required Environment Variables

Variable	Description
`LINEAR_API_TOKEN`	Your Linear API token (required)

Get your API token from: Linear Settings → API → Personal API Keys

Optional Default Values

These environment variables provide defaults for common operations:

Variable	Description	Example
`LINEAR_DEFAULT_TEAM`	Default team key or ID	`MYTEAM`
`LINEAR_DEFAULT_PROJECT`	Default project ID	`abc123...`
`LINEAR_DEFAULT_STATE`	Default workflow state ID	`xyz789...`
`LINEAR_DEFAULT_PRIORITY`	Default priority (0-4)	`2`

Integration with direnv

For automatic environment configuration when entering the project directory, use direnv:

Install direnv:
```
brew install direnv
```
Add to your shell (~/.zshrc or ~/.bashrc):
```
eval "$(direnv hook zsh)"  # or bash
```

Create .envrc in your project root:

# Linear API
export LINEAR_API_TOKEN="lin_api_..."

# Default values for convenience
export LINEAR_DEFAULT_TEAM="MYTEAM"
# export LINEAR_DEFAULT_PROJECT="..."  # Optional
# export LINEAR_DEFAULT_STATE="..."    # Optional
# export LINEAR_DEFAULT_PRIORITY="2"   # Optional (0-4)

Allow the directory:
```
direnv allow
```

Now when you cd into the project, credentials are automatically loaded.

Usage

View All Commands

linear tree

Workspace Summary

Get a comprehensive overview of workspace state in one call.

# Get summary for a team
linear workspace summary --team MYTEAM

# Output as JSON
linear workspace summary --team MYTEAM --output json

Shows:

Current cycle with progress
Issues by state and priority
Recent activity (created/closed last 7 days)
Active projects with progress

Workspace Tree

Display your Linear workspace hierarchy with initiatives, projects, and issues.

# Show initiatives and projects
linear tree workspace

# Short alias
linear tree w

# Include issues under each project (limited to 10 per project)
linear tree workspace --issues

# Hide status/state information
linear tree workspace --no-status

# Disable colors (useful for piping)
linear tree workspace --no-color

# Output as JSON (for programmatic use)
linear tree workspace --format json

Issues Tree

View all issues grouped by project, team, or state.

# Group issues by project (default)
linear tree issues

# Group issues by team
linear tree issues --by team

# Group issues by state
linear tree issues --by state

# Filter to specific team
linear tree issues --team MYTEAM

# Combine options
linear tree issues --by state --team MYTEAM --no-color

# Output as JSON
linear tree issues --format json

Graph Visualization

Generate Graphviz DOT format output to visualize project structure.

# Generate graph grouped by project (default)
linear tree graph

# Render to PNG (requires graphviz installed)
linear tree graph | dot -Tpng -o graph.png

# Render to SVG
linear tree graph | dot -Tsvg -o graph.svg

# Group by different attributes
linear tree graph --by team
linear tree graph --by state
linear tree graph --by assignee
linear tree graph --by cycle
linear tree graph --by label

# Filter to specific team
linear tree graph --team MYTEAM

# Include labels and cycle info on nodes
linear tree graph --labels --cycles

# Change orientation (TB=top-bottom, LR=left-right)
linear tree graph --orientation LR

Features:

Color-coded nodes based on issue state
Subgraphs for each group with pastel backgrounds
Parent-child relationships shown as edges
Optional labels and cycle information on nodes

Issues

All commands use explicit flags (no positional arguments) for clarity and self-documentation.

# List all issues
linear issues list

# List with filters (all accept friendly names)
linear issues list --team MYTEAM
linear issues list --project "Phase 0"
linear issues list --state "In Progress"
linear issues list --assignee "john@example.com"
linear issues list --label "type/bug"
linear issues list --priority 1
linear issues list --created-after 2024-01-01
linear issues list --unlabeled                  # Show only issues without labels
linear issues list --mine                       # Show only issues assigned to me
linear issues list --cycle current              # Show issues in current cycle
linear issues list --cycle 8                    # Show issues in cycle #8
linear issues list --stale 30                   # Show issues not updated in 30 days

# Get a specific issue
linear issues get --id PROJ-123

# Create an issue (uses defaults from env vars)
linear issues create --title "Fix login bug"

# Create with explicit options
linear issues create --title "New feature" --team MYTEAM --description "Details here"

# Update an issue
linear issues update --id PROJ-123 --state-id <state-id>

# Add a comment
linear issues comment --id PROJ-123 --body "This is my update"

# Clone an issue with a new title
linear issues clone --id PROJ-123 --title "Copy of original issue"

# Create a sub-issue (child of another issue)
linear issues create --title "Subtask" --team MYTEAM --parent-id PROJ-123

# List child issues of a parent
linear issues children --id PROJ-123

# List comments on an issue
linear issues comments --id PROJ-123

# Set a parent issue (convert to sub-issue)
linear issues assign parent --issue PROJ-124 --to PROJ-123

# Remove parent (convert back to top-level issue)
linear issues unassign parent --issue PROJ-124

Issue Statistics

# Show overall stats (counts by state, priority, team)
linear issues stats

# Stats for a specific team
linear issues stats --team MYTEAM

# Stats for issues created in the last 7 days
linear issues stats --since 7d

# Stats for issues created since a date
linear issues stats --since 2024-01-01

# Show issues opened (created) recently
linear issues stats opened --since 7d

# Show issues closed (completed/canceled) recently
linear issues stats closed --since 7d --team MYTEAM

Projects

# List all projects
linear projects list

# List with filters
linear projects list --state started
linear projects list --initiative "Q1 Goals"

# Get a specific project
linear projects get --id <project-id>

# Create a project
linear projects create --name "Q1 Release" --team-id <team-id>

Cycles (Sprints)

# List cycles for a team
linear cycles list --team MYTEAM

# Get the current active cycle
linear cycles current --team MYTEAM

# List issues in a cycle
linear cycles issues                        # Issues in current cycle
linear cycles issues --team MYTEAM             # Issues in current cycle for team MYTEAM
linear cycles issues --cycle 8              # Issues in cycle #8
linear cycles issues --cycle 8 --team MYTEAM   # Issues in cycle #8 for team MYTEAM

# Create a cycle
linear cycles create --team MYTEAM --starts-at 2026-01-20 --ends-at 2026-02-02 --name "Sprint 1"

# Update a cycle
linear cycles update --id <cycle-id> --name "Sprint 1 - Updated"

# Delete (archive) a cycle
linear cycles delete --id <cycle-id>

Initiatives

# List all initiatives
linear initiatives list

# Get an initiative
linear initiatives get --id <id>

# Create an initiative
linear initiatives create --name "Q1 Goals" --description "Goals for Q1"

# Update an initiative
linear initiatives update --id <id> --status "completed"

# Delete an initiative
linear initiatives delete --id <id>

Labels

# List all labels
linear labels list

# Get a label
linear labels get --id <id>

# Create a label
linear labels create --name "priority-critical" --color "#ff0000" --team MYTEAM

# Update a label
linear labels update --id <id> --color "#00ff00"

# Delete a label
linear labels delete --id <id>

Teams and States

# List all teams
linear teams list

# List workflow states for a team
linear states list --team MYTEAM

Reports

Generate markdown reports from issues and their sub-issues.

# Generate a report to stdout (multiple --issue flags)
linear report generate --issue PROJ-129 --issue PROJ-126 --issue PROJ-127

# Comma-separated issues also work
linear report generate --issue PROJ-129,PROJ-126,PROJ-127

# Write to a file with custom title
linear report generate --output q1_report.md --title "Q1 2026 Deep Research Report" --issue PROJ-129 --issue PROJ-126

# Include sub-issues with --children flag
linear report generate --children --issue PROJ-129 --issue PROJ-138

# Full example
linear report generate \
  --output docs/research_report.md \
  --title "Research Findings" \
  --children \
  --issue PROJ-129 \
  --issue PROJ-126

The report includes:

Table of contents with anchor links
Issue descriptions and metadata
All comments (sorted chronologically)
Sub-issues with their comments (when --children is used)

Daily Digest

Generate a quick daily status report without AI analysis.

# Generate daily digest
linear report daily --team MYTEAM

# Output as JSON
linear report daily --team MYTEAM --output json

Shows:

Completed issues (yesterday/today)
In-progress issues
Blocked issues
Upcoming issues in current cycle

Convert to PDF

Convert any markdown file to a beautifully formatted PDF using the Eisvogel template.

# Basic conversion
linear report pdf --input docs/report.md

# With custom output path and title
linear report pdf --input docs/report.md --output docs/report.pdf --title "Research Report"

# Include table of contents
linear report pdf --input docs/report.md --toc

# Dark theme
linear report pdf --input docs/report.md --dark

Prerequisites: pandoc and lualatex (via basictex). The Eisvogel template is auto-installed on first run.

Assign/Unassign Commands

Manage relationships between issues and other resources. All commands accept friendly names that are resolved case-insensitively.

# Assign issue to project
linear issues assign project --issue PROJ-123 --to "Phase 0"

# Unassign issue from project
linear issues unassign project --issue PROJ-123

# Assign issue to user (by email or name)
linear issues assign user --issue PROJ-123 --to "john@example.com"

# Unassign issue from user
linear issues unassign user --issue PROJ-123

# Assign issue to state (workflow transition)
linear issues assign state --issue PROJ-123 --to "In Progress"

# Assign issue to cycle
linear issues assign cycle --issue PROJ-123 --to 5

# Unassign issue from cycle
linear issues unassign cycle --issue PROJ-123

# Add label to issue
linear issues assign label --issue PROJ-123 --to "type/bug"

# Remove label from issue
linear issues unassign label --issue PROJ-123 --from "type/bug"

# Link project to initiative
linear projects assign initiative --project "Phase 0" --to "Q1 Goals"

# Unlink project from initiative
linear projects unassign initiative --project "Phase 0" --from "Q1 Goals"

Workflows

Automated workflows that combine Linear data gathering with AI analysis.

# Run daily Claude-Gemini review workflow
linear workflow daily-review

# Run with flags
linear workflow daily-review --dry-run        # Preview what would be done
linear workflow daily-review --gather-only    # Only gather context, skip AI analysis
linear workflow daily-review --skip-gemini    # Skip Gemini review step

# Deep research on a specific topic
linear workflow research --topic PROJ-123         # Research specific issue
linear workflow research --topic highest-impact  # Auto-select highest impact issue
linear workflow research --topic oldest-urgent   # Auto-select oldest urgent issue

# Research with flags
linear workflow research --topic PROJ-123 --dry-run
linear workflow research --topic PROJ-123 --skip-sub-issues

# Full research cycle (daily review + topic selection + deep research)
linear workflow research-cycle

# Research cycle with flags
linear workflow research-cycle --skip-daily-review  # Skip to research phase
linear workflow research-cycle --topic PROJ-123      # Override topic selection

# Auto-label issues using AI analysis
linear workflow auto-label                     # Show suggestions for unlabeled issues
linear workflow auto-label --team MYTEAM          # Filter to specific team
linear workflow auto-label --apply             # Apply suggested labels
linear workflow auto-label --review-all        # Review all issues, not just unlabeled
linear workflow auto-label --dry-run           # Preview without making changes

# Transform research into formal deliverables (technical paper, briefing, implementation plan)
linear workflow paper --research-output ./private/research/2026-01-20T150405
linear workflow paper --topic PROJ-123                    # Find research by topic
linear workflow paper --topic PROJ-123 --dry-run         # Preview what would be done
linear workflow paper --topic PROJ-123 --skip-issues     # Skip Linear issue creation
linear workflow paper --topic PROJ-123 --skip-knowledge  # Skip knowledge base updates
linear workflow paper --resume ./private/papers/2026-01-20T150405/workflow-state.json

All workflows support:

State tracking - Resume interrupted workflows
Partial results - Get findings even if workflow fails midway
Dry run mode - Preview what would be done

Output Formats

# JSON output (default)
linear issues list

# Quiet mode (IDs only)
linear issues list -q

# Debug mode (shows API requests)
linear issues list --debug

Team Resolution

The --team flag accepts both:

Team keys (e.g., MYTEAM) - short, memorable identifiers
Team IDs (e.g., df66a9b2-cbbe-4068-b483-a9eb0e320a90) - full UUIDs

Team keys are automatically resolved to IDs.

Design Philosophy

This CLI uses explicit flags instead of positional arguments for all commands. This design choice makes the CLI:

Self-documenting - --id PROJ-123 is clearer than a bare PROJ-123
Order-independent - Flags can appear in any order
Agent-friendly - Claude can construct commands reliably with explicit names
Grep-friendly - Easy to search command history for specific flags

Multi-value flags support both styles:

# Repeated flags (more explicit)
linear report generate --issue PROJ-129 --issue PROJ-126

# Comma-separated (more concise)
linear report generate --issue PROJ-129,PROJ-126

Claude Agent Integration

This CLI is designed for use with Claude agents. Key features:

JSON output - Easy to parse programmatically
Quiet mode - Returns only IDs for chaining commands
Environment defaults - Reduce command verbosity
Consistent error messages - Clear feedback for troubleshooting
Explicit flags - No positional arguments, making commands unambiguous

Example Claude Workflow

# Read an issue
linear issues get --id PROJ-123

# Update status
linear issues update --id PROJ-123 --state-id <in-progress-state-id>

# Add progress comment
linear issues comment --id PROJ-123 --body "## Progress Update

Started implementation. Key changes:
- Added validation middleware
- Updated API tests"

# Mark as done
linear issues update --id PROJ-123 --state-id <done-state-id>

Development

# Build
make build

# Run tests
make test

# Install locally
make install

# Clean
make clean

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
cmd		cmd
docs		docs
internal/linear		internal/linear
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

License

jllovet/linear-cli

Folders and files

Latest commit

History

Repository files navigation

Linear CLI

Installation

Configuration

Required Environment Variables

Optional Default Values

Integration with direnv

Usage

View All Commands

Workspace Summary

Workspace Tree

Issues Tree

Graph Visualization

Issues

Issue Statistics

Projects

Cycles (Sprints)

Initiatives

Labels

Teams and States

Reports

Daily Digest

Convert to PDF

Assign/Unassign Commands

Workflows

Output Formats

Team Resolution

Design Philosophy

Claude Agent Integration

Example Claude Workflow

Development

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages