Linear CLI

面向智能体（agent）原生设计的 Linear 运行时，适配当前 v3 执行模型，具备稳定的 JSON 接口契约、启动时能力发现（startup discovery）、预览式执行（dry-run previews）、超时感知的写入语义（timeout-aware write semantics）、源文件邻近式内容摄入（source-adjacent intake），以及对 git / jj 工作流的深度集成。

推荐的智能体执行循环（Agent Loop）

在智能体运行时中调用本 CLI 时，请优先遵循以下顺序：

1. 使用 linear capabilities 发现命令能力特征；仅当旧版调用方仍依赖裁剪后的遗留接口形状时，才使用 --compat v1
2. 通过默认 JSON 核心接口或显式 --json 读取 Linear 状态
3. 若支持，优先使用 --dry-run --json 预览写入操作
4. 在默认机器可读输出界面上执行写入操作，随后检查 operation、receipt 和 error.details 字段
5. 依据退出码（exit code）与 error.details 判断结果，而非解析带样式的终端文本输出

由提示驱动的人工交互或调试流程属于次要路径，且需显式启用。当某命令支持交互式提示（prompt）或编辑器输入时，请传入 --profile human-debug --interactive；否则，缺失必需输入将立即失败（fail fast）。

智能体安全的执行语义现已作为默认运行时行为。--text 与 --profile human-debug 是为维护者保留的显式人工/调试逃逸通道（escape hatches），而 --profile agent-safe 仍被接受，以兼容旧版自动化脚本。

当上游工具向运行时传递已归一化的 Slack 消息、工单（ticket）或其他类似来源信封（source envelope）时，优先使用 --context-file；若该信封已包含确定性的团队/状态/标签等提示信息，则额外添加 --apply-triage；当封装层（wrapper）需要“仅建议”（suggest-only）或“必须预览”（preview-required）的阶段性策略时，请显式指定 --autonomy-policy。

推荐参考文档：

• ../../docs/agent-first.md
• ../../docs/v2-to-v3-migration-cookbook.md
• ../../docs/json-contracts.md
• ../../docs/stdin-policy.md

前提条件

linear 命令须已加入系统 PATH。验证方式如下：

linear --version

如未安装，请参照以下地址的说明进行安装：
https://github.com/kyaukyuai/linear-cli?tab=readme-ov-file#install

Markdown 内容处理最佳实践

在处理含 Markdown 格式的工单描述（issue description）或评论正文（comment body）时，对已有磁盘文件优先使用基于文件的参数标志，对流水线动态生成的内容则优先使用标准输入（stdin）：

• 若描述内容已存在于本地文件中，在 issue create 与 issue update 命令中使用 --description-file
• 若评论内容已存在于本地文件中，在 comment add 与 comment update 命令中使用 --body-file
• 对动态生成的 Markdown 内容，采用管道（pipe）方式传入 stdin，例如：cat description.md | linear issue create --title "My Issue" --team ENG

为何避免使用大型内联参数（inline flags）：

• 确保内容在 Linear Web UI 中正确渲染格式
• 规避 Shell 对换行符及特殊字符的转义问题
• 防止字面量 n 序列意外出现在 Markdown 文本中
• 便于在脚本与 CI/CD 流水线中处理多行内容

示例工作流：

# 将 Markdown 写入临时文件
cat > /tmp/description.md <<'EOF'
## Summary

- First item
- Second item

## Details

This is a detailed description with proper formatting.
EOF

# 使用该文件创建工单
linear issue create --title "My Issue" --description-file /tmp/description.md

# 或直接管道传输生成的 Markdown
cat /tmp/description.md | linear issue create --title "My Issue" --team ENG

# 或用于评论
linear issue comment add ENG-123 --body-file /tmp/comment.md

仅对简单、单行内容 使用内联参数（--description、--body）。

可用命令

