linear-cli

Linear CLI

一个用于从命令行管理 Linear 问题的 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

Markdown 内容的最佳实践

在处理包含 markdown 的问题描述或评论正文时，始终优先使用基于文件的标志，而不是将内容作为命令行参数传递：

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

为什么使用基于文件的标志：

• 确保在 Linear Web UI 中正确格式化
• 避免换行和特殊字符的 shell 转义问题
• 防止 markdown 中出现字面的 \n 序列
• 更容易处理多行内容

示例工作流程：

# 将 markdown 写入临时文件
cat > /tmp/description.md <<'EOF'
## 摘要

- 第一项
- 第二项

## 详情

这是格式正确的详细描述。
EOF

# 使用文件创建问题
linear issue create --title "我的问题" --description-file /tmp/description.md

# 或者用于评论
linear issue comment add ENG-123 --body-file /tmp/comment.md

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

可用命令

紧凑的命令列表，从 linear --help 生成：

linear api

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

linear config

linear cycle
linear cycle list
linear cycle view

linear document
linear document create
linear document delete
linear document list
linear document update
linear document view

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

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

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

linear label
linear label create
linear label delete
linear label list

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

linear project
linear project create
linear project delete
linear project list
linear project update
linear project view

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

linear schema

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

参考文档

• api - 发起原始 GraphQL API 请求
• auth - 管理 Linear 身份验证
• config - 交互式生成 .linear.toml 配置
• cycle - 管理 Linear 团队周期
• document - 管理 Linear 文档
• initiative - 管理 Linear 倡议
• initiative-update - 管理倡议状态更新（时间线帖子）
• issue - 管理 Linear 问题
• label - 管理 Linear 问题标签
• milestone - 管理 Linear 项目里程碑
• project - 管理 Linear 项目
• project-update - 管理项目状态更新
• schema - 将 GraphQL 模式打印到标准输出
• team - 管理 Linear 团队

有关组织功能（倡议、标签、项目、批量操作）的精选示例，请参阅 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。
• --no-pager 仅在 issue list 上受支持——将其传递给其他命令（如 project list）会报错。

直接使用 Linear GraphQL API

对于所有支持的操作，优先使用 CLI。 api 命令仅应作为 CLI 未覆盖的查询的回退方案。

检查模式以获取可用的类型和字段

将模式写入临时文件，然后搜索：

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 请求

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

# 简单查询（无类型标记，因此内联即可）
linear api '{ viewer { id name email } }'

# 带变量的查询——使用 heredoc 避免转义问题
linear api --variable teamId=abc123 <<'GRAPHQL'
query($teamId: String!) { team(id: $teamId) { name } }
GRAPHQL

# 按文本搜索问题
linear api --variable term=onboarding <<'GRAPHQL'
query($term: String!) { searchIssues(term: $term, first: 20) { nodes { identifier title state { name } } } }
GRAPHQL

# 数字和布尔变量
linear api --variable first=5 <<'GRAPHQL'
query($first: Int!) { issues(first: $first) { nodes { title } } }
GRAPHQL

# 通过 JSON 传递复杂变量
linear api --variables-json '{"filter": {"state": {"name": {"eq": "In Progress"}}}}' <<'GRAPHQL'
query($filter: IssueFilter!) { issues(filter: $filter) { nodes { title } } }
GRAPHQL

# 通过管道传递给 jq 进行过滤
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 } }"}'