/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` is an alias of `issue mine` and only shows _your_ issues — use `issue query` for anything scoped to other people or a whole team/project.

List my issues

linear issue mine --state started --sort priority

Create an issue

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

Write multi-line markdown to a file and pass `--description-file` (see the markdown section below); `--no-interactive` avoids prompts 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 --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.

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 --confirm         # 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 formatting in the Linear web UI
• Avoids shell escaping issues with newlines and special characters
• Prevents literal `\n` sequences from appearing in markdown
• Makes it easier to work with multi-line content

**Example workflow:**

# Write markdown to a temporary file
cat > /tmp/description.md <<'EOF'
## Summary

- First item
- Second item

## Details

This is a detailed description with proper formatting.
EOF

# Create issue using the file
linear issue create --title "My Issue" --description-file /tmp/description.md

# Or for comments
linear issue comment add ENG-123 --body-file /tmp/comment.md

**Only use inline flags** (`--description`, `--body`) for simple, single-line content.

Linear Markdown Features

Mention people and resources with plain URLs

Linear turns a resource's **plain Linear URL** in Markdown into a linked mention. A literal `@name`, `@[Name](id)`, or a Markdown link such as `[Name](url)` does not c