核心用法
linear-cli 是一个面向 AI 代理（Agent）原生运行时设计的 Linear 管理工具，采用 v3.0.0 执行模型，专为 Claude Code、Codex 等自动化环境优化。
关键特性：
- 默认 JSON 输出：所有命令原生支持机器可读的 JSON 格式，避免解析终端样式文本
- 启动发现（Startup Discovery）：通过
linear capabilities自动探测命令能力，支持版本兼容模式 - Dry-run 预览：写操作前可预览变更，降低自动化风险
- 操作收据（Operation Receipts）：每次写入返回结构化收据，便于审计和回滚
- Git/JJ 工作流集成：与版本控制工作流深度整合
核心命令体系：
覆盖 Linear 全资源管理——Issues、Teams、Projects、Cycles、Milestones、Initiatives、Labels、Documents、Notifications、Webhooks 等 15+ 个资源维度，同时提供 api 命令作为 GraphQL 直连fallback。
显著优点
1. Agent-First 设计：默认行为即为自动化安全，人机交互需显式开启 --profile human-debug
2. 稳定的 JSON 契约：v3.0.0 版本提供稳定的机器可读接口，降低集成 fragility
3. Markdown 友好：针对 issue 描述和评论内容，提供 --description-file、--body-file 及 stdin 管道支持，避免 shell 转义问题
4. 渐进式安全：dry-run → 应用 → 收据验证的完整闭环
5. 灵活的后门：linear api 允许在 CLI 未封装场景下直接访问 GraphQL
潜在缺点与局限性
1. 第三方工具依赖：需单独安装 linear-cli，非 Linear 官方出品（kyaukyuai/linear-cli）
2. 功能覆盖边界：部分高级 GraphQL 查询仍需 fallback 到 api 命令或原始 curl
3. 学习曲线：capabilities 发现模式与传统 --help 并存，概念层次较多
4. 社区规模：相比官方 SDK，第三方维护的可持续性存在不确定性
适合人群
- 使用 Claude Code、Codex 等 AI 编码代理的开发者
- 需要批量自动化 Linear 数据操作的 DevOps/平台工程师
- 追求 GitOps 风格项目管理的技术团队
- 希望将 Linear 集成到 CI/CD 管道的工程团队
常规风险
- Token 管理：
linear auth token暴露的凭证需妥善保管，避免泄露到日志 - 写操作幂等性：虽提供 dry-run，但大规模自动化仍需配合事务性设计
- API 速率限制：直接 GraphQL 调用可能触发 Linear 平台限流
- Schema 变更：非官方工具可能滞后于 Linear API 更新
评估结论
作为 Agent-Native 工作流的专用工具，linear-cli 在自动化友好性上设计精巧，JSON 契约和 dry-run 机制显著降低了 AI 代理的操作风险。适合已采用 Claude Code 等现代 Agent 工作流、且希望深度集成 Linear 的技术团队。建议配合官方 SDK 作为互补方案，关键业务逻辑增加兜底校验。