Linear

A CLI to manage Linear issues from the command line, with git and jj integration.

Prerequisites

The linear command must be available on PATH. To check:

linear --version

If not installed:

• Homebrew: brew install schpet/tap/linear
• Deno: deno install -A --reload -f -g -n linear jsr:@schpet/linear-cli
• Binaries: https://github.com/schpet/linear-cli/releases/latest

Setup

1. Create an API key at https://linear.app/settings/account/security
2. Authenticate: linear auth login
3. Configure your project: cd my-project-repo && linear config

Available Commands

linear auth               # Manage Linear authentication
linear issue              # Manage Linear issues
linear team               # Manage Linear teams
linear project            # Manage Linear projects
linear project-update     # Manage project status updates
linear milestone          # Manage Linear project milestones
linear initiative         # Manage Linear initiatives
linear initiative-update  # Manage initiative status updates
linear label              # Manage Linear issue labels
linear document           # Manage Linear documents
linear config             # Interactively generate .linear.toml configuration
linear schema             # Print the GraphQL schema to stdout
linear api                # Make a raw GraphQL API request

Common Workflows

List and view issues

# List your unstarted issues
linear issue list

# List issues in a specific state
linear issue list -s started
linear issue list -s completed

# List all assignees' issues
linear issue list -A

# View the current branch's issue
linear issue view

# View a specific issue
linear issue view ABC-123

Create and manage issues

# Create an issue interactively
linear issue create

# Create non-interactively
linear issue create -t "Fix login bug" -d "Users can't log in with SSO" -s "In Progress" -a self --priority 1

# Update an issue
linear issue update ABC-123 -s "Done" -t "Updated title"

# Add a comment
linear issue comment add ABC-123 -b "This is fixed in the latest build"

# Delete an issue
linear issue delete ABC-123 -y

Start working on an issue

# Pick an issue interactively, creates a git branch and marks it as started
linear issue start

# Start a specific issue
linear issue start ABC-123

# Create a PR with issue details pre-filled
linear issue pr

Projects and milestones

# List projects
linear project list

# Create a project
linear project create -n "Q1 Launch" -t ENG -s started --target-date 2026-03-31

# List milestones for a project
linear milestone list --project <projectId>

Documents

# List documents
linear document list

# Create a document from a file
linear document create --title "Design Spec" --content-file ./spec.md --project <projectId>

# View a document
linear document view <slug>

Teams

# List teams
linear team list

# List team members
linear team members

Discovering Options

Run --help on any command for flags and options:

linear --help
linear issue --help
linear issue list --help
linear issue create --help

Using the Linear GraphQL API Directly

Prefer the CLI for all supported operations. The api command is a fallback for queries not covered by the CLI.

Check the schema

linear schema -o "${TMPDIR:-/tmp}/linear-schema.graphql"
grep -i "cycle" "${TMPDIR:-/tmp}/linear-schema.graphql"
grep -A 30 "^type Issue " "${TMPDIR:-/tmp}/linear-schema.graphql"

Make a GraphQL request

# Simple query
linear api '{ viewer { id name email } }'

# With variables
linear api 'query($teamId: String!) { team(id: $teamId) { name } }' --variable teamId=abc123

# Complex filter via JSON
linear api 'query($filter: IssueFilter!) { issues(filter: $filter) { nodes { title } } }' \
  --variables-json '{"filter": {"state": {"name": {"eq": "In Progress"}}}}'

# Pipe to jq
linear api '{ issues(first: 5) { nodes { identifier title } } }' | jq '.data.issues.nodes[].title'

Using curl directly

curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $(linear auth token)" \
  -d '{"query": "{ viewer { id } }"}'

Reference Documentation

For detailed subcommand documentation with all flags and options:

• issue - Manage Linear issues (list, create, update, start, view, comment, PR, delete)
• team - Manage Linear teams (list, create, delete, members, autolinks)
• project - Manage Linear projects (list, view, create)
• document - Manage Linear documents (list, view, create, update, delete)
• api - Make raw GraphQL API requests

Configuration

The CLI supports environment variables or a .linear.toml config file:

Option	Env Var	TOML Key	Example
Team ID	LINEAR_TEAM_ID	team_id	"ENG"
Workspace	LINEAR_WORKSPACE	workspace	"mycompany"
Issue sort	LINEAR_ISSUE_SORT	issue_sort	"priority" or "manual"
VCS	LINEAR_VCS	vcs	"git" or "jj"

Config file locations (checked in order):

1. ./linear.toml or ./.linear.toml (current directory)
2. <repo-root>/linear.toml or <repo-root>/.linear.toml
3. <repo-root>/.config/linear.toml
4. ~/.config/linear/linear.toml