MCPInstall
schpet avatar

linear-cli

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

Installs
16.7K
Last 24h
+84
Trending rank
#2222
Security
Warn

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/schpet/linear-cli --skill linear-cli
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads linear-cli automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files, each dated to when it ran.

Gen Agent Trust Hub PassSAFE ·The skill is a legitimate tool for managing Linear workspaces using the linear CLI. It facilitates issue, project, and team management. The analysis found potential risks associated with processing external issue data (indirect prompt injection) and the capability to display authentication tokens.· Audited
Socket PassNo alerts· Audited
Snyk WarnMEDIUM ·Risk: MEDIUM · 2 issues· Audited
Runlayer PassLOW ·2/19 files flagged· Audited
ZeroLeaks PassNONE ·Score: 93/100 · 2 sections analyzed· Audited

SKILL.md

The instructions your agent reads when the skill is triggered.

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 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 create the same mention. Put the plain URL directly in the comment or description:

https://linear.app/yourworkspace/profiles/someuser could you review this? https://linear.app/yourworkspace/issue/ENG-123 is related.

Resolve people within the relevant team first. The team can usually be inferred from the issue identifier or current directory:

linear team members ENG --json

Use the selected member's url field verbatim in the Markdown. If the intended person is not a member of that team, stop and confirm before searching the whole workspace with linear user list --json; mentioning someone outside the team is likely accidental. For issues, use linear issue url ENG-123 and include that plain URL.

Add collapsible sections

Open a collapsible section with +++ [title] and close it with +++:

+++ [Server log]

Markdown content that is initially hidden.

+++

The square brackets around the title and the closing +++ are required.

Exit Status

The exit status says why a command failed, so scripts need not parse stderr:

  • 0 success
  • 1 any other failure, including GraphQL errors from linear api
  • 2 usage error: fix the flags or values; nothing was sent
  • 3 not found: the issue, team, or other entity does not exist
  • 4 authentication: no usable API key, or Linear rejected it; retrying will not help
  • 5 unavailable: network failure, timeout, rate limit, or server error; retry later, but a create or update may already have happened
  • 130 cancelled

Available Commands

Compact command list, generated from linear --help:

linear api

linear auth
linear auth login
linear auth logout
linear auth list
linear auth default
linear auth token
linear auth whoami
linear auth migrate

linear config

linear cycle
linear cycle list
linear cycle view

linear document
linear document list
linear document view
linear document create
linear document update
linear document delete
linear document comment
linear document comment add
linear document comment list

linear initiative
linear initiative list
linear initiative view
linear initiative create
linear initiative update
linear initiative archive
linear initiative unarchive
linear initiative delete
linear initiative add-project
linear initiative remove-project
linear initiative comment
linear initiative comment add
linear initiative comment list

linear initiative-update
linear initiative-update create
linear initiative-update list

linear issue
linear issue list
linear issue query
linear issue view
linear issue create
linear issue update
linear issue delete
linear issue archive
linear issue start
linear issue id
linear issue title
linear issue url
linear issue describe
linear issue commits
linear issue pull-request
linear issue comment
linear issue comment add
linear issue comment list
linear issue comment update
linear issue comment delete
linear issue comment resolve
linear issue comment unresolve
linear issue attach
linear issue link
linear issue relation
linear issue relation add
linear issue relation delete
linear issue relation list
linear issue agent-session
linear issue agent-session list
linear issue agent-session view

linear label
linear label list
linear label create
linear label delete

linear markdown

linear milestone
linear milestone list
linear milestone view
linear milestone create
linear milestone update
linear milestone delete

linear project
linear project list
linear project view
linear project create
linear project update
linear project delete
linear project comment
linear project comment add
linear project comment list

linear project-update
linear project-update create
linear project-update list

linear schema

linear team
linear team list
linear team create
linear team delete
linear team members
linear team states
linear team id
linear team autolinks

linear template
linear template list
linear template view

linear user
linear user list

Reference Documentation

  • api - Send a raw GraphQL request to the Linear API
  • auth - Log in to workspaces and manage their credentials
  • config - Write a .linear.toml for the current repository
  • cycle - View team cycles
  • document - Manage documents
  • initiative - Manage initiatives
  • initiative-update - Post and list initiative status updates
  • issue - Manage issues
  • label - Manage issue labels
  • markdown - Explain Linear-flavored Markdown: mentions and collapsible sections
  • milestone - Manage project milestones
  • project - Manage projects
  • project-update - Post and list project status updates
  • schema - Print the Linear GraphQL schema
  • team - Manage teams
  • template - Browse issue, project and document templates
  • user - List workspace members

For curated examples of organization features (initiatives, labels, projects, bulk operations), see organization-features.

Discovering Options

To see available subcommands and flags, run --help on any command:

linear --help
linear issue --help
linear issue list --help
linear issue create --help

Each command has detailed help output describing all available flags and options.

Some commands have required flags that aren't obvious. Notable examples:

  • issue list sorts by priority by default — override via --sort (valid values: manual, priority), the issue_sort config option, or the LINEAR_ISSUE_SORT env var. Requires --team <key> unless the team can be inferred from the directory — if unknown, run linear team list first (linear team list --json maps team names to their key and id).
  • --no-pager is only supported on issue list, issue query, issue view, and project view — passing it to other commands like project list will error.

