/linear-cli

name: linear-cli
description: Manage Linear issues from the command line using the linear cli. This skill allows automating linear management.
allowed-tools: Bash(linear:*), Bash(curl:*)

Linear CLI

A CLI to manage Linear issues from the command line, with git and jj integration.

Prerequisites

The `linear` command must be available on PATH. To check:

linear --version

If not installed globally, you can run it without installing via npx:

npx @schpet/linear-cli --version

All subsequent commands can be prefixed with `npx @schpet/linear-cli` in place of `linear`. Otherwise, follow the install instructions at:\ https://github.com/schpet/linear-cli?tab=readme-ov-file#install

Common Tasks

Copy-pasteable recipes for the most frequent flows. Prefer these dedicated commands over `linear api` — reach for the GraphQL fallback only when no dedicated command or flag covers the operation.

Query issues with filters

`issue query` searches across all assignees and supports structured filters that can be combined:

linear issue query --team ENG --state started --json
linear issue query --project "Mobile App" --state backlog --state triage --unassigned
linear issue query --assignee sam --label bug --updated-after 2026-01-01

Note: `linear issue list` (alias `issue mine`) shows _your_ issues by default — use `issue query` for anything scoped to other people or a whole team/project.

List my issues

linear issue list --state started --sort priority

Create an issue

linear issue create --team ENG --title "Fix login redirect" \
  --description-file ./description.md --no-input

Write multi-line markdown to a file and pass `--description-file` (see the markdown section below); `--no-input` makes the command fail instead of prompting for anything missing in scripted use.

Update an issue's state, assignee, or labels

linear issue update ENG-123 --state "In Review" --assignee sam
linear issue update ENG-123 --unassign
linear issue update ENG-123 --delegate linear                # hand to an agent; separate from the assignee
linear issue update ENG-123 --clear-delegate
linear issue update ENG-123 --add-label security             # add, keep existing labels
linear issue update ENG-123 --remove-label sprint-42         # detach; does not delete the label
linear issue update ENG-123 --remove-label sprint-42 --add-label sprint-43  # atomic swap
linear issue update ENG-123 --label infra --label security   # replaces the label set

Create an issue or project from a template

linear template list --type issue --team ENG              # find the template a team expects
linear template view "Bug report"                         # see what it pre-fills (title, fields, body, sub-issues)
linear issue create --team ENG --template "Bug report" --title "Login fails on Safari"
linear project create --name "Q3 launch" --team ENG --template "Kickoff"

Explicit flags override the template's values, `--label` merges with its labels, and `--description` replaces its body (omit it to keep the body). Document templates cannot be applied through the API.

Add a comment

linear issue comment add ENG-123 --body-file ./comment.md

Attach an image or screenshot so it is visible inline

linear issue comment add ENG-123 --attach ./screenshot.png

This uploads the image and embeds it in a comment, where Linear renders it inline. Do not use `linear issue attach` when the image must be visible: that command creates a sidebar link attachment and does not render images inline.

Resolve or reopen comment threads

linear issue comment list ENG-123 --unresolved            # open threads only, with their replies
linear issue comment resolve <COMMENT> <COMMENT>          # resolve threads by their top-level comment IDs
linear issue comment resolve <COMMENT> --with <REPLY>     # record the reply that resolved the thread
linear issue comment unresolve <COMMENT>                  # reopen a thread

Name a thread by its top-level comment's ID; a reply's ID is refused. In `comment list --json`, `resolvedAt` is set only on a resolved thread's top-level comment, and a reply carries its thread's state in `parent.resolvedAt`. The IDs of open threads are `jq -r '.[] | select(.parent == null and .resolvedAt == null) | .id'`.

View an issue / get its URL

linear issue view ENG-123          # details incl. comments
linear issue view ENG-123 --json   # structured output
linear issue url ENG-123           # print just the URL

Close, delete, or archive an issue

linear issue update ENG-123 --state Done       # or Canceled; Linear auto-archives closed issues later
linear issue delete ENG-123                    # trash; restorable in Linear for 30 days
linear issue archive ENG-123 --yes             # rarely appropriate, see below

Prefer closing or deleting over archiving. Linear's docs say "archiving happens automatically with no option to manually archive items" (https://linear.app/docs/delete-archive-issues): closed issues are auto-archived after the team's configured period, and Linear removed manual archiving from its app because people used it as a trash can. `issue archive` calls the `issueArchive` mutation directly, bypassing auto-archive's checks for open parents, sub-issues, cycles, and projects, and archived issues vanish from `issue list`, `issue query`, and search unless `--include-archived` is passed. Only archive when the user explicitly asks for it.

Best Practices for Markdown Content

When working with issue descriptions or comment bodies that contain markdown, **always prefer using file-based flags** instead of passing content as command-line arguments:

• Use `--description-file` for `issue create` and `issue update` commands
• Use `--body-file` for `comment add` and `comment update` commands

**Why use file-based flags:**

• Ensures proper format