linear-cli

Linear CLI

一款用于通过命令行管理 Linear issue 的 CLI，并集成了 git 和 jj。

前置条件

linear 命令必须在 PATH 中可用。检查方法：

linear --version

如果未全局安装，可以通过 npx 运行，无需安装：

npx @schpet/linear-cli --version

后续所有命令都可以在前面加上 npx @schpet/linear-cli，代替 linear。否则，请按照以下安装说明操作：
https://github.com/schpet/linear-cli?tab=readme-ov-file#install

常见任务

以下是最常用工作流的可复制粘贴示例。优先使用这些专用命令，而不是 linear api；仅当没有专用命令或标志能完成操作时，才使用 GraphQL 备用方案。

使用筛选条件查询 issue

issue query 会搜索所有受指派人，并支持可组合使用的结构化筛选条件：

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

注意：linear issue list（别名 issue mine）默认显示_你_的 issue；要查询其他人或整个团队／项目范围内的内容，请使用 issue query。

列出我的 issue

linear issue list --state started --sort priority

创建 issue

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

将多行 Markdown 写入文件，并传入 --description-file（参见下文的 Markdown 部分）；在脚本中使用时，--no-input 会让命令在有必填内容缺失时失败，而不是提示输入。

更新 issue 的状态、受指派人或标签

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

根据模板创建 issue 或项目

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"

显式标志会覆盖模板中的值，--label 会与模板标签合并，--description 会替换模板正文（省略该选项则保留正文）。文档模板无法通过 API 应用。

添加评论

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

附加图片或屏幕截图，使其以内嵌形式显示

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

此操作会上传图片并将其嵌入评论中，Linear 会以内嵌形式渲染图片。如果图片必须可见，请勿使用 linear issue attach：该命令会创建显示在侧边栏中的链接附件，不会以内嵌形式渲染图片。

解决或重新打开评论串

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

使用顶层评论的 ID 指定评论串；回复的 ID 不会被接受。在 comment list --json 中，只有已解决评论串的顶层评论才会设置 resolvedAt，回复则会在 parent.resolvedAt 中携带其所属评论串的状态。开放评论串的 ID 可通过 jq -r '.[] | select(.parent == null and .resolvedAt == null) | .id' 获取。

查看 issue／获取其 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

关闭、删除或归档 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

优先关闭或删除，而不是归档。Linear 的文档称“归档会自动发生，无法手动归档条目”（https://linear.app/docs/delete-archive-issues）：已关闭的 issue 会在团队配置的期限过后自动归档；由于用户把归档功能当作垃圾桶使用，Linear 已从其应用中移除手动归档功能。issue archive 会直接调用 issueArchive mutation，绕过对开放父项、子 issue、周期和项目的自动归档检查；除非传入 --include-archived，已归档的 issue 也不会出现在 issue list、issue query 和搜索结果中。仅在用户明确提出要求时才归档。

Markdown 内容的最佳实践

处理包含 Markdown 的 issue 描述或评论正文时，始终优先使用基于文件的标志，不要将内容作为命令行参数传入：

• 对于 issue create 和 issue update 命令，使用 --description-file
• 对于 comment add 和 comment update 命令，使用 --body-file

使用基于文件的标志的原因：

• 确保内容在 Linear 网页界面中正确格式化
• 避免换行符和特殊字符导致的 shell 转义问题
• 防止 Markdown 中出现字面的 \n 序列
• 便于处理多行内容

工作流示例：

# 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

仅对简单的单行内容使用内联标志（--description、--body）。

Linear Markdown 功能

使用普通 URL 提及人员和资源

在 Markdown 中，Linear 会将资源的普通 Linear URL转换为链接提及。单独使用 @name、@[Name](id) 或 [Name](url) 这样的 Markdown 链接，不会创建同样的提及。请将普通 URL 直接放在评论或描述中：

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

先在相关团队中查找人员。通常可以根据问题标识符或当前目录推断团队：

linear team members ENG --json

在 Markdown 中原样使用所选成员的 url 字段。如果目标人员不是该团队的成员，请先停止并确认，再使用 linear user list --json 搜索整个工作区；提及团队外的人员很可能是误操作。对于问题，请使用 linear issue url ENG-123 并附上该普通 URL。

添加可折叠部分

使用 +++ [title] 打开可折叠部分，并使用 +++ 将其关闭：

+++ [Server log]

Markdown content that is initially hidden.

+++

标题两侧的方括号和结尾的 +++ 均为必需内容。

退出状态

退出状态说明命令失败的原因，因此脚本无需解析 stderr：

• 0 成功
• 1 其他任何失败，包括 linear api 返回的 GraphQL 错误
• 2 用法错误：修正标志或值；未发送任何内容
• 3 未找到：问题、团队或其他实体不存在
• 4 身份验证失败：没有可用的 API 密钥，或 Linear 拒绝了该密钥；重试无济于事
• 5 服务不可用：网络故障、超时、速率限制或服务器错误；请稍后重试，但创建或更新操作可能已经完成
• 130 已取消

可用命令

从 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

参考文档

• api - 向 Linear API 发送原始 GraphQL 请求
• auth - 登录工作区并管理其凭据
• config - 为当前代码库编写 .linear.toml
• cycle - 查看团队周期
• document - 管理文档
• initiative - 管理计划
• initiative-update - 发布并列出计划状态更新
• issue - 管理问题
• label - 管理问题标签
• markdown - 介绍 Linear 风格的 Markdown：提及和可折叠部分
• milestone - 管理项目里程碑
• project - 管理项目
• project-update - 发布并列出项目状态更新
• schema - 输出 Linear GraphQL 架构
• team - 管理团队
• template - 浏览问题、项目和文档模板
• user - 列出工作区成员

如需组织功能（计划、标签、项目、批量操作）的精选示例，请参阅 organization-features。

查找选项

要查看可用的子命令和标志，请对任意命令运行 --help：

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

每个命令都有详细的帮助输出，说明所有可用标志和选项。

某些命令需要不太明显的必需标志。值得注意的示例：

• issue list 默认按优先级排序——可通过 --sort（有效值：manual、priority）、issue_sort 配置选项或 LINEAR_ISSUE_SORT 环境变量更改排序。除非可以从目录推断团队，否则必须指定 --team <key>；如果团队未知，请先运行 linear team list（linear team list --json 会将团队名称映射到其 key 和 id）。
• --no-pager 仅支持用于 issue list、issue query、issue view 和 project view；将其传给 project list 等其他命令会报错。

直接使用 Linear GraphQL API

所有受支持的操作都优先使用 CLI。 只有当 CLI 不支持所需查询时，才应将 api 命令用作后备方案。

检查架构以查看可用类型和字段

将架构写入临时文件，然后搜索：

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"

发起 GraphQL 请求

linear api 将 GraphQL 文档作为唯一的位置参数，且没有子命令。在引号括起的文档中添加前导 query 或 mutation 关键字：使用 linear api 'query { ... }'，而不要使用 linear api query '...'。linear issue query 是一个独立且真实存在的用于搜索问题的子命令。

重要： 包含非空类型标记（例如 String 后跟感叹号）的 GraphQL 查询必须通过 heredoc 标准输入传递，以避免转义问题。不包含这类标记的简单查询可以直接内联传递。

# 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'

高级用法：直接使用 curl

如果需要完全控制 HTTP 请求，请使用 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 } }"}'