mirror of
https://github.com/schpet/linear-cli.git
synced 2026-09-14 14:26:50 +08:00
Peter Schilling
d341afdbd5
issue update could set a due date, estimate, parent, project, or milestone but never remove one, and project update had the same gap for lead, start date, and target date. Only --unassign and --clear-cycle existed. cliffy rejects an empty string as a missing option value, so --due-date "" is not a workaround, and an agent driving the CLI had to fall back to a hand-written projectUpdate/issueUpdate mutation through linear api. Add one boolean clear flag per field, each placed after its set flag and modelled on --clear-cycle: it conflicts with its set flag (a ValidationError before any request, with a null check so --estimate 0 counts as a value), skips the lookup the set flag would run, and puts an explicit null in the mutation input. --clear-project also rejects --milestone, because a milestone belongs to the project being removed; --project with --clear-milestone is allowed so a move can detach a stale milestone in one update. The project update guard treats each clear flag as an update and its suggestion lists them. Linear honours null for every field, including startDate, verified on a scratch project and issue. Claude-Session: https://claude.ai/code/session_01A9qEGri4p2HZMQSuYsBmub
405 lines
8.4 KiB
Markdown
405 lines
8.4 KiB
Markdown
## 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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
linear issue list
|
|
```
|
|
|
|
list issues with different states:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```bash
|
|
linear issue view
|
|
```
|
|
|
|
view a specific issue:
|
|
|
|
```bash
|
|
linear issue view TEAM-123
|
|
```
|
|
|
|
view options:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
linear issue start
|
|
```
|
|
|
|
start a specific issue:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
linear issue create
|
|
```
|
|
|
|
create with specific options:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
linear issue update
|
|
```
|
|
|
|
update a specific issue:
|
|
|
|
```bash
|
|
linear issue update TEAM-123
|
|
```
|
|
|
|
change labels:
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
linear issue id
|
|
```
|
|
|
|
get issue title:
|
|
|
|
```bash
|
|
linear issue title TEAM-123
|
|
```
|
|
|
|
get issue url:
|
|
|
|
```bash
|
|
linear issue url TEAM-123
|
|
```
|
|
|
|
create a github pull request:
|
|
|
|
```bash
|
|
linear issue pull-request
|
|
linear issue pr # Short alias
|
|
```
|
|
|
|
delete an issue:
|
|
|
|
```bash
|
|
linear issue delete TEAM-123
|
|
```
|
|
|
|
#### issue comments
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
linear team id
|
|
```
|
|
|
|
#### team members
|
|
|
|
list members of your default team:
|
|
|
|
```bash
|
|
linear team members
|
|
```
|
|
|
|
list members of a specific team:
|
|
|
|
```bash
|
|
linear team members TEAM
|
|
linear team members "Team Name"
|
|
```
|
|
|
|
#### create a team
|
|
|
|
```bash
|
|
linear team create
|
|
```
|
|
|
|
#### configure github autolinks
|
|
|
|
set up github repository autolinks for linear issues:
|
|
|
|
```bash
|
|
linear team autolinks
|
|
```
|
|
|
|
### projects
|
|
|
|
#### create a project
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# --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
|
|
|
|
```bash
|
|
linear project list
|
|
```
|
|
|
|
#### view project details
|
|
|
|
```bash
|
|
linear project view PROJECT-ID
|
|
linear project view PROJECT-ID --json
|
|
```
|
|
|
|
#### project comments
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
```
|