linear-cli-agents

The Linear CLI built for AI agents and Claude Code. JSON-first output, the broadest command coverage of any Linear CLI (issues, projects, initiatives, customers, documents, and more), bulk operations with --dry-run previews, and an --unblocked filter that surfaces what's actually actionable right now.

Why this Linear CLI

Built for agents, not retrofitted: every command defaults to structured JSON; linear info gives an LLM the entire command surface in one call, no man pages to scrape
Safer bulk changes: bulk-update / bulk-label support --dry-run so an agent (or you) can preview a mass edit before it touches real issues
Find what's actionable: issues list --unblocked filters out issues still stuck behind an unresolved blocker
Widest entity coverage: the only Linear CLI with full CRUD on documents, initiatives, and customers, not just issues and projects
One-command Claude Code setup: linear setup installs a skill, allow-lists the CLI, and writes CLAUDE.md notes automatically

Features

JSON output: All commands return structured JSON, perfect for parsing by LLMs
Multiple formats: JSON (default), table (colored), or plain text output
Comprehensive docs: linear info returns full CLI documentation in one command
Configurable defaults: Set default team to skip --team-id on every command
Bulk operations: Update multiple issues at once with bulk-update and bulk-label, with --dry-run previews
Unblocked filter: issues list --unblocked finds issues with no active (unresolved) blocking issue
Schema introspection: Discover available operations programmatically
Full CRUD: Issues, projects, labels, comments, templates, milestones, documents, initiatives, customers
Issue relations: Manage blocks, duplicates, and related issues
Project management: Projects, milestones, and status updates
Team management: List and browse teams, states, users
Browser integration: Open issues, teams, inbox directly in Linear
Search: Find issues across workspace
Raw GraphQL queries: Execute any GraphQL query directly

Installation

npm install -g linear-cli-agents
# or
pnpm add -g linear-cli-agents

Quick Start

# Install
npm install -g linear-cli-agents

# Authenticate
linear auth login

# Get full CLI documentation (recommended for LLMs)
linear info

# Configure default team (optional, skips --team-id on every command)
linear config set default-team-id YOUR_TEAM_ID

# Add CLAUDE.md notes, install the Claude Code skill, and allow-list permissions (optional)
linear setup

Authentication

# Open Linear API settings in browser to create a key
linear auth login --browser

# Login with API key
linear auth login --key lin_api_xxxxx

# Or use environment variable
export LINEAR_API_KEY=lin_api_xxxxx

# Check auth status
linear auth status

# View current user info
linear me

# Logout
linear auth logout

Configuration

# Set default team (skips --team-id on create commands)
linear config set default-team-id YOUR_TEAM_UUID
linear config set default-team-key TEAM_KEY

# Get a config value
linear config get default-team-id

# List all config
linear config list

Usage

Issues

# List all issues
linear issues list

# List with filters
linear issues list --team ENG
linear issues list --assignee me
linear issues list --state "In Progress"
linear issues list --filter '{"priority":{"lte":2}}'

# Only issues with no active blocker (a completed/canceled blocker no longer counts)
linear issues list --unblocked

# Output formats: json (default), table (colored), plain (IDs only)
linear issues list --format table
linear issues list --format plain

# Get a specific issue
linear issues get ENG-123
linear issues get ENG-123 --format table
linear issues get ENG-123 --with-attachments  # Include linked PRs, commits

# Create an issue
linear issues create --title "Bug fix" --team-id <team-id>
linear issues create --title "Task" --team-id <team-id> --due-date 2024-12-31
linear issues create --title "Sprint work" --team-id <team-id> --cycle-id <cycle-id>
linear issues create --input '{"title":"Feature","teamId":"xxx","priority":2}'

# Update an issue
linear issues update ENG-123 --title "Updated title"
linear issues update ENG-123 --state-id <state-id> --assignee-id <user-id>

# Delete an issue (moves to trash)
linear issues delete ENG-123

# Archive/unarchive an issue
linear issues archive ENG-123
linear issues archive ENG-123 --unarchive

# Manage labels on issues
linear issues add-labels ENG-123 --label-ids LABEL_ID1,LABEL_ID2
linear issues remove-labels ENG-123 --label-ids LABEL_ID1

# Bulk update multiple issues at once
linear issues bulk-update --ids ENG-1,ENG-2,ENG-3 --state-id STATE_ID
linear issues bulk-update --ids ENG-1,ENG-2 --priority 2 --assignee-id USER_ID
linear issues bulk-update --ids ENG-1,ENG-2,ENG-3 --state-id STATE_ID --dry-run  # preview first

# Bulk add/remove labels from multiple issues
linear issues bulk-label --ids ENG-1,ENG-2,ENG-3 --add-labels LABEL1,LABEL2
linear issues bulk-label --ids ENG-1,ENG-2 --remove-labels LABEL1
linear issues bulk-label --ids ENG-1,ENG-2,ENG-3 --add-labels LABEL1 --dry-run  # preview first

Projects

# List projects
linear projects list
linear projects list --team ENG
linear projects list --state started

# Get project details
linear projects get PROJECT_ID

