linear-cli 是一个让你不离开命令行就能管理 Linear 项目的工具：列出 issue、开始处理任务、为 issue 创建 PR，并且对 Agent 非常友好。它的一大亮点是结构化的退出码（exit code）设计——每条命令失败时都会返回不同的退出码，脚本可以据此精准判断失败原因，而无需费力解析 stderr 输出。本文带你完整读懂 linear-cli 的退出码体系：0、1、2、3、4、5（以及130）各代表什么，并给出实用的脚本判断技巧。

退出码速查表：一眼看懂命令为什么失败

这张速查表与官方文档 docs/usage.md 中 "exit status" 一节完全一致，AI 技能文档 skills/linear-cli/SKILL.md 也有同样的 Exit Status 章节。

各退出码深度解读

0 和 1：成功与"兜底"失败

0表示成功，自不待言。1是一个**兜底类（general）**退出码：凡是"不属于其他类别"的运行时失败都归到它——例如 Linear 拒绝了你的输入、linear api发送了无效的 GraphQL 查询等。写脚本时，1通常意味着"需要人工看一眼输出"。

2：用法错误——什么都没发到 Linear

退出码2对应用法错误（usage error）：参数拼写错误、缺少必填值等。关键点是这类错误在发送任何请求之前就被拒绝了，所以2代表"命令根本没执行"，可以放心修改参数后重试。

3：未找到——实体不存在

当命令要查询的 issue、team、label、project 等 Linear 实体不存在时，返回3（not found）。注意它只针对 Linear 侧的实体；本地文件读不到之类的问题会归入1。

4：认证失败——重试没用

4表示认证问题：没有配置可用的 API key，或 key 已被吊销、输错、权限不足。重试不会有帮助，正确做法是重新登录：

linear auth login

命令输出中通常还会附带提示行（hint），指引你执行上述命令。

5：服务不可用——可以重试，但要小心

5表示 Linear 暂时无法提供服务：网络故障、请求超时、被限流或服务器内部错误。这类失败稍后重试通常能成功，但有一个重要细节：create 或 update 类操作可能实际上已经生效，盲目重试可能产生副作用，建议先查询确认状态再决定是否重试。

130：用户主动取消

在交互提示或编辑器中按 Ctrl-C / Esc 取消时，linear-cli 输出Canceled.并以130退出。在 CI 场景下用--no-input可以避免意外进入交互提示；脚本里把130单列出来，就不会把"人为取消"误报成程序故障。

退出码背后的源码设计

退出码逻辑集中在 crates/linear-cli/src/error.rs 中。Failure枚举定义了四种运行时失败类别，每个类别通过exit_code()方法映射到具体数字：

• General→1
• NotFound→3
• Auth→4
• Unavailable→5

进程入口 crates/linear-cli/src/app.rs 中的main()函数在命令成功时返回0，失败时先向 stderr 打印✗ message及提示，再返回对应的退出码；最终由 crates/linear-cli/src/main.rs 转换为进程的退出状态。此外还有两个小细节：

• 子进程的退出状态会原样透传（例如收到 SIGTERM 后返回143）；
• 如果下游读取方关闭了 stdout（broken pipe），linear-cli 会安静地以0退出，避免linear issue list | head这类管道产生报错。

批量命令的退出码：取"最需要优先处理"的类别

当你用批量命令（如批量归档 issue）一次处理多个目标、且部分失败时，退出码如何定？答案是：取所有失败中最严重的一类。

严重度排序为：认证（4） > 不可用（5） > 一般失败（1） > 未找到（3）。也就是说，一次运行里如果既有 issue 不存在（3）、又触发了限流（5），最终退出码是5——认证问题最优先，因为其他问题在它面前都无需处理。该逻辑由 error.rs 中的combine/fold方法实现，批量执行的汇总与退出码判定见 crates/linear-cli/src/commands/bulk.rs。

脚本实战：用 case 精准分流失败原因

下面是一个典型的 CI 脚本写法，按退出码精准分流，无需解析 stderr：

linear issue view ENG-12 --no-input status=$? case $status in 0) echo "ok" ;; 2) echo "参数错误：先修命令再重试" ;; 3) echo "issue 不存在：核对标识符" ;; 4) echo "认证失败：CI 中检查 API key 环境变量" ;; 5) echo "Linear 不可用：可重试，但注意写操作可能已生效" ;; 130) echo "被取消" ;; *) echo "一般失败（$status）：查看日志" ;; esac

💡 几个实用建议：

1. 自动化场景加--no-input：缺值时直接失败而不是等待交互，让退出码成为唯一信号。
2. 2与4不要重试：前者改参数才有用，后者重试无效。
3. 5可以指数退避重试，但重试前先查询确认写操作是否已生效。
4. 把130视为"跳过"而非"失败"，避免污染告警。

总结

掌握 linear-cli 的退出码体系后，你的脚本和 Agent 就能像读懂"结构化 API"一样读懂它：不用正则解析报错文本，一个$?判断即可决定下一步动作。更多命令用法可参考 docs/usage.md，AI 集成技巧见 skills/linear-cli/SKILL.md。