linear-cli

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

CLAUDE.md

Audit 0.4.1 · source sha b002c4677a31 · 20 Oct 2026Report an issue or request a re-scan

• Publisherschpet GitHub userOwner of the repository this skill is read from
• Source folderschpet/linear-cli/skills/linear-cliThe exact folder we audited
• LicenceISCAs the repository states it
• Commit pinned for this verdictb002c4677a31A new audit runs when the source changes
• Repository statusNot archivedLast push 12 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Manage Linear issues from the command line using the linear cli. This skill allows automating linear management.

---
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:

```bash
linear --version
```

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

```bash
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:

```bash
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

```bash
linear issue list --state started --sort priority
```

### Create an issue

```bash
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

```bash
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

```bash
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

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

### Attach an image or screenshot so it is visible inline

```bash
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

```bash
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

```bash
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

```bash
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

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-20
   ✓SAFE B 89 / 100

   first audit · source b002c4677a31

Questions about linear-cli

• github.com/schpet/linear-cli/tree/main/skills/linear-cli — the audited source at commit b002c4677a31 and every finding aboveObserved · 20 Oct 2026

Spotted something wrong? Report a correction · Methodology