mirror of
https://github.com/schpet/linear-cli.git
synced 2026-09-14 14:26:50 +08:00
Peter Schilling
5214ca9b80
The reporter asked for a way to detach a label from one issue without
deleting it team-wide, believing --label was additive. It actually
replaces the issue's entire label set (IssueUpdateInput.labelIds), so
the gap was wider than reported: adding one label clobbered the rest.
Rather than only the suggested --remove-label, this maps both
--add-label and --remove-label onto the API's addedLabelIds/
removedLabelIds (one atomic mutation, no read-modify-write). --label
keeps its documented replace semantics for existing scripts, with help
text that now says so. Flag names match gh issue edit, the surface
users and agents reach for first.
A --clear-labels flag was considered (an empty label set is currently
inexpressible in one command) and deliberately deferred: adding a flag
later is backwards compatible, removing one is breaking, and nothing
has asked for clear-all yet.
Invalid combinations error before any network call: --label with
incremental flags, the same resolved label ID in both add and remove,
and --team moves combined with incremental flags (label names resolve
against the destination team, which would make source-team labels
silently unresolvable). Live QA confirmed removing an unattached label
is rejected by Linear's API ("Label <id> is not on issue <id>"), not a
silent no-op — surfaced as-is, consistent with the repo's
explicit-input-errors philosophy.
The reporter's alternative ask (label rename) is deferred: it is
team-wide and would not solve the per-issue detach workflow.
Github-Issue: Fixes #258
Github-Issue-Url: https://github.com/schpet/linear-cli/issues/258
5.4 KiB
5.4 KiB
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
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
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