⚡

LinearCLISkill linear

Linear CLI是一款用于Linear项目管理平台的命令行工具，提供问题跟踪、任务创建、团队协作、项目管理和GraphQL查询等功能。支持自动化工作流、JSON数据处理、API集成和开发团队协作，适用于敏捷开发、DevOps流程和软件项目管理。

DevOps 0 次安装 0 次浏览 更新于 2/28/2026

名称: linear 描述: 通过CLI管理Linear问题、团队和项目。列出问题、创建任务、查看详情、链接问题、运行GraphQL查询。必须用于“我的Linear问题”、“创建Linear任务”、“在Linear中链接问题”、“Linear API查询”或任何Linear项目管理请求。

Linear CLI

使用linear命令与Linear进行问题跟踪和项目管理交互。

范围

  • 用于通过CLI或GraphQL（linear gql）管理Linear问题/项目/团队。
  • 除非功能缺失，否则优先使用内置命令而非原始GraphQL。
  • 保持默认值与用户配置同步；不要硬编码团队ID/输出。

安装与设置

  • 安装：npm install -g @0xbigboss/linear-cli
  • 认证：linear auth set 或设置 LINEAR_API_KEY
  • 默认值：linear config set default_team_id TEAM_KEY，linear config set default_output json|table，linear config set default_state_filter completed,canceled
  • 检查或重置默认值：linear config show，linear config unset default_output
  • 配置路径：~/.config/linear/config.json（使用--config PATH或LINEAR_CONFIG覆盖）

前提条件

  • CLI已安装并在PATH中
  • 有效的Linear API密钥可用
  • 已设置团队默认值或在每个命令中提供（团队密钥/UUID）

规范

  • 分支：命名为{TICKET}-{short-name}（例如ENG-123-fix-auth）；对于并行工作，优先使用git worktrees
  • 提交：使用约定式提交；票据ID放在正文或尾部，而非主题中
  • 分配：开始工作时分配给自己（linear issue update ENG-123 --assignee me --yes）
  • 子问题：设置父级以关联相关工作（需要UUID：linear issue update ENG-123 --parent PARENT_UUID --yes）
  • 范围蔓延：为发现的工作创建单独的问题；使用阻塞关系链接（linear issue link ENG-123 --blocks ENG-456 --yes）
  • 周期/项目：创建问题时询问用户偏好

快速指南

列出我的问题

linear issues list --team TEAM_KEY --assignee me --human-time

搜索问题

linear search "keyword" --team TEAM_KEY --limit 10

创建问题

linear issue create --team TEAM_KEY --title "修复bug" --yes
# 返回标识符（例如ENG-123）

查看问题详情

linear issue view ENG-123

以JSON格式获取问题以便处理

linear issue view ENG-123 --json

获取完整上下文的问题（用于代理/分析）

linear issue view ENG-123 --fields identifier,title,state,assignee,priority,url,description,parent,sub_issues,comments --json

列出所有团队

linear teams list

验证认证

linear auth test

列出项目

linear projects list --limit 10

查看或更改CLI默认值

linear config show
linear config set default_output json
linear config unset default_state_filter

向问题添加评论

linear issue comment ENG-123 --body "评论内容在此" --yes

# 或从文件/stdin
cat notes.md | linear issue comment ENG-123 --body-file - --yes

创建和管理项目

# 创建项目（需要团队UUID）
linear project create --team TEAM_UUID --name "我的项目" --state planned --yes

# 更新项目状态
linear project update PROJECT_ID --state started --yes

# 向项目添加问题
linear project add-issue PROJECT_ID ISSUE_UUID --yes

命令参考

命令 用途
linear issues list 使用过滤器列出问题
linear search "keyword" 按文本搜索问题
linear issue view ID 查看单个问题
linear issue create 创建新问题
linear issue update ID 更新问题（分配、状态、优先级、父级*）
linear issue link ID 链接问题（阻塞、相关、重复）
linear issue comment ID 向问题添加评论
linear issue delete ID 归档问题
linear projects list 列出项目
linear project view ID 查看项目详情
linear project create 创建新项目
linear project update ID 更新项目（状态、名称、日期）
linear project delete ID 归档项目
linear project add-issue 向项目添加问题
linear project remove-issue 从项目移除问题
linear teams list 列出可用团队
linear me 显示当前用户
linear gql 运行原始GraphQL
linear help CMD 命令特定帮助