# Create a project
linear projects create --name "Q1 Goals" --team-ids TEAM_ID
linear projects create --name "Feature X" --team-ids TEAM_ID --target-date 2024-06-30

# Update a project
linear projects update PROJECT_ID --name "Updated Name"
linear projects update PROJECT_ID --state completed

# Delete a project
linear projects delete PROJECT_ID

# Archive/unarchive a project
linear projects archive PROJECT_ID
linear projects archive PROJECT_ID --unarchive

Project Milestones

# List milestones for a project
linear milestones list PROJECT_ID

# Get milestone details
linear milestones get MILESTONE_ID

# Create a milestone
linear milestones create PROJECT_ID --name "Alpha Release" --target-date 2024-03-01

# Update a milestone
linear milestones update MILESTONE_ID --name "Beta Release"

Project Updates

# List status updates for a project
linear project-updates list PROJECT_ID

# Get update details
linear project-updates get UPDATE_ID

# Create a status update
linear project-updates create PROJECT_ID --body "Sprint completed" --health onTrack

# Update a status update
linear project-updates update UPDATE_ID --body "Updated status"

Issue Relations

# List relations for an issue
linear relations list ENG-123

# Create a relation
linear relations create ENG-123 ENG-456 --type blocks
linear relations create ENG-123 ENG-456 --type duplicate
linear relations create ENG-123 ENG-456 --type related

# Delete a relation
linear relations delete RELATION_ID

Labels

# List labels
linear labels list
linear labels list --team ENG

# Create a label
linear labels create --name "Bug" --color "#FF0000"
linear labels create --name "Feature" --color "#00FF00" --team-id TEAM_ID

# Update a label
linear labels update LABEL_ID --name "Critical Bug" --color "#FF0000"

# Delete a label
linear labels delete LABEL_ID

Templates

# List templates
linear templates list
linear templates list --team ENG

# Get template details
linear templates get TEMPLATE_ID

# Create a template
linear templates create --name "Bug Report" --type issue --team-id TEAM_ID \
  --template-data '{"title":"Bug: ","priority":2}'

# Update a template
linear templates update TEMPLATE_ID --name "Updated Template"

Comments

# List comments on an issue
linear comments list ENG-123

# Add a comment
linear comments add ENG-123 --body "This looks good!"

# Update a comment
linear comments update COMMENT_ID --body "Updated comment"

# Delete a comment
linear comments delete COMMENT_ID

States

# List workflow states
linear states list
linear states list --team ENG

Cycles (Sprints)

# List all cycles
linear cycles list
linear cycles list --team ENG

# Filter by status
linear cycles list --active      # Currently running
linear cycles list --upcoming    # Future cycles
linear cycles list --completed   # Past cycles

# Get current cycle for a team
linear cycles current --team ENG

# Get cycle details
linear cycles get CYCLE_ID

Documents

# List documents
linear documents list

# Get document details
linear documents get DOCUMENT_ID

# Create a document
linear documents create --title "Meeting Notes"
linear documents create --title "Specs" --content "# Overview\n\nDetails here..."
linear documents create --title "Project Doc" --project-id PROJECT_ID

# Update a document
linear documents update DOCUMENT_ID --title "New Title"
linear documents update DOCUMENT_ID --content "Updated content"

# Delete a document
linear documents delete DOCUMENT_ID

Initiatives

# List initiatives
linear initiatives list
linear initiatives list --status Active
linear initiatives list --status Completed

# Get initiative details
linear initiatives get INITIATIVE_ID

# Create an initiative
linear initiatives create --name "Q1 Goals"
linear initiatives create --name "Product Launch" --status Active --target-date 2024-12-31

# Update an initiative
linear initiatives update INITIATIVE_ID --name "New Name"
linear initiatives update INITIATIVE_ID --status Completed

# Archive/unarchive an initiative
linear initiatives archive INITIATIVE_ID
linear initiatives archive INITIATIVE_ID --unarchive

# Delete an initiative
linear initiatives delete INITIATIVE_ID

Customers

# List customers
linear customers list
linear customers list --format table
linear customers list --name "Acme"

# Get customer details (includes needs)
linear customers get CUSTOMER_ID

# Create a customer
linear customers create --name "Acme Corp (Pro)" --domains "acme.com" --size 5
linear customers create --name "John Doe (Free)" --status-id STATUS_ID
linear customers create --input '{"name":"Acme","domains":["acme.com"],"size":5}'

# Update a customer
linear customers update CUSTOMER_ID --name "Acme Corp (Studio)"
linear customers update CUSTOMER_ID --status-id STATUS_ID --size 10

# Delete a customer
linear customers delete CUSTOMER_ID

Customer Needs

# List all needs
linear customers needs list
linear customers needs list --format table

# List needs for a specific customer
linear customers needs list --customer-id CUSTOMER_ID

# Create a need
linear customers needs create --customer-id CID --body "Needs vertical storyboard"
linear customers needs create --customer-id CID --body "Export to PDF" --issue-id ISSUE_ID
linear customers needs create --customer-id CID --body "Critical" --project-id PROJECT_ID --priority 1

