Linear CLI

核心用法

linear-cli 是一个面向 AI 代理（Claude Code、Codex 等）原生设计的 Linear 项目管理命令行工具，采用 v3.0.0 执行模型，提供稳定的 JSON 契约、启动发现机制和干运行预览能力。

关键执行模式：
1. 发现阶段：使用 linear capabilities 探测命令特性，兼容旧版本可用 --compat v1
2. 读取操作：默认 JSON 输出，如 linear issue list --json
3. 预览写入：--dry-run --json 在应用前预览变更
4. 执行写入：获取 operation、receipt、error.details 等机器可读回执
5. 错误处理：依赖退出码和结构化错误信息，而非解析终端文本

Markdown 内容最佳实践：

• 文件内容使用 --description-file / --body-file
• 管道生成内容直接通过 stdin 传入
• 避免大型内联参数以防止转义问题和格式异常

核心命令覆盖： issues、projects、cycles、documents、notifications、webhooks、teams、labels、initiatives、milestones 等全量 Linear 资源管理，同时支持原生 GraphQL API 直接访问作为后备方案。

显著优点

• 代理原生设计：默认机器可读输出，JSON 契约稳定，无需解析终端样式文本
• 安全执行语义：内置超时感知写入、操作回执机制，支持 --dry-run 预览
• Git/JJ 工作流集成：与版本控制工作流深度整合
• 灵活的 Markdown 处理：支持文件、stdin、内联三种内容输入模式
• 完整的资源覆盖：涵盖 Linear 绝大多数核心实体
• GraphQL 直通能力：linear api 和 linear schema 支持自定义查询

潜在局限

• 外部依赖：需单独安装 linear CLI 并配置 PATH
• 认证管理：需预先完成 linear auth 配置
• GraphQL 复杂度：直接 API 使用时需注意非空类型标记（!）的转义问题
• 人类交互为次要模式：--profile human-debug 和 --text 需显式启用
• 特定版本绑定：v3.0.0 执行模型可能与旧版自动化不兼容

适合人群

• AI 编程助手/代理（Claude Code、Codex、Cursor Agent 等）
• 需要自动化 Linear 工作流的 DevOps/平台工程师
• 构建 CI/CD 流水线集成 Linear 的开发团队
• 偏好命令行和 JSON 接口而非 Web UI 的高级用户

常规风险

• 认证令牌安全：linear auth token 输出的令牌需妥善管理，避免泄露
• 写操作不可逆：虽有 --dry-run，但实际执行后 Linear 数据变更难以回滚
• GraphQL 查询风险：直接使用 linear api 可能触发意外的大数据量查询
• 版本漂移：CLI 与 Linear API 版本不匹配可能导致契约破坏
• 并发写入冲突：多代理/多进程同时操作同一资源可能产生竞态条件