*--parent需要UUID，而非标识符。参见查找ID。

常用标志

  • --team ID\|KEY - 指定团队（大多数命令必需）
  • --json - 以JSON格式输出
  • --yes - 无需提示确认变更
  • --human-time - 显示相对时间戳
  • --fields LIST - 选择特定字段
  • --help - 显示命令帮助

工作流：创建和链接问题

注意：--parent需要UUID。使用linear issue view ID --json | jq -r '.issue.id'获取UUID

进度：
- [ ] 列出团队以获取TEAM_KEY：`linear teams list`
- [ ] 创建父级问题：`linear issue create --team KEY --title "Epic" --yes`
- [ ] 创建子级问题：`linear issue create --team KEY --title "Task" --yes`
- [ ] 获取父级UUID：`linear issue view PARENT_ID --json | jq -r '.issue.id'`
- [ ] 设置父级（需要UUID）：`linear issue update CHILD_ID --parent PARENT_UUID --yes`
- [ ] 创建另一个问题以链接：`linear issue create --team KEY --title "Blocked" --yes`
- [ ] 链接阻塞问题：`linear issue link ISSUE_ID --blocks OTHER_ID --yes`
- [ ] 验证：`linear issue view ISSUE_ID --json`

常见问题

问题 原因 解决方案
空结果 未指定团队 添加--team TEAM_KEY
401未授权 无效/缺失API密钥 运行linear auth test
变更无效 缺少确认 添加--yes标志
找不到问题 错误ID或缺少访问权限 issue view接受标识符或UUID；验证拼写和权限
–parent失败 使用标识符 --parent标志需要UUID，而非标识符

**ID格式摘要：**大多数命令接受标识符（ENG-123）。例外：--parent需要UUID。

高级操作

对于内置命令未涵盖的操作，使用linear gql配合GraphQL：

  • 添加附件 - 参见graphql-recipes.md → “向问题附加URL”
  • 上传文件 - 参见graphql-recipes.md → “上传文件”

注意：现在可通过linear issue comment添加评论。通过issue update --parent设置父级，但需要UUID。使用linear issue view ID --json获取UUID。

查找ID

重要：issue update --parent需要UUID。

# 从标识符获取问题UUID
linear issue view ENG-123 --json | jq -r '.issue.id'

# 当前用户UUID
linear me --json | jq -r '.viewer.id'

# 所有团队及其UUID
linear teams list --json

# 问题完整详情包括UUID
linear issue view ENG-123 --json

或在Linear应用中：Cmd/Ctrl+K → “复制模型UUID”

JSON输出结构

带有--json的命令返回嵌套结构。使用以下jq路径：

命令 根路径 项目路径
issue view ID .issue 不适用（单个对象）
issue view ID --fields ... . 不适用（所选字段的平面对象）
issues list .issues .issues.nodes[]
project view ID .project 不适用（单个对象）
projects list .projects .projects.nodes[]
teams list .teams .teams.nodes[]
me .viewer 不适用（单个对象）
search .issues .issues.nodes[]

**空值处理：**许多字段可能为空（名称、描述、日期、分配者）。使用空值安全过滤器。

jq模式

# 列出所有项目（正确路径）
linear projects list --json | jq '.projects.nodes[]'

# 按名称过滤项目（空值安全）
linear projects list --json | jq '.projects.nodes[] | select(.name) | select(.name | ascii_downcase | contains("keyword"))'

# 获取项目名称数组
linear projects list --json | jq '[.projects.nodes[].name]'

# 按标题过滤问题
linear issues list --team TEAM --json | jq '.issues.nodes[] | select(.title | ascii_downcase | contains("bug"))'

# 提取特定字段
linear issues list --team TEAM --json | jq '.issues.nodes[] | {id: .identifier, title, state: .state.name}'

# 从标识符获取问题UUID
linear issue view ENG-123 --json | jq -r '.issue.id'

常见错误：

  • 在根上使用.[] - 使用.projects.nodes[]或.issues.nodes[]
  • 在空值上使用test("pattern"; "i") - 首先使用select(.field)过滤空值
  • 在shell中转义!= - 使用select(.field)而非select(.field != null)

参考文件

  • graphql-recipes.md - 用于附件、关系、评论、文件上传的GraphQL变更
  • troubleshooting.md - 常见错误和调试步骤

外部链接