概述
linear-cli 是一款专为 AI Agent 设计的 Linear 命令行工具，核心定位是提供可编程、可预测、可回滚的项目管理接口。与传统 CLI 不同，它强调 JSON-first 契约、dry-run 预览和超时感知的写操作语义，使 Claude Code、Codex 等 Agent 能够安全地自动化 Linear 工作流。
核心用法
工具覆盖 Linear 全资源类型：issue、project、cycle、milestone、initiative、label、document、notification、webhook 等。推荐 Agent 调用模式为：
1. linear capabilities --json 发现命令能力
2. --json 读取状态
3. --dry-run --json 预览变更
4. 执行写操作并检查 exit code 与 error.details
特殊支持文件式 Markdown 输入（--description-file、--body-file），避免 shell 转义问题。GraphQL API 直连作为 fallback，支持 heredoc 传参与变量绑定。
显著优点
- Agent 原生设计: 输出契约稳定，不依赖终端样式解析
- 安全写操作: dry-run 模式 + 超时感知，降低误操作风险
- Git 工作流集成: 天然适配 CI/CD 和代码提交流程
- Markdown 友好: 文件/pipe 输入避免转义地狱
- GraphQL 透明: schema 导出与裸 API 调用能力完备
潜在局限
- 需独立安装
linear二进制，非 Node/Python 生态原生 - 高级 GraphQL 查询需手写，学习成本高于纯 SDK
- 文档引用大量相对路径（
../../docs/），跨环境可能失效
适合人群
AI Agent 开发者、DevOps 工程师、需将 Linear 纳入自动化工作流的团队，尤其适合已有 CLI 工具链或 Git-based workflow 的组织。
常规风险
- Token 泄露:
linear auth token输出需妥善保管 - 写操作误触: 虽 dry-run 可降低风险，但
--json输出仍需验证 - GraphQL 复杂度: 手写查询易构造低效或错误语句
- 版本兼容性:
--compat v2等标志需显式管理