linear auth               # 管理 Linear 认证
linear issue              # 管理 Linear 工单
linear team               # 管理 Linear 团队
linear project            # 管理 Linear 项目
linear project-update     # 管理项目状态更新
linear cycle              # 管理 Linear 团队周期
linear milestone          # 管理 Linear 项目里程碑
linear initiative         # 管理 Linear 主题（initiatives）
linear initiative-update  # 管理主题状态更新（时间线帖子）
linear label              # 管理 Linear 工单标签
linear document           # 管理 Linear 文档
linear notification       # 管理 Linear 通知
linear webhook            # 管理 Linear Webhook
linear workflow-state     # 管理 Linear 工作流状态
linear user               # 管理 Linear 用户
linear project-label      # 管理 Linear 项目标签
linear config             # 交互式生成 .linear.toml 配置文件
linear schema             # 将 GraphQL Schema 输出至 stdout
linear api                # 发起原始 GraphQL API 请求
linear capabilities       # 描述面向智能体的命令接口表面（command surface）
linear resolve            # 解析引用（references）而不修改 Linear 数据

参考文档

• auth — 管理 Linear 认证
• issue — 管理 Linear 工单
• team — 管理 Linear 团队
• project — 管理 Linear 项目
• project-update — 管理项目状态更新
• cycle — 管理 Linear 团队周期
• milestone — 管理 Linear 项目里程碑
• initiative — 管理 Linear 主题（initiatives）
• initiative-update — 管理主题状态更新（时间线帖子）
• label — 管理 Linear 工单标签
• document — 管理 Linear 文档
• notification — 管理 Linear 通知
• webhook — 管理 Linear Webhook
• workflow-state — 管理 Linear 工作流状态
• user — 管理 Linear 用户
• project-label — 管理 Linear 项目标签
• config — 交互式生成 .linear.toml 配置文件
• schema — 将 GraphQL Schema 输出至 stdout
• api — 发起原始 GraphQL API 请求
• capabilities — 描述面向智能体的命令接口表面（command surface）
• resolve — 解析引用（references）而不修改 Linear 数据

如需查看组织级功能（如 initiatives、labels、projects、批量操作等）的精选示例，请参阅 organization-features。

选项发现方式

要查看任意命令支持的子命令与参数标志，请在其后追加 --help：

linear --help
linear issue --help
linear issue list --help
linear issue create --help

每个命令均提供详尽的帮助输出，完整列出所有可用标志与选项。

如需机器可读的能力发现方式，请优先使用：

linear capabilities
linear capabilities --compat v1

直接使用 Linear GraphQL API

所有受支持的操作请优先使用 CLI。api 命令仅应在 CLI 未覆盖的查询场景下作为备用方案使用。

检查 Schema 中可用的类型与字段

将 Schema 写入临时文件后进行搜索：

linear schema -o "${TMPDIR:-/tmp}/linear-schema.graphql"
grep -i "cycle" "${TMPDIR:-/tmp}/linear-schema.graphql"
grep -A 30 "^type Issue " "${TMPDIR:-/tmp}/linear-schema.graphql"

发起 GraphQL 请求

重要提示： 包含非空类型标记（non-null type markers，例如后跟感叹号的 String!）的 GraphQL 查询，必须通过 heredoc 方式经 stdin 传入，以避免 Shell 转义问题；不含此类标记的简单查询可直接以内联方式传入。

# 简单查询（无类型标记，内联方式即可）
linear api '{ viewer { id name email } }'

# 含变量的查询 — 使用 heredoc 避免转义问题
linear api --variable teamId=abc123 <<'GRAPHQL'
query($teamId: String!) { team(id: $teamId) { name } }
GRAPHQL

# 按文本搜索工单
linear api --variable term=onboarding <<'GRAPHQL'
query($term: String!) { searchIssues(term: $term, first: 20) { nodes { identifier title state { name } } } }
GRAPHQL

# 数值型与布尔型变量
linear api --variable first=5 <<'GRAPHQL'
query($first: Int!) { issues(first: $first) { nodes { title } } }
GRAPHQL

# 通过 JSON 传入复杂变量
linear api --variables-json '{"filter": {"state": {"name": {"eq": "In Progress"}}}}' <<'GRAPHQL'
query($filter: IssueFilter!) { issues(filter: $filter) { nodes { title } } }
GRAPHQL

# 管道至 jq 进行过滤
linear api '{ issues(first: 5) { nodes { identifier title } } }' | jq '.data.issues.nodes[].title'

高级用法：直接使用 curl

当需要完全控制 HTTP 请求细节时，可结合 linear auth token 使用 curl：

curl -s -X POST https://api.linear.app/graphql 
  -H "Content-Type: application/json" 
  -H "Authorization: $(linear auth token)" 
  -d '{"query": "{ viewer { id } }"}'