Skip to content
Back to search

linear-cli

marketplace for linear-cli claude code plugin

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/schpet/linear-cli with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/schpet/linear-cli'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/schpet--linear-cli/badge.svg)](/listings/schpet--linear-cli)

HTML

<a href="/listings/schpet--linear-cli"><img src="/api/listings/schpet--linear-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

homebrew

brew install schpet/tap/linear

npm / bun / pnpm

install as a dev dependency to pin a version in your project:

npm install -D @schpet/linear-cli
# or
bun add -D @schpet/linear-cli
# or
pnpm add -D @schpet/linear-cli

then run via your package manager:

npx linear issue list
bunx linear issue list

> **note:** this package ships pre-built binaries

package on npm: [@schpet/linear-cli](https://www.npmjs.com/package/@schpet/linear-cli)

shell installer

for macOS and Linux:

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/schpet/linear-cli/releases/latest/download/linear-installer.sh | sh

binaries

https://github.com/schpet/linear-cli/releases/latest

from source

with a [rust toolchain](https://rustup.rs) installed:

cargo install --locked --git https://github.com/schpet/linear-cli linear

upgrading from 2.x? see [upgrading from 2.x](CHANGELOG.md#upgrading-from-2x) in the changelog.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 495 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # linear cli
  2. > [!NOTE]
  3. > This README is for the upcoming 4.0 release. For stable instructions, see the [latest stable release (v3.1.0)](https://github.com/schpet/linear-cli/blob/v3.1.0/README.md).
  4. a cli to list, start and create issues in the [linear](https://linear.app/) issue tracker. git and [jj](https://www.jj-vcs.dev/) aware to keep you in the right views in linear. allows jumping to the web or the linear desktop app similar to `gh`.
  5. **works great with AI agents** — the CLI includes a [skill](#skills) that lets agents create issues, update status, and manage your Linear workflow alongside your code. install it with `linear skill setup`.
  6. here's how it works:
  7. ```bash
  8. linear config # setup your repo, it writes a config file
  9. linear issue mine # list unstarted issues assigned to you
  10. linear issue query --all-teams # query issues across all teams
  11. linear issue query --search "login bug" # search issues in your configured team
  12. linear issue start ABC-123 # move an issue to its team's first started status
  13. linear issue git start # choose an issue, create its branch, and start it
  14. linear issue view ABC-123 # see an issue as markdown
  15. linear issue gh pr ABC-123 # makes a PR with title/body preset, using gh cli
  16. linear issue create # create a new issue
  17. ```
  18. it aims to be a complement to the web and desktop apps that lets you stay on the command line in an interactive or scripted way.
  19. ## screencast demos
  20. <details>
  21. <summary><code>linear issue create -i</code></summary>
  22. <img width="600" src="docs/cast-issue-create.svg?1" alt="screencast showing the linear issue create -i command, interactively adding issue details">
  23. </details>
  24. ## install
  25. ### homebrew
  26. ```
  27. brew install schpet/tap/linear
  28. ```
  29. ### npm / bun / pnpm
  30. install as a dev dependency to pin a version in your project:
  31. ```bash
  32. npm install -D @schpet/linear-cli
  33. # or
  34. bun add -D @schpet/linear-cli
  35. # or
  36. pnpm add -D @schpet/linear-cli
  37. ```
  38. then run via your package manager:
  39. ```bash
  40. npx linear issue mine
  41. bunx linear issue mine
  42. ```
  43. > **note:** this package ships pre-built binaries
  44. package on npm: [@schpet/linear-cli](https://www.npmjs.com/package/@schpet/linear-cli)
  45. ### shell installer
  46. for macOS and Linux:
  47. ```bash
  48. curl --proto '=https' --tlsv1.2 -LsSf https://github.com/schpet/linear-cli/releases/latest/download/linear-installer.sh | sh
  49. ```
  50. ### binaries
  51. https://github.com/schpet/linear-cli/releases/latest
  52. ### from source
  53. with a [rust toolchain](https://rustup.rs) installed:
  54. ```bash
  55. cargo install --locked --git https://github.com/schpet/linear-cli linear
  56. ```
  57. ### nix
  58. run it without installing, with [flakes](https://nix.dev/concepts/flakes) enabled:
  59. ```bash
  60. nix run github:schpet/linear-cli -- --version
  61. ```
  62. or install it into your profile:
  63. ```bash
  64. nix profile install github:schpet/linear-cli
  65. ```
  66. the flake builds from source on linux and apple silicon macOS. as a flake input it provides `packages.<system>.linear` and `overlays.default`, which adds `pkgs.linear`.
  67. upgrading from 2.x? see [upgrading from 2.x](CHANGELOG.md#upgrading-from-2x) in the changelog.
  68. ## setup
  69. 1. create an API key at [linear.app/settings/account/security](https://linear.app/settings/account/security)[^1]
  70. 2. authenticate with the CLI:
  71. ```sh
  72. linear auth login
  73. ```
  74. 3. configure your project:
  75. ```sh
  76. cd my-project-repo
  77. linear config
  78. ```
  79. see [docs/authentication.md](docs/authentication.md) for multi-workspace support and other authentication options.
  80. the CLI works with both git and jj version control systems:
  81. - **git**: `linear issue git start ABC-123` creates the branch Linear suggests for the issue and starts the issue. branch names that include the issue ID let [Linear's GitHub integration](https://linear.app/docs/github#branch-format) link your pull requests, and `@git` reads the issue back from the current branch's name (`linear issue view @git`).
  82. - **jj**: `linear issue jj start ABC-123` starts a change (or reuses an empty, undescribed one) described with the issue title and `Linear-issue` trailers, or add them yourself with `jj describe -m "$(linear issue describe ABC-123)"`. `@jj` reads back every issue the trailers in `trunk()..@` name (`linear issue view @jj`). to open a pull request, push a bookmark with jj first and name it with `--head` (see below)
  83. each command names its tool (`issue git …`, `issue jj …`, `issue gh …`), and nothing is chosen by a setting: `linear issue gh pr` builds the title and body and runs `gh pr create`; linear itself never creates, moves or pushes a branch or bookmark. the `vcs` setting (`LINEAR_VCS`) was removed in 4.0; old values are ignored quietly and are safe to leave in place. `pr_template` (`LINEAR_PR_TEMPLATE`), the old starting-body file setting, was removed too: pass description text with `linear issue gh pr <ISSUE> --body-file <FILE>`. An old setting is reported only when creating a pull request or running `linear config check`; it is safe to keep. use new [MiniJinja preferences](docs/templating.md) to configure generated guide, commit and PR layouts
  84. ## commands
  85. ### issue commands
  86. every command takes the issue it acts on: an ID like `ENG-123`, an issue URL, a bare number in the configured team, or a reference that reads it from your repository. `@git` is the first issue ID in the current git branch's name; `@jj` is every issue named by the `Linear-issue` trailers of the changes in `trunk()..@`. the cli reads the repository only when you pass one of these, and says on stderr which issues it read before anything is sent. a command that acts on one issue refuses a reference that names several; `issue view` and the pull request commands take them all. in PowerShell, quote them: `'@git'`.
  87. ```bash
  88. linear issue view ABC-123 # view issue details in terminal
  89. linear issue view 123
  90. linear issue view ABC-123 ABC-124 # multiple issues, in argument order
  91. linear issue view ABC-123 ABC-124 --json # an array; one issue returns an object
  92. linear issue view ABC-123 -w # open issue in web browser
  93. linear issue view ABC-123 -a # open issue in Linear.app
  94. linear issue title ABC-123 # prints just the issue title
  95. linear issue url ABC-123 # prints the Linear.app URL for the issue
  96. linear issue gh pr ABC-123 # creates a GitHub PR with issue details via `gh pr create`
  97. linear issue gh pr @git # the same, for the issue in the current git branch's name
  98. linear issue gh pr ABC-123 ABC-124 --title "Fix login" # one PR for several issues: "Fixes ABC-123 and ABC-124" and their URLs in the body
  99. linear issue gh pr ABC-123 -F body.md # your description, then the issue links
  100. linear issue gh pr ABC-123 -- --draft --base main # everything after -- goes to `gh pr create`
  101. linear issue gh pr @jj --title "Fix login" -- --head my-topic # one PR for every issue the trailers in trunk()..@ name, from a pushed branch
  102. linear issue id @jj # prints the issues @jj reads, one per line
  103. linear issue mine # list your issues in a table view (supports -s/--state and --sort)
  104. linear issue mine --project "My Project" --milestone "Phase 1" # filter by milestone
  105. linear issue mine -w # open your issues in the web browser
  106. linear issue mine -a # open your issues in Linear.app
  107. linear issue query --search "login bug" # search issues by text in your configured team
  108. linear issue query --search "oauth timeout" --team ENG --json # structured search output for agents
  109. linear issue query --team "Engineering" --state "In Review" --json # teams by key, name, or ID; states by type, name, or ID
  110. linear issue query --all-teams --json --limit all # export all issues as JSON
  111. linear issue start ENG-123 # move the issue to its team's first started status; touches nothing in your repo
  112. linear issue complete ENG-123 # move the issue to its team's completed status
  113. linear issue cancel ENG-123 # move the issue to its team's canceled status
  114. linear issue git start ENG-123 # create/switch to the issue's git branch, then start it (--branch, --from-ref); prints what it did
  115. linear issue jj start ENG-123 # start a jj change described with the issue, then start it; prints the change ID, description and trailers it wrote
  116. linear issue create # create a new issue, asking for the title
  117. linear issue create -i # create a new issue, asking for every field
  118. linear issue create -t "title" -d "description" # create with flags
  119. linear issue create --project "My Project" --milestone "Phase 1" # create with milestone
  120. linear issue create --template "Bug report" -t "Login fails" # create from a template (see template commands)
  121. linear issue update ENG-123 -s started # change only the fields you pass
  122. linear issue update ENG-123 --milestone "Phase 2" # set milestone on existing issue
  123. linear issue update ENG-123 --clear-due-date --clear-parent # remove values (also --clear-estimate, --clear-project, --clear-milestone, --clear-cycle, --unassign)
  124. linear issue archive ENG-123 --yes # archive an issue (Linear normally auto-archives closed issues; see docs/usage.md)
  125. linear issue archive --yes --bulk ENG-123 ENG-124 # archive several issues
  126. linear issue delete ENG-123 # delete an issue
  127. linear issue comment list ENG-123 # list comments on an issue
  128. linear issue comment add ENG-123 # add a comment to an issue
  129. linear issue comment add ENG-123 --reply-to <id> # reply to a comment (-p / --parent are aliases)
  130. linear issue comment list ENG-123 --json # comments as JSON, with quotedText and parent for inline comments and replies
  131. linear issue comment update <id> # update a comment
  132. ```
  133. #### pull requests
  134. `issue gh pr` fetches the issues, builds the title and body, and runs `gh pr create`. before `--` is what linear builds; everything after `--` goes to gh unchanged, after linear's `--title` and `--body`, so a flag there wins (a `--title` or `--body` after `--` replaces linear's, issue links included; gh's own `--template` cannot be used, since linear always passes a body). the shipped title is `ABC-123 <issue title>` for one issue, and several issues require `--title`. [template preferences](docs/templating.md) can generate a multiissue title and customize the complete body; an explicit `--title` always wins. `--body` or `--body-file` supplies description data to the body template, whose shipped layout appends `Fixes ABC-123` (or `References …` with `--references`) and each issue URL. linear itself never pushes: without `-- --head`, gh opens the pull request from the current git branch and, in a terminal, may offer to push it (or fork the repository) first; `-- --head <branch>` names a branch that is already pushed and turns that off. from jj, push the bookmark first, then pass it with `-- --head`. `@-` assumes `@` is an empty scratch change on top of the finished one; right after `issue jj start`, `@` is the described change, so run `jj new` first (or push `@`):
  135. ```bash
  136. branch=$(linear issue view ABC-123 --json | jq -r .branchName)
  137. jj git push --named "$branch=@-" # first push: creates the bookmark
  138. linear issue gh pr ABC-123 -- --head "$branch" # add --repo OWNER/REPO after -- in a non-colocated jj repository
  139. ```
  140. later, `jj git push --bookmark "$branch"` updates the pull request. the bookmark follows a rewritten change on its own; after adding new commits on top, first run `jj bookmark move "$branch" --to @-`.
  141. #### attaching files
  142. attach files to an issue or comment. uploads are **private** by default (readable only by workspace members), matching the Linear web app.
  143. ```bash
  144. linear issue attach ENG-123 ./screenshot.png # attach a file to an issue
  145. linear issue attach ENG-123 ./doc.pdf -t "Spec" # custom attachment title
  146. linear issue attach ENG-123 ./img.png -c "see this" # add a linked comment
  147. linear issue comment add ENG-123 -a ./screenshot.png # attach a file to a comment
  148. linear issue comment add ENG-123 -a ./a.png -a ./b.png # attach multiple files
  149. ```
  150. by default attachments are private. pass `--public` to upload raster images (png/jpeg/gif/webp/bmp/tiff) to a public `public.linear.app` URL readable by **anyone, unauthenticated** — useful for sharing outside the workspace, but a warning is printed since it bypasses workspace access controls. non-image files cannot be made public.
  151. ```bash
  152. linear issue attach ENG-123 ./screenshot.png --public # public image URL
  153. linear issue comment add ENG-123 -a ./screenshot.png --public # public image URL
  154. ```
  155. ### team commands
  156. ```bash
  157. linear team list # list teams
  158. linear team list --json # as JSON, e.g. to map a team name to its key or id in scripts
  159. linear team id # print the configured team key (e.g. for scripts)
  160. linear team members # list team members
  161. linear team members --all --json # include inactive members, as JSON
  162. linear team create # create a new team
  163. linear team autolinks # configure GitHub repository autolinks for Linear issues
  164. ```
  165. ### user commands
  166. ```bash
  167. linear user list # list everyone in the workspace
  168. linear user list --all # include deactivated members
  169. linear user list --json # machine-readable output
  170. ```
  171. ### project commands
  172. ```bash
  173. linear project list # list projects
  174. linear project view https://linear.app/acme/project/mobile-launch-272f50ef9250 # paste a URL from Linear
  175. linear project view # pick from a searchable list of projects
  176. linear project view <projectId> # overview, milestones, resources, documents, related projects
  177. linear project view "Mobile launch" # a UUID, slug ID, or exact name all work
  178. linear project view <projectId> --json # project details as JSON
  179. linear project create --name "API v2" --team ENG --content-file overview.md
  180. linear project create --name "Mobile launch" --team APP --priority high --label Launch --member jane@example.com
  181. linear project create --name "Q3 launch" --team APP --template "Kickoff" # create from a project template
  182. linear project update <projectId> --content-file overview.md # replace the project's overview body
  183. linear project update <projectId> --clear-lead --clear-target-date # remove values (also --clear-start-date)
  184. linear project update <projectId> --add-team OPS --remove-label Launch --add-initiative "Q4 Bets" # change teams, labels, initiatives incrementally
  185. linear project update <projectId> --team ENG --team OPS # replace the whole team set (--label and --initiative replace likewise)
  186. linear project comment list <project> # list the project's discussion thread (UUID, slug, or name)
  187. linear project comment add <project> --body "Kickoff Monday" # comment on a project
  188. linear project comment add <project> --body "+1" --reply-to <commentId> # reply in a thread
  189. ```
  190. ### initiative commands
  191. ```bash
  192. linear initiative list # list initiatives
  193. linear initiative view <initiative> # view an initiative (UUID, slug, or name)
  194. linear initiative comment list <initiative> # list the initiative's discussion thread
  195. linear initiative comment add <initiative> --body-file note.md # comment on an initiative
  196. linear initiative comment add <initiative> --body "+1" --reply-to <commentId> # reply in a thread
  197. ```
  198. ### cycle commands
  199. ```bash
  200. linear cycle list --team ENG # list a team's cycles (--team takes a key, name, or ID)
  201. linear cycle list --team ENG --json # as JSON
  202. linear cycle view 12 --team ENG # view a cycle by number or name
  203. linear cycle view 12 --team ENG --json # cycle details and its issues, as JSON
  204. ```
  205. ### milestone commands
  206. ```bash
  207. linear milestone list --project <projectId> # list milestones for a project
  208. linear m list --project <projectId> # list milestones (alias)
  209. linear milestone list --project <projectId> --json # as JSON
  210. linear milestone view <milestoneId> # view milestone details
  211. linear m view <milestoneId> # view milestone (alias)
  212. linear milestone view <milestoneId> --all # list every issue, not just the first 10
  213. linear milestone view <milestoneId> --json # milestone with every issue, as JSON
  214. linear milestone create --project <projectId> --name "Q1 Goals" --target-date "2026-03-31" # create a milestone
  215. linear m create --project <projectId> # create a milestone, asking for its name
  216. linear milestone update <milestoneId> --name "New Name" # update milestone name
  217. linear m update <milestoneId> --target-date "2026-04-15" # update target date
  218. linear milestone delete <milestoneId> # delete a milestone
  219. linear m delete <milestoneId> --yes # delete without confirmation
  220. ```
  221. ### document commands
  222. manage Linear documents from the command line. every document is attached to exactly one target: a project, issue, initiative, team, cycle, or release (Linear's API requires one).
  223. ```bash
  224. # list documents
  225. linear document list # list all accessible documents
  226. linear docs list # alias for document
  227. linear document list --project <project> # filter by project (UUID, slug ID, or name)
  228. linear document list --issue TC-123 # filter by issue (or @git, @jj)
  229. linear document list --team ENG # filter by team
  230. linear document list --initiative <initiative> # filter by initiative
  231. linear document list --team ENG --cycle active # filter by cycle (team scopes the lookup)
  232. linear document list --release <release> # filter by release (UUID, name, or version)
  233. linear document list --json # output as JSON
  234. # view a document
  235. linear document view <slug> # view document rendered in terminal
  236. linear document view <slug> --raw # output raw markdown (for piping)
  237. linear document view <slug> --web # open in browser
  238. linear document view <slug> --json # output as JSON, including document comments
  239. # comment on a document
  240. linear document comment list <slug> # list comments; inline comments show the text they quote
  241. linear document comment list <slug> --json # comments as JSON (quotedText, parent, ...)
  242. linear document comment add <slug> --body "Looks good" # add a top-level comment
  243. linear document comment add <slug> --body-file note.md --reply-to <commentId> # reply in a thread
  244. # create a document (exactly one attachment target is required)
  245. linear document create --title "Doc" --project <project> # attach to project
  246. linear document create --title "Notes" --issue TC-123 # attach to issue
  247. linear document create --title "Handbook" --team ENG # attach to team
  248. linear document create --title "Brief" --initiative <initiative> # attach to initiative
  249. linear document create --title "Sprint" --team ENG --cycle next # attach to cycle
  250. linear document create --title "Notes" --release 2026.8 # attach to release
  251. linear document create --title "Spec" --content-file ./spec.md --project <project> # content from file
  252. cat spec.md | linear document create --title "Spec" --project <project> # content from stdin
  253. # update a document
  254. linear document update <slug> --title "New Title" # update title
  255. linear document update <slug> --content-file ./updated.md # update content
  256. linear document update <slug> --edit # open in $EDITOR
  257. linear document update <slug> --team ENG # re-point attachment (replaces current)
  258. linear document update <slug> --content-file ./updated.md --force # bypass comment-anchor guard
  259. # delete a document
  260. linear document delete <slug> # soft delete (move to trash)
  261. linear document delete --bulk <slug1> <slug2> # bulk delete
  262. ```
  263. content updates are refused by default when a document has active inline Linear comments, because replacing markdown can detach or hide those anchors. top-level document comments do not block updates. review the inline comment first, then rerun with `--force` if you intentionally want to replace the content anyway.
  264. ### template commands
  265. ```bash
  266. linear template list # every issue, project, and document template in the workspace
  267. linear template list --type issue --team ENG # ENG's issue templates plus workspace-level ones
  268. linear template list --json # the raw template objects (templateData is a JSON-encoded string)
  269. linear template view "Bug report" # what the template pre-fills: title, priority, labels, body, sub-issues, ...
  270. linear template view <template-id> --json # raw GraphQL object; `jq '.templateData | fromjson'` decodes the data
  271. # apply a template on create (name or ID). Linear fills the template in server-side.
  272. linear issue create --team ENG --template "Bug report" # the template supplies the title
  273. linear issue create --team ENG --template "Bug report" -t "Login fails" -l security # flags override, labels merge
  274. linear project create --name "Q3 launch" --team APP --template "Kickoff"
  275. ```
  276. `--template` takes the place of the team's default template, so it never needs `--no-use-default-template` (passing both is fine). Anything you pass explicitly overrides the template's value; `--label` merges with the template's labels; `--description` replaces the template body, so leave it out to keep the body. Document templates can be listed and viewed, but Linear's API has no way to apply one when creating a document.
  277. ### other commands
  278. ```bash
  279. linear --help # show all commands
  280. linear --version # show version
  281. linear config # setup the project
  282. linear completions # generate shell completions
  283. ```
  284. ## configuration options
  285. scalar options support environment variables or a `.linear.toml` config file. environment variables take precedence over config file values. [template preferences](docs/templating.md) use `[templates]` and `[template-aliases]`, with separate per-name layering and no `LINEAR_*` equivalent.
  286. | option | env var | toml key | example | description |
  287. | --------------- | --------------------------------- | -------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------ |
  288. | Team ID | `LINEAR_TEAM_ID` | `team_id` | `"ENG"` | default team for operations |
  289. | Workspace | `LINEAR_WORKSPACE` | `workspace` | `"mycompany"` | workspace slug for web/app URLs |
  290. | Issue sort | `LINEAR_ISSUE_SORT` | `issue_sort` | `"priority"` or `"manual"` | how to sort issue lists |
  291. | Ask project | `LINEAR_ISSUE_CREATE_ASK_PROJECT` | `issue_create_ask_project` | `true` or `false` | ask for a project during interactive `issue create` |
  292. | Assign self | `LINEAR_ISSUE_CREATE_ASSIGN_SELF` | `issue_create_assign_self` | `"always"`, `"auto"`, or `"never"` | control default self-assignment during issue creation |
  293. | Download images | `LINEAR_DOWNLOAD_IMAGES` | `download_images` | `true` or `false` | download images when viewing issues |
  294. | Inline images | `LINEAR_INLINE_IMAGES` | `inline_images` | `true` or `false` | draw downloaded PNG images in kitty, Ghostty and Rex (default: true; see below) |
  295. in kitty, Ghostty and Rex, `issue view` and `document view` draw the PNG images they download right under their links, using the kitty graphics protocol's Unicode placeholders so they still show inside the pager. other image formats, other terminals, terminals inside tmux or screen, piped output and `NO_COLOR` keep the plain link. images show through `less` (the default pager); another `PAGER` may not show them. set `inline_images = false` or `LINEAR_INLINE_IMAGES=false` to turn them off, or pass `--no-download` for one view.
  296. scalar settings are read from a project file and a global file. each option takes the first value it finds in this order:
  297. 1. a command-line flag, where the command has one
  298. 2. an environment variable, from the shell or a `.env` file (the shell wins)
  299. 3. the project config file: the first that exists of `./linear.toml`, `./.linear.toml`, then `linear.toml`, `.linear.toml`, or `.config/linear.toml` at the repository root
  300. 4. the global config file: `$XDG_CONFIG_HOME/linear/linear.toml` (or `~/.config/linear/linear.toml`) on macOS and Linux, `%APPDATA%\linear\linear.toml` on Windows
  301. so the global file can hold defaults such as `issue_sort`, and a repository's `.linear.toml` overrides them for that project. every active value is validated, even one a higher tier overrides, and an invalid value is an error naming its file and key. retired `vcs` and `pr_template` values are ignored without validation; malformed TOML still fails.
  302. run `linear config check` to check the loaded environment, `.env`, global/project config and template overlays locally. it needs no login or network and changes no files. ignored settings are informational, with their sources and no values; they exit successfully and need no cleanup. invalid active settings or malformed config exit with status 1. existing warnings about unusable `.env` entries remain warnings.
  303. ## exit status
  304. scripts can tell why a command failed from its exit status, without parsing the error message:
  305. | status | meaning |
  306. | ------ | ------- |
  307. | `0` | success |
  308. | `1` | any other failure, including GraphQL errors such as an invalid query in `linear api` |
  309. | `2` | usage error: bad flags or values, rejected before anything is sent to Linear |
  310. | `3` | not found: an issue, team, project, or other entity the command looked up does not exist |
  311. | `4` | authentication: no usable API key, or Linear rejected it (revoked, mistyped, or lacking access) |
  312. | `5` | unavailable: Linear could not be reached, timed out, rate limited the request, or failed with a server error. Retrying later may work, but a create or update may still have taken effect |
  313. | `130` | cancelled at a prompt or in the editor |
  314. a bulk command (`--bulk`) that fails for several reasons exits with the first of `4`, `5`, `1`, `3` among them, so `3` means every failure was a missing item. `linear --help` lists the statuses too.
  315. ## skills
  316. linear-cli teaches AI agents to use it. the guide ships with the `linear` binary and applies your global and project [template preferences](docs/templating.md). it covers common workflows and the graphql api for anything the cli doesn't do. `linear skill show issue comment add` prints inherited guidance and help for one command. guide generation needs no login or network; `linear skill show --builtin` ignores configuration for recovery.
  317. ```bash
  318. linear skill setup # install the skill for claude code, codex, opencode and pi
  319. linear skill setup --project # or into the current repository, to commit for your team
  320. linear skill status # see what is installed where
  321. linear skill remove # remove it again
  322. ```
  323. `setup` installs a small skill that tells the agent to run `linear skill show`, which prints the guide. upgrading linear updates the guide, so the installed skill never needs to change.
  324. for Claude Code, `setup` also adds a `SessionStart` hook to `~/.claude/settings.json` (or `.claude/settings.json` with `--project`). it injects a short reminder to load `/linear-cli` or run `linear skill show` before using linear, even when a large skill catalog leaves out the skill's description. it runs on startup, resume, clear and compaction; the full guide is loaded only when needed. run `linear skill setup` again to add the reminder to an existing installation.
  325. for Codex, account setup adds the same reminder to `~/.codex/hooks.json` (or `$CODEX_HOME/hooks.json`), pointing to `$linear-cli`. the hook is installed by default when the Codex configuration directory exists; `--agent codex` installs it explicitly. review and trust the hook in Codex's `/hooks` menu before it runs. project setup installs the skill alone for Codex and recommends account hook setup, because project hooks also require a trusted project. linear never changes Codex's trust settings.
  326. existing settings and hooks are preserved, though writing a hook may reorder and reformat the JSON. `status` reports the reminders alongside the skill, `--dry-run` previews hook changes, and `remove` removes only linear's unedited hooks. settings-file symlinks and existing file permissions are preserved; project settings must resolve inside the repository. custom command variants are separate hooks and are managed by hand. OpenCode and Pi continue to use the skill without a startup hook.
  327. codex, opencode and pi all read `~/.agents/skills`, which is always written. claude code reads `~/.claude/skills`, which is written when claude code is set up on the machine. `--agent` chooses agents explicitly and `--dry-run` shows what would change. in a project, pi loads the skill once the project is trusted.
  328. an agent without skills can run `linear skill show` itself, for example from a line in `AGENTS.md`.
  329. ### skills.sh
  330. the same skill can be installed with [skills.sh](https://skills.sh), without changing hook configuration:
  331. ```bash
  332. npx skills add schpet/linear-cli
  333. ```
  334. ### coming from the claude code plugin or an older copy
  335. releases before 3.2 shipped the skill as a claude code plugin and as a directory of generated files. the plugin is no longer published. uninstall it, then let `setup` replace any older copy:
  336. ```bash
  337. claude plugin uninstall linear-cli@linear-cli
  338. claude plugin marketplace remove linear-cli
  339. linear skill setup --dry-run # an older copy of the skill shows as a conflict
  340. linear skill setup --force # moves older copies to a backup directory, then installs
  341. ```
  342. `--force` deletes nothing: it moves what was there to a `linear-cli-skill-backups` directory beside the skills directory and prints the path. `linear skill status` checks the directories agents read by default; it can't see an installed plugin.
  343. ## development
  344. linear-cli is written in rust; the toolchain is pinned in `rust-toolchain.toml`. common tasks are in the `justfile`:
  345. ```bash
  346. just dev issue mine # run the cli from source (cargo run -- issue mine)
  347. just install # install this checkout as `linear`
  348. just check # cargo fmt --check, clippy, and tests, as CI runs them
  349. ```
  350. ### updating the agent guide
  351. `crates/linear-cli/src/templates/defaults.toml` owns the guide prose and recipes. the command list, exit statuses and markdown rules come from the cli, and tests parse the rendered builtin guide's examples. `skills/linear-cli/SKILL.md` is the small skill that `linear skill setup` installs. to preview the shipped guide without local overrides:
  352. ```bash
  353. just dev skill show --builtin
  354. ```
  355. ### updating the graphql schema
  356. `graphql/schema.graphql` is linear's api schema, used to type-check every query at compile time. refresh it with a logged in cli:
  357. ```bash
  358. just sync-schema
  359. ```
  360. ## why
  361. linear's UI is incredibly good but it slows me down. i find the following pretty grating to experience frequently:
  362. - switching context from my repo to linear
  363. - not being on the right view when i open linear
  364. - linear suggests a git branch, but i have to do the work of creating or switching to that branch
  365. - linear's suggested git branch doesn't account for it already existing or having a merged pull request
  366. this cli solves this. it does the work of preparing a branch or change for an issue, and will write your pull request details for you.
  367. [^1]: creating an API key requires member access, it is not available for guest accounts.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.