Using the Linear GraphQL API Directly

Prefer the CLI for all supported operations. The api command should only be used as a fallback for queries not covered by the CLI.

Check the schema for available types and fields

Write the schema to a tempfile, then search it:

linear schema -o "${TMPDIR:-/tmp}/linear-schema.graphql"
grep -i "cycle" "${TMPDIR:-/tmp}/linear-schema.graphql"
grep -A 30 "^type Issue " "${TMPDIR:-/tmp}/linear-schema.graphql"

Make a GraphQL request

linear api takes the GraphQL document as its only positional argument and has no subcommands. Put a leading query or mutation keyword inside that quoted document: use linear api 'query { ... }', never linear api query '...'. linear issue query is a separate, real subcommand for searching issues.

Important: GraphQL queries containing non-null type markers (e.g. String followed by an exclamation mark) must be passed via heredoc stdin to avoid escaping issues. Simple queries without those markers can be passed inline.

# Simple query (no type markers, so inline is fine)
linear api '{ viewer { id name email } }'

# Query with variables — use heredoc to avoid escaping issues
linear api --variable teamId=abc123 <<'GRAPHQL'
query($teamId: String!) { team(id: $teamId) { name } }
GRAPHQL

# Search issues by text
linear api --variable term=onboarding <<'GRAPHQL'
query($term: String!) { searchIssues(term: $term, first: 20) { nodes { identifier title state { name } } } }
GRAPHQL

# Numeric and boolean variables
linear api --variable first=5 <<'GRAPHQL'
query($first: Int!) { issues(first: $first) { nodes { title } } }
GRAPHQL

# Complex variables via JSON
linear api --variables-json '{"filter": {"state": {"name": {"eq": "In Progress"}}}}' <<'GRAPHQL'
query($filter: IssueFilter!) { issues(filter: $filter) { nodes { title } } }
GRAPHQL

# Pipe to jq for filtering
linear api '{ issues(first: 5) { nodes { identifier title } } }' | jq '.data.issues.nodes[].title'

Advanced: Using curl directly

For cases where you need full HTTP control, use linear auth token:

curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $(linear auth token)" \
  -d '{"query": "{ viewer { id } }"}'

FAQ

What does the linear-cli skill do?

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

How do I install linear-cli?

Run npx skills add https://github.com/schpet/linear-cli --skill linear-cli in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/linear-cli/ (personal) or .claude/skills/linear-cli/ (project).

Which AI agents can use linear-cli?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is linear-cli safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk flagged items to review; Runlayer passed; ZeroLeaks passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains linear-cli?

It is published by schpet in schpet/linear-cli. It has 16,674 recorded installs.

More from schpet/linear-cli

View all →
schpet avatar

release

schpet/linear-cli

This skill should be used when the user asks to "make a release", "create a release", "cut a release", "release a new version", "publish a release", or mentions preparing for release. Provides comprehensive workflow for reviewing changes, updating changelog, determining semver bump, and publishing.

Popular productivity & automation skills

View category →
vercel-labs avatar

agent-browser

vercel-labs/agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools.

OfficialProductivity & Automation1.5M installs
open.feishu.cn avatar

lark-doc

open.feishu.cn

飞书云文档(Docx / Wiki)内容操作:读取、创建、编辑文档,插入或下载图片附件,以及操作思维笔记。用户提供文档 URL/token(包括 doubao.com 的 /docx/、/wiki/)时使用;按 URL 路径/token 而非域名路由;/page/ 是妙搭应用,非飞书云文档。文档内嵌资源按读取参考中的统一规则分流。独立评论操作走 lark-drive;随正文读取评论使用 docs +fetch。表格或 Base 内部数据操作不在本 skill。

open.feishu.cn avatar

lark-shared

open.feishu.cn

Use for lark-cli setup/auth tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, or handling notice JSON.

open.feishu.cn avatar

lark-drive

open.feishu.cn

飞书云空间(云盘/云存储):管理 Drive 文件和文件夹,包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、查询权限设置、评论/权限/订阅、标题、版本、飞书文档密级标签(secure labels)和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token、判断链接类型/真实 token/标题,或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用;doubao.com 云空间 URL/token 也按资源路径和 token 路由,不回退 WebFetch。不负责:文档内容编辑(走 lark-doc)、表格/Base 表内数据操作(走 lark-sheets/lark-base)、知识空间节点/成员管理(走 lark-wiki)、原生 Markdown 文件读写/patch/diff(走 lark-markdown)。

open.feishu.cn avatar

lark-base

open.feishu.cn

飞书多维表格(Base)操作:建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式(BaseApp/AppMode 页面与组件)、Workspace 目录、workflow、角色权限、模板中心(多维表格模板分类/列表/搜索);遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps;文件导入/导出转 lark-drive,认证/授权转 lark-shared。

open.feishu.cn avatar

lark-im

open.feishu.cn

飞书即时通讯:收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片(Interactive Card)、监听卡片按钮回调(card.action.trigger)。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶(添加/移除/查询置顶会话)、管理标签数据、处理卡片回调时使用。