核心用法
linear-cli 是一款专为 AI 代理设计的 Linear 命令行工具，核心设计理念是"agent-first"——优先保证机器可读的 JSON 输出而非人类友好的终端样式。其命令体系覆盖 Linear 全量资源：issues、projects、cycles、documents、notifications、webhooks 等，共 20+ 个顶级命令。
推荐代理工作流：
1. 能力发现：linear capabilities --json 获取命令元数据
2. 状态读取：所有查询命令附加 --json 获取结构化数据
3. 变更预览：写操作先执行 --dry-run --json，校验后再应用
4. 结果解析：依赖 exit code 和 error.details 字段，而非正则匹配终端输出
内容处理最佳实践：
- Markdown 描述优先使用
--description-file/--body-file文件参数 - 管道生成内容可用
stdin传入 - 避免大型内联参数，防止 shell 转义与
\n字面量问题
GraphQL 兜底：linear api 命令支持原始 GraphQL 查询，配合 --variable / --variables-json 处理复杂参数，heredoc 语法避免 ! 类型标记的转义问题。
显著优点
- 契约稳定性：显式 JSON Schema 输出，兼容
v2元数据扩展，适合长期自动化脚本 - 安全变更：内置
--dry-run预览机制，配合 timeout-aware 写语义，降低误操作风险 - Git/JJ 集成：工作流感知设计，可与版本控制工具链无缝衔接
- 认证隔离：
linear auth token支持独立获取凭证，便于 curl 场景复用
潜在局限
- 第三方实现：非 Linear 官方工具，存在 API 变更导致不兼容的长期风险
- 覆盖盲区：官方 API 边缘功能可能缺失 CLI 封装，需 fallback 到原始 GraphQL
- 生态规模：相比 GitHub CLI 等成熟工具，社区插件与 CI 模板积累较少
适合人群
- 使用 Claude Code、Codex 等 AI 代理进行项目管理的开发者
- 需要流水线集成 Linear 的 DevOps 工程师
- 追求声明式、可审计的项目操作脚本的技术团队
常规风险
- 认证泄露：
linear auth token输出需妥善保管，避免意外日志留存 - 数据一致性：dry-run 预览与真实执行之间可能存在状态漂移（如 issue 被他人修改）
- GraphQL 复杂度：直接使用
api命令时，复杂变量与过滤条件需严格校验 JSON 格式 - Rate Limit：高频自动化操作需关注 Linear API 配额限制