核心用法
Linear CLI 是专为 AI Agent 设计的 Linear 项目管理命令行工具，采用 v3 执行模型，提供稳定的 JSON 契约与机器优先的交互设计。
关键特性：
- Agent 原生设计：默认 JSON 输出、结构化错误、exit code 语义化，避免解析终端样式文本
- 启动发现：
linear capabilities命令暴露完整命令表面，支持程序化发现 - Dry-run 预览：
--dry-run --json组合可在执行前预览变更，降低误操作风险 - 操作回执：写操作返回
operation、receipt、error.details，便于审计与重试 - 工作流集成：原生支持 Git/jujutsu 工作流，source-adjacent intake 模式
执行模式：
- 默认：
agent-safe（无人值守安全模式） - 人工调试：
--profile human-debug --interactive - 兼容性：
--compat v1支持旧版消费者
推荐 Agent 循环：
1. linear capabilities 发现能力
2. 读操作（默认 JSON）
3. --dry-run --json 预览写入
4. 执行写入并检查回执
5. 基于 exit code 和 error.details 处理异常
核心命令覆盖： Issues、Projects、Cycles、Documents、Notifications、Webhooks、Labels、Teams、Users 等全量 Linear 资源。
Markdown 最佳实践：
- 复杂内容使用
--description-file/--body-file或 stdin 管道 - 避免大段内联参数，防止转义问题和
\n字面量
显著优点
1. Agent 优先架构：相比传统 CLI 的人类可读输出，全程机器可解析
2. 安全写入语义：Timeout-aware、操作回执、dry-run 三层防护
3. 灵活集成：支持 source envelope（Slack/ticket 归一化输入）与 --context-file
4. 完整 API 兜底：linear api 与 linear schema 覆盖 CLI 未实现的高级查询
5. Git 原生：source-adjacent intake 设计，适合 CI/CD 与本地工作流
潜在缺点与局限性
1. 外部依赖：需独立安装 linear 二进制并配置 PATH
2. 认证管理：linear auth 需预配置，Agent 无自动凭证注入机制
3. GraphQL 复杂度：直接使用 linear api 需理解 Linear GraphQL Schema
4. 版本迁移：v2→v3 存在行为变更，旧自动化需显式 --compat v1
5. 交互限制：--interactive 需显式启用，纯 Agent 场景不支持提示式输入
适合人群
- AI Agent 开发者：构建 Claude Code、Codex 等 Agent 的 Linear 集成工作流
- DevOps/Platform 工程师：CI/CD 流水线中自动化 Issue/Project 管理
- 工程团队 Lead：批量操作、报表生成、团队工作流自动化
- 工具集成开发者：需要将 Linear 与其他系统（Slack、GitHub、内部工具）桥接
常规风险
| 风险类型 | 说明 | 缓解措施 |
|---------|------|---------|
| 误写数据 | Agent 自动化可能批量修改/删除 | 强制 `--dry-run` 阶段；审查 `receipt` |
| 凭证泄露 | `linear auth token` 输出敏感信息 | 仅在受控环境使用；避免日志记录 |
| Schema 变更 | Linear GraphQL API 演进 | 依赖 CLI 抽象层，fallback 时锁定 schema 版本 |
| 超时/限流 | 大批量操作触发 Linear API 限制 | CLI 内置 timeout-aware 语义；分页查询 |
| 转义问题 | 复杂 GraphQL 查询的 shell 转义 | 强制 heredoc stdin；避免内联复杂变量 |