schpet__linear-cli/docs/usage.md

linear cli

usage

linear cli provides commands to manage linear issues, teams, and projects from the command line.

repo configuration

first, configure the cli with your linear api token:

linear config

this will interactively generate a .linear.toml configuration file in the repo.

issues

list issues

list your issues (shows unstarted issues by default):

linear issue list

list issues with different states:

# List started issues
linear issue list --state started

# List all issues regardless of state  
linear issue list --all-states

# List multiple states
linear issue list --state unstarted --state started

filter by assignee:

# List issues assigned to you
linear issue list --assignee self

# List issues assigned to specific user
linear issue list --assignee username

# List all unassigned issues
linear issue list --unassigned

# List issues for all assignees
linear issue list --all-assignees

other options:

# List issues for specific team
linear issue list --team TEAM

# Sort by priority instead of manual order
linear issue list --sort priority

# Open in web browser
linear issue list --web

# Open in Linear app
linear issue list --app

view issue details

view the current issue (based on git branch):

linear issue view

view a specific issue:

linear issue view TEAM-123

view options:

# Open in web browser
linear issue view TEAM-123 --web

# Open in Linear app  
linear issue view TEAM-123 --app

# Exclude comments from output
linear issue view TEAM-123 --no-comments

start working on an issue

start the next available issue:

linear issue start

start a specific issue:

linear issue start TEAM-123

this will move the issue to "in progress" and create a git branch.

create an issue

create an issue interactively:

linear issue create

create with specific options:

# Create with title and description
linear issue create --title "Fix bug" --description "Description here"

# Create and assign to yourself
linear issue create --assignee self

# Create with priority (1-4, where 1 is highest)
linear issue create --priority 1

# Create with estimate points
linear issue create --estimate 3

# Create with labels
linear issue create --label bug --label frontend

# Create for specific team
linear issue create --team TEAM

# Create and start working on it
linear issue create --start

update an issue

update the current issue:

linear issue update

update a specific issue:

linear issue update TEAM-123

other issue commands

get issue id from current git branch:

linear issue id

get issue title:

linear issue title TEAM-123

get issue url:

linear issue url TEAM-123

create a github pull request:

linear issue pull-request
linear issue pr  # Short alias

delete an issue:

linear issue delete TEAM-123

teams

list teams

linear team list

get team id

get team id derived from repository name:

linear team id

team members

list members of your default team:

linear team members

list members of a specific team:

linear team members TEAM

create a team

linear team create

configure github autolinks

set up github repository autolinks for linear issues:

linear team autolinks

projects

create a project

# Create with a short description and long-form overview markdown
linear project create --name "API v2" --team ENG --description "Short summary" --content "## Overview"

# Read the project overview body from a markdown file
linear project create --name "API v2" --team ENG --content-file overview.md

# Create with priority, labels, members, icon, and color
linear project create --name "Mobile launch" --team APP --priority high --label Launch --member jane@example.com --icon rocket --color "#5E6AD2"

list projects

linear project list

view project details

linear project view PROJECT-ID

shell completions

generate shell completions for better command-line experience:

# For bash
source <(linear completions bash)

# For zsh  
source <(linear completions zsh)

# For fish
linear completions fish | source

add the appropriate line to your shell's configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish).

global options

most commands support these options:

• --no-pager - disable automatic paging for long output
• --no-color - disable colored output
• --help - show help for the command

examples

common workflows:

# Start working on the next issue
linear issue start

# View current issue details
linear issue view

# Create and start a new bug fix
linear issue create --title "Fix login error" --label bug --start

# List high priority issues
linear issue list --sort priority

# Create a pull request for current issue
linear issue pr