# Update a need
linear customers needs update NEED_ID --body "Updated description"
linear customers needs update NEED_ID --issue-id ISSUE_ID

# Delete a need
linear customers needs delete NEED_ID

Upload Files

# Upload a file and get the asset URL
linear upload ./screenshot.png
linear upload ./document.pdf

# Output as markdown (for embedding in descriptions)
linear upload ./image.png --markdown
# Returns: ![image.png](https://linear-uploads.s3.amazonaws.com/...)

# Specify content type
linear upload ./file.dat --content-type application/octet-stream

Users

# List users
linear users list

# Get user details
linear users get USER_ID

Search

# Search issues
linear search "login bug"
linear search "SSO" --team ENG

Teams

# List all teams
linear teams list

# With table format
linear teams list --format table

Open in Browser

# Open an issue
linear open ENG-123

# Open a team
linear open --team ENG

# Open inbox
linear open --inbox

# Open my issues
linear open --my-issues

# Open settings
linear open --settings

User Info

# Show current user
linear me
linear whoami

# With table format
linear me --format table

Schema Introspection (for LLMs)

# List available entities
linear schema

# Get schema for a specific entity
linear schema issues

# Get full schema (all entities)
linear schema --full

# Include usage examples
linear schema issues --include-examples

Raw GraphQL Queries

# Execute any GraphQL query
linear query --gql "query { viewer { id name email } }"

# With variables
linear query --gql "query(\$id: String!) { issue(id: \$id) { title } }" \
  --variables '{"id":"xxx"}'

Output Format

JSON (default)

All commands return structured JSON by default, ideal for LLMs and scripts:

// Success
{
  "success": true,
  "data": { ... }
}

// Success with pagination
{
  "success": true,
  "data": [...],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "abc123"
  }
}

// Error
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Issue ENG-123 not found"
  }
}

Table (human-readable)

Use --format table for colored, human-readable output:

linear issues list --format table
# ID        PRI     TITLE
# ENG-123   High    Fix login bug
# ENG-124   Medium  Add dark mode

Plain (minimal)

Use --format plain for minimal output (IDs/identifiers only):

linear issues list --format plain
# ENG-123    Fix login bug
# ENG-124    Add dark mode

Disabling Colors

Colors are automatically disabled when piping output. You can also disable them manually:

NO_COLOR=1 linear issues list --format table
# or
linear issues list --format table --no-color

For LLM Integration

The CLI is designed to be easily used by LLMs and AI agents:

Single discovery command: Use linear info to get complete documentation in one JSON response
Structured output: All responses are JSON with consistent format
Configurable defaults: Set default team to reduce command complexity
Bulk operations: Update multiple issues efficiently
Error codes: Programmatic error handling via error codes

Example LLM Workflow

# 1. Get complete CLI documentation in one command
linear info

# 2. Or get compact version for limited context
linear info --compact

# 3. Create issues (uses default team if configured)
linear issues create --title "From LLM"

# 4. Bulk update multiple issues
linear issues bulk-update --ids ENG-1,ENG-2,ENG-3 --state-id STATE_ID

Claude Code Integration

# Add CLAUDE.md notes, install the linear-cli skill (~/.claude/skills/linear-cli/SKILL.md),
# and allow-list `Bash(linear:*)` + `Skill(linear-cli)` in ~/.claude/settings.json
linear setup

# Remove all of the above
linear setup --remove

This also runs automatically (with a y/N prompt) after npm install -g linear-cli-agents.

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run in development
./bin/dev.js issues list

# Run tests
pnpm test

Troubleshooting

Authentication Issues

"Not authenticated" error:

# Check current auth status
linear auth status

# Re-authenticate
linear auth login --key lin_api_xxxxx

Using environment variable:

export LINEAR_API_KEY=lin_api_xxxxx
linear auth status  # Should show source: environment

Common Errors

Error Code	Cause	Solution
`NOT_AUTHENTICATED`	No API key configured	Run `linear auth login` or set `LINEAR_API_KEY`
`INVALID_API_KEY`	API key expired or invalid	Generate a new key in Linear settings
`NOT_FOUND`	Resource doesn't exist	Check the issue/team identifier
`RATE_LIMITED`	Too many requests	Wait before retrying

Getting Help

# See all commands
linear --help

# Get help for a specific command
linear issues --help
linear issues create --help

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
bin		bin
scripts		scripts
src		src
.gitignore		.gitignore
.prettierignore		.prettierignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation

linear-cli-agents

Why this Linear CLI

Features

Installation

Quick Start

Authentication

Configuration

Usage

Issues

Projects

Project Milestones

Project Updates

Issue Relations

Labels

Templates

Comments

States

Cycles (Sprints)

Documents

Initiatives

Customers

Customer Needs

Upload Files

Users

Search

Teams

Open in Browser

User Info

Schema Introspection (for LLMs)

Raw GraphQL Queries

Output Format

JSON (default)

Table (human-readable)

Plain (minimal)

Disabling Colors

For LLM Integration

Example LLM Workflow

Claude Code Integration

Development

Troubleshooting

Authentication Issues

Common Errors

Getting Help

Contributing

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages