首页 / Linear CLI / Linear CLI
👁️ 418
👍 122
📅 2026-06-13 收录
🔄 2026-06-13 更新
Linear CLI

Linear CLI

🔗 打开网站
🗃 Linear CLI
Skills
🚀 访问网站 📁 查看更多

正文内容

Linear CLI

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

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

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

  1. 使用 linear capabilities 发现命令能力；仅当旧版消费者仍依赖裁剪后的遗留结构时，才指定 --compat v1
  2. 使用默认 JSON 格式的主接口（core surfaces）或显式 --json 参数读取 Linear 状态
  3. 在支持时，使用 --dry-run --json 预览写入操作
  4. 在默认的机器可读输出界面上执行写入操作，随后检查响应中的 operation、receipt 及 error.details 字段
  5. 依据退出码（exit code）和 error.details 判断结果，切勿解析带格式的终端文本输出

面向人工提示（prompt-driven）的调试/交互流程为次要路径，且需显式启用。若某命令支持交互式提示或编辑器输入，请显式传入 --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/agent-first.md)
  • [../../docs/v2-to-v3-migration-cookbook.md](../../docs/v2-to-v3-migration-cookbook.md)
  • [../../docs/json-contracts.md](../../docs/json-contracts.md)
  • [../../docs/stdin-policy.md](../../docs/stdin-policy.md)

前置条件（Prerequisites）

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

linear --version

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

Markdown 内容处理最佳实践

在处理含 Markdown 的 Issue 描述或评论正文时，对已有磁盘文件优先使用基于文件的参数；对流水线动态生成的内容则优先使用标准输入（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 
仅对简单、单行内容 使用内联参数（--description、--body）。
可用命令列表
linear auth               # 管理 Linear 认证
linear issue              # 管理 Linear issues
linear team               # 管理 Linear teams
linear project            # 管理 Linear projects
linear project-update     # 管理项目状态更新（project status updates）
linear cycle              # 管理 Linear team cycles
linear milestone          # 管理 Linear project milestones
linear initiative         # 管理 Linear initiatives
linear initiative-update  # 管理 initiative 状态更新（即时间线动态，timeline posts）
linear label              # 管理 Linear issue labels
linear document           # 管理 Linear documents
linear notification       # 管理 Linear notifications
linear webhook            # 管理 Linear webhooks
linear workflow-state     # 管理 Linear workflow states
linear user               # 管理 Linear users
linear project-label      # 管理 Linear project labels
linear config             # 交互式生成 .linear.toml 配置文件
linear schema             # 将 GraphQL schema 输出至 stdout
linear api                # 发起原始 GraphQL API 请求
linear capabilities       # 描述面向智能体的命令接口（agent-facing command surface）
linear resolve            # 解析引用（references）而不修改 Linear 数据
参考文档（Reference Documentation）
  • [auth](references/auth.md) — 管理 Linear 认证
  • [issue](references/issue.md) — 管理 Linear issues
  • [team](references/team.md) — 管理 Linear teams
  • [project](references/project.md) — 管理 Linear projects
  • [project-update](references/project-update.md) — 管理项目状态更新
  • [cycle](references/cycle.md) — 管理 Linear team cycles
  • [milestone](references/milestone.md) — 管理 Linear project milestones
  • [initiative](references/initiative.md) — 管理 Linear initiatives
  • [initiative-update](references/initiative-update.md) — 管理 initiative 状态更新（时间线动态）
  • [label](references/label.md) — 管理 Linear issue labels
  • [document](references/document.md) — 管理 Linear documents
  • [notification](references/notification.md) — 管理 Linear notifications
  • [webhook](references/webhook.md) — 管理 Linear webhooks
  • [workflow-state](references/workflow-state.md) — 管理 Linear workflow states
  • [user](references/user.md) — 管理 Linear users
  • [project-label](references/project-label.md) — 管理 Linear project labels
  • [config](references/config.md) — 交互式生成 .linear.toml 配置
  • [schema](references/schema.md) — 将 GraphQL schema 输出至 stdout
  • [api](references/api.md) — 发起原始 GraphQL API 请求
  • [capabilities](references/capabilities.md) — 描述面向智能体的命令接口
  • [resolve](references/resolve.md) — 解析引用而不修改 Linear 数据

如需组织级功能（initiatives、labels、projects、批量操作等）的精选示例，请参阅 [organization-features](references/organization-features.md)。

查看可用选项（Discovering Options）

要查看任意命令的子命令与参数列表，请在其后追加 --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 未覆盖场景下的备用方案（fallback）。

检查 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 请求

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

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

# 含变量的查询 — 使用 heredoc 避免转义问题
linear api --variable teamId=abc123 
高级用法：直接使用 curl
如需完全控制 HTTP 层，请结合 linear auth token 使用：
curl -s -X POST https://api.linear.app/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: $(linear auth token)" \
  -d '{"query": "{ viewer { id } }"}'