schpet__linear-cli/docs/usage.md at schpet/project-collection-flags

mirror of https://github.com/schpet/linear-cli.git synced 2026-09-14 14:26:50 +08:00

Files

T

Peter Schilling 10553fe632 Add, remove, and set flags for project teams, labels, and initiatives

project update could only replace a project's teams and labels, and could
not change initiatives at all: project create accepts --initiative, but
after creation the only route was a hand-written mutation. Every
collection field an update command can change should offer the same three
operations, following the pattern issue update already has for labels:
--team/--label/--initiative replace the whole set, --add-* appends,
--remove-* detaches, all repeatable, and a replace flag cannot be combined
with its add/remove flags.

Linear's ProjectUpdateInput only takes a full teamIds/labelIds list, so
add and remove read the project's current connection, following every
page, compute the new set, and send it. Removing something the project
does not have is an error that lists what it does have, rather than a
silent no-op, and removing the last team errors up front because Linear
rejects an empty teamIds. Initiatives have no input field: membership is
an InitiativeToProject join row, so all three initiative flags diff the
desired set against the current rows and run initiativeToProjectDelete
then initiativeToProjectCreate. Deletes go first because a project may
appear only once in an initiative hierarchy, so moving it to a parent or
child initiative is rejected while the old link still exists; that is
also why a UUID-shaped initiative is confirmed to exist before any link
is touched, since the shared resolver passes UUIDs through unchecked.
Those mutations are not transactional, so a failure part-way reports what
was applied, including the already-committed project fields, and what is
still pending, with the remaining flags given by initiative ID because
names are not unique, instead of implying a rollback.

The survey of issue update and initiative update found no other
replace-only collection flag: IssueUpdateInput's releaseIds and
subscriberIds and InitiativeUpdateInput's labelIds are not exposed by
either command.

Claude-Session: https://claude.ai/code/session_01A9qEGri4p2HZMQSuYsBmub

2026-09-05 08:56:36 -07:00

9.0 KiB

Raw Permalink Blame History

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

# Teams, labels, and initiatives are sets. --team, --label, and --initiative
# replace the whole set; --add-*/--remove-* change it incrementally. All are
# repeatable, and a replace flag cannot be combined with its add/remove flags.
linear project update PROJECT-ID --add-team OPS --remove-team APP
linear project update PROJECT-ID --add-label Launch --remove-label Beta
linear project update PROJECT-ID --add-initiative "Q4 Bets"     # ID, slug, or name
linear project update PROJECT-ID --initiative "Q4 Bets" --initiative "Platform"  # exactly these
# Removing a team, label, or initiative the project does not have is an error.

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

9.0 KiB Raw Permalink Blame History