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

# A state name or ID works too, and mixes with types
linear issue list --state "In Review"
linear issue list --state started --state "In Review"

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 (key, name, or ID)
linear issue list --team TEAM
linear issue list --team "Team Name"

# 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 (key, name, or ID)
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

change labels:

# Add a label, keeping existing labels
linear issue update TEAM-123 --add-label bug

# Remove a label from this issue (does not delete it from the team)
linear issue update TEAM-123 --remove-label sprint-42

# Swap labels atomically in one update
linear issue update TEAM-123 --remove-label sprint-42 --add-label sprint-43

# Replace the entire label set
linear issue update TEAM-123 --label bug --label frontend

clear optional fields (each --clear-* flag conflicts with its set flag):

# Remove the due date, estimate, parent, project, or milestone
linear issue update TEAM-123 --clear-due-date
linear issue update TEAM-123 --clear-estimate --clear-parent
linear issue update TEAM-123 --clear-project --clear-milestone

# Move to another project and detach the milestone in one update
linear issue update TEAM-123 --project "Mobile App" --clear-milestone

# Assignee and cycle have their own clearing flags
linear issue update TEAM-123 --unassign --clear-cycle

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

issue comments

# List comments (threads, newest first); --json keeps the GraphQL connection
linear issue comment list TEAM-123
linear issue comment list TEAM-123 --json

# Add a comment; --body-file is preferred for markdown
linear issue comment add TEAM-123 --body "Reproduced on staging"
linear issue comment add TEAM-123 --body-file notes.md

# Reply to a top-level comment (-p / --parent are aliases of --reply-to)
linear issue comment add TEAM-123 --body "Fixed in #42" --reply-to COMMENT-ID

teams

wherever a command takes a team, pass its key, its name, or its UUID. keys are canonical; an unknown team errors and lists the valid keys.

list teams

linear team list
linear team list --json   # machine-readable, e.g. to map a team name to its key

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
linear team members "Team Name"

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"

update a project

# --description is the short summary; --content is the long-form overview body
linear project update PROJECT-ID --description "Short summary" --content "## Overview"

# Replace the overview body from a markdown file
linear project update PROJECT-ID --content-file overview.md

# Remove the lead, start date, or target date (each conflicts with its set flag)
linear project update PROJECT-ID --clear-lead --clear-start-date --clear-target-date

list projects

linear project list

view project details

linear project view PROJECT-ID
linear project view PROJECT-ID --json

project comments

# A project is a UUID, slug ID, or exact name
linear project comment list "Mobile launch"
linear project comment list PROJECT-ID --json

linear project comment add PROJECT-ID --body "Kickoff is Monday"
linear project comment add PROJECT-ID --body-file update.md --reply-to COMMENT-ID

documents and initiatives

Documents and initiatives take the same comment list and comment add subcommands as issues and projects. A document is a UUID or slug; an initiative is a UUID, slug, or name.

linear document comment list DOC-SLUG          # inline comments show the text they quote
linear document comment list DOC-SLUG --json   # quotedText and parent are in the JSON
linear document comment add DOC-SLUG --body-file review.md
linear document comment add DOC-SLUG --body "Agreed" --reply-to COMMENT-ID

linear initiative comment list "Platform"
linear initiative comment add "Platform" --body "Scope locked for Q3"

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