linear-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Linear CLI

Interact with the Linear issue tracker from the command line. The primary use cases are:

Starting tasks from issues -- fetch an issue by ID, read its description, and begin work
Searching/listing issues -- find issues by state, assignee, team, or free-text search
Viewing issue details -- read full descriptions, comments, and metadata
Updating issue state -- mark issues as started, add comments with progress

从命令行与Linear问题追踪工具交互。主要使用场景包括：

从问题启动任务——通过ID获取问题，阅读其描述并开始工作
搜索/列出问题——按状态、经办人、团队或自由文本搜索查找问题
查看问题详情——阅读完整描述、评论和元数据
更新问题状态——标记问题为已启动，添加进度评论

Setup

安装与配置

Install

安装

bash

brew install schpet/tap/linear

bash

brew install schpet/tap/linear

Authenticate

身份验证

Create an API key at https://linear.app/settings/account/security (requires member access, not guest)
Run
```
linear auth login
```
and paste the key when prompted
Verify:
```
linear auth whoami
```

在https://linear.app/settings/account/security创建API密钥（需要成员权限，访客权限不可用）
运行
```
linear auth login
```
，并在提示时粘贴密钥
验证：
```
linear auth whoami
```

Configure for this repo

为当前仓库配置

bash

linear config

This writes a

.linear.toml

in the repo root with the team ID and workspace slug. The file is checked into git so all agents and developers share the same config.

bash

linear config

此命令会在仓库根目录写入一个

.linear.toml

文件，包含团队ID和工作区别名。该文件会被提交到git，以便所有Agent和开发人员共享相同配置。

Starting a Task from an Issue

从问题启动任务

When given an issue ID (e.g.

ENG-123

bash

undefined

当提供问题ID（例如

ENG-123

）时：

bash

undefined

Read the full issue -- description, state, assignee, labels, comments

查看完整问题——描述、状态、经办人、标签、评论

linear issue view ENG-123

Get just the title (useful for branch names or commit messages)

仅获取标题（适用于分支名称或提交信息）

linear issue title ENG-123

Get the Linear URL

获取Linear链接

linear issue url ENG-123


The agent should read the issue description to understand requirements before starting implementation.

linear issue url ENG-123


Agent应先阅读问题描述，明确需求后再开始实现。

Task Lifecycle

任务生命周期

On start: Move the issue to "In Progress" immediately when beginning implementation.

bash

linear issue update ENG-123 -s started

启动时：开始实现后立即将问题状态改为“进行中”。

bash

linear issue update ENG-123 -s started

or via GraphQL if CLI fails (see Updating Issues below)

若CLI执行失败，可通过GraphQL更新（见下方“更新问题”部分）


**On deploy to production**: Move to "In Review" only after the deploy has fully completed and the change is live on production. Never update Linear state speculatively or immediately after pushing — a reviewer loading the issue will open the production site, which must already reflect the change.

The required sequence:
1. Push to telecine main (or merge PR)
2. **Block** on `scripts/wait-for-telecine-action` until the deploy job completes successfully
3. Only then move to "In Review" and add a comment

```bash


**部署到生产环境时**：仅在部署完全完成且变更已上线到生产环境后，再将状态改为“审核中”。切勿在推送代码后立即或推测性地更新Linear状态——审核者查看问题时会访问生产站点，此时站点必须已体现相关变更。

要求的流程：
1. 推送到telecine main分支（或合并PR）
2. 等待`scripts/wait-for-telecine-action`脚本执行完成，直到部署任务成功
3. 仅在此之后将状态改为“审核中”并添加评论

```bash

From monorepo/ — MUST complete before touching Linear

从monorepo/目录执行——必须完成此步骤后再操作Linear

scripts/wait-for-telecine-action

Then move to In Review

然后改为审核中状态

linear api <<'GRAPHQL' mutation { issueUpdate(id: "EF2-123", input: { stateId: "2717b5fe-9ea0-429f-8edd-cf8eabe0551d" }) { success } } GRAPHQL

linear issue comment add EF2-123 -b "Deployed to production. <one-line summary of what changed>"


The comment should be a single sentence describing what was implemented or fixed, not a list of commits.

linear api <<'GRAPHQL' mutation { issueUpdate(id: "EF2-123", input: { stateId: "2717b5fe-9ea0-429f-8edd-cf8eabe0551d" }) { success } } GRAPHQL

linear issue comment add EF2-123 -b "已部署到生产环境。<变更内容的单行摘要>"


评论应为单句，描述已实现或修复的内容，而非提交记录列表。

Searching and Listing Issues

搜索与列出问题

bash

undefined

bash

undefined

List unstarted issues assigned to you (default)

列出分配给你的未启动问题（默认）

--sort is required: manual or priority (NOT "updated")

--sort为必填项：manual或priority（不可为"updated"）

linear issue list --sort priority

List issues in a specific state

列出特定状态的问题

linear issue list -s started --sort priority linear issue list -s backlog --sort priority linear issue list --all-states --sort priority

List issues for all assignees

列出所有经办人的问题

linear issue list -A --sort priority

List unassigned issues

列出未分配的问题

linear issue list -U --sort priority

Filter by project -- requires exact name match; use GraphQL if not found

按项目筛选——需完全匹配项目名称；若未找到，使用GraphQL

linear issue list --project "Project Name" --sort priority --team ENG

Filter by team (required if no .linear.toml in repo)

按团队筛选（若仓库中无.linear.toml则为必填）

linear issue list --team ENG --sort priority

Limit results

限制结果数量

linear issue list --limit 10 --sort priority

undefined

linear issue list --limit 10 --sort priority

undefined

List issues in a project via GraphQL (preferred for project browsing)

通过GraphQL列出项目中的问题（浏览项目时优先使用）

The CLI

--project

filter is fragile (exact name match, requires team). Use GraphQL instead:

bash

undefined

CLI的

--project

筛选功能存在局限性（需完全匹配名称，且需要指定团队）。建议改用GraphQL：

bash

undefined

First find the project ID

先查找项目ID

linear api <<'GRAPHQL' query { projects(first: 50) { nodes { id name } } } GRAPHQL

Then fetch its issues

然后获取该项目的问题

linear api <<'GRAPHQL' query { project(id: "<id>") { issues(first: 50) { nodes { identifier title state { name } assignee { name } priority } } } } GRAPHQL

undefined

linear api <<'GRAPHQL' query { project(id: "<id>") { issues(first: 50) { nodes { identifier title state { name } assignee { name } priority } } } } GRAPHQL

undefined

Free-text search via GraphQL

通过GraphQL进行自由文本搜索

The CLI doesn't have a built-in search command, but the

api

subcommand exposes the full GraphQL API:

bash

linear api --variable term="onboarding" <<'GRAPHQL'
query($term: String!) {
  searchIssues(term: $term, first: 20) {
    nodes { identifier title state { name } assignee { name } }
  }
}
GRAPHQL

Pipe to

jq

for filtering:

bash

linear api --variable term="bug" <<'GRAPHQL'
query($term: String!) {
  searchIssues(term: $term, first: 20) {
    nodes { identifier title state { name } }
  }
}
GRAPHQL

CLI没有内置搜索命令，但

api

子命令可调用完整的GraphQL API：

bash

linear api --variable term="onboarding" <<'GRAPHQL'
query($term: String!) {
  searchIssues(term: $term, first: 20) {
    nodes { identifier title state { name } assignee { name } }
  }
}
GRAPHQL

可通过

jq

进行过滤：

bash

linear api --variable term="bug" <<'GRAPHQL'
query($term: String!) {
  searchIssues(term: $term, first: 20) {
    nodes { identifier title state { name } }
  }
}
GRAPHQL

Updating Issues

更新问题

bash

undefined

bash

undefined

Mark as started (sets state to "In Progress")

标记为已启动（状态改为“进行中”）

NOTE: linear issue update fails with "Could not determine team key from issue ID"

注意：对于非标准前缀（如EF2-123），linear issue update会提示"Could not determine team key from issue ID"

for non-standard prefixes (e.g. EF2-123). Use GraphQL mutation instead (see below).

此时请改用GraphQL变更（见下方）

linear issue update ENG-123 -s started

Update title or description

更新标题或描述

linear issue update ENG-123 -t "New title" linear issue update ENG-123 --description-file /tmp/desc.md

Add a comment

添加评论

linear issue comment add ENG-123 -b "Started implementation"

For multi-line markdown comments, use a file

若添加多行markdown评论，请使用文件

linear issue comment add ENG-123 --body-file /tmp/comment.md

undefined

linear issue comment add ENG-123 --body-file /tmp/comment.md

undefined

Update issue state via GraphQL (when CLI update fails)

通过GraphQL更新问题状态（当CLI更新失败时）

bash

undefined

bash

undefined

Find the state ID first

先查找状态ID

linear api <<'GRAPHQL' query { workflowStates(filter: { name: { eq: "Done" } }) { nodes { id name team { key } } } } GRAPHQL

Then update one or more issues in a single mutation

然后在单个变更中更新一个或多个问题

linear api <<'GRAPHQL' mutation { issueUpdate(id: "EF2-123", input: { stateId: "<state-id>" }) { success } } GRAPHQL

Batch update multiple issues

批量更新多个问题

linear api <<'GRAPHQL' mutation { a: issueUpdate(id: "EF2-436", input: { stateId: "<state-id>" }) { success } b: issueUpdate(id: "EF2-435", input: { stateId: "<state-id>" }) { success } } GRAPHQL

undefined

linear api <<'GRAPHQL' mutation { a: issueUpdate(id: "EF2-436", input: { stateId: "<state-id>" }) { success } b: issueUpdate(id: "EF2-435", input: { stateId: "<state-id>" }) { success } } GRAPHQL

undefined

Creating Issues

创建问题

bash

undefined

bash

undefined

Interactive (prompts for details)

交互式（提示输入详情）

linear issue create

Non-interactive

非交互式

linear issue create -t "Fix rendering bug" --description-file /tmp/desc.md -a self -s unstarted

Create and immediately start working

创建后立即开始工作

linear issue create -t "Investigate flaky test" --start


Always use `--description-file` or `--body-file` for multi-line markdown content to avoid shell escaping issues.

linear issue create -t "Investigate flaky test" --start


对于多行markdown内容，始终使用`--description-file`或`--body-file`，以避免shell转义问题。

Discovering CLI Options

查看CLI选项

Every command supports

--help

bash

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

The CLI has extensive subcommands beyond issues --

linear team

linear project

linear document

linear label

linear milestone

. Run

--help

on any of them.

每个命令都支持

--help

：

bash

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

CLI除了issue相关子命令外，还有更多扩展子命令——

linear team

、

linear project

、

linear document

、

linear label

、

linear milestone

。可对任意子命令执行

--help

查看详情。

Workspace Reference

工作区参考

Use these IDs directly in mutations — no need to query for them first.

可直接在变更中使用以下ID，无需提前查询。

Users

用户

Name	ID
Collin Miller	`7fa0b8f1-b1d2-462a-8edd-5365fb5e1d4a`
Jeremy Yudkin	`12ae7fdb-6af1-45fd-b656-a1052b387605`

姓名	ID
Collin Miller	`7fa0b8f1-b1d2-462a-8edd-5365fb5e1d4a`
Jeremy Yudkin	`12ae7fdb-6af1-45fd-b656-a1052b387605`

Workflow States (team: EF2)

工作流状态（团队：EF2）

State	ID	Type
Backlog	`deceb52d-a969-493a-974c-228d0e595e08`	backlog
Todo	`fb95e2be-9938-42bf-8248-276d4b1af951`	unstarted
In Progress	`ac7b4c8f-d2a9-4e74-a9ff-392506703bd2`	started
In Review	`2717b5fe-9ea0-429f-8edd-cf8eabe0551d`	started
Done	`5fcec8c5-d69d-4cf4-bcad-e73654b2fae2`	completed
Canceled	`1fbe9606-44eb-486c-8521-daf848673435`	canceled
Duplicate	`ec2113c9-0b49-407a-82e1-3d1f39c7037a`	canceled

状态	ID	类型
Backlog	`deceb52d-a969-493a-974c-228d0e595e08`	backlog
Todo	`fb95e2be-9938-42bf-8248-276d4b1af951`	unstarted
In Progress	`ac7b4c8f-d2a9-4e74-a9ff-392506703bd2`	started
In Review	`2717b5fe-9ea0-429f-8edd-cf8eabe0551d`	started
Done	`5fcec8c5-d69d-4cf4-bcad-e73654b2fae2`	completed
Canceled	`1fbe9606-44eb-486c-8521-daf848673435`	canceled
Duplicate	`ec2113c9-0b49-407a-82e1-3d1f39c7037a`	canceled

Projects

项目

Name	ID	State
Editframe 2026 Launch / Bug Fixes	`b43b5d1d-8431-4e19-b4ae-c05760c02996`	planned
App and Dashboard For Launch	`5fbea590-482f-4fcd-89f3-b0e581e43546`	started
Demo Improvements (Pre Launch)	`6c616f08-8bc9-4f8c-9109-26863099ffc3`	started
Dev Rel Catnip	`90b4643c-9b09-43fc-8fd8-9e78de7669a5`	started
Bug Fixes	`9c2beb23-32c3-4c24-a896-ca69eb99da49`	started
Clean Slate Task Collection	`12e632b9-6ce7-4a06-8403-46b419e3f649`	started
Docs/Site Feedback (2025)	`4ccf4054-9b6a-4ccf-85e6-088fe60851e4`	started
EF - Rendering Improvements	`fd8a3df6-e174-41ee-a7f2-b7d49bca6094`	backlog
EF - Preview Improvements	`4772c169-6f0f-4c01-b408-801ebd49bb3a`	backlog
Launch Documentation Beta	`f8babb39-f732-4611-999e-f7db4d0aa48c`	backlog
Stack Trace Project	`e2f37910-6a4f-4f45-a877-889c62526e6b`	planned

名称	ID	状态
Editframe 2026 Launch / Bug Fixes	`b43b5d1d-8431-4e19-b4ae-c05760c02996`	planned
App and Dashboard For Launch	`5fbea590-482f-4fcd-89f3-b0e581e43546`	started
Demo Improvements (Pre Launch)	`6c616f08-8bc9-4f8c-9109-26863099ffc3`	started
Dev Rel Catnip	`90b4643c-9b09-43fc-8fd8-9e78de7669a5`	started
Bug Fixes	`9c2beb23-32c3-4c24-a896-ca69eb99da49`	started
Clean Slate Task Collection	`12e632b9-6ce7-4a06-8403-46b419e3f649`	started
Docs/Site Feedback (2025)	`4ccf4054-9b6a-4ccf-85e6-088fe60851e4`	started
EF - Rendering Improvements	`fd8a3df6-e174-41ee-a7f2-b7d49bca6094`	backlog
EF - Preview Improvements	`4772c169-6f0f-4c01-b408-801ebd49bb3a`	backlog
Launch Documentation Beta	`f8babb39-f732-4611-999e-f7db4d0aa48c`	backlog
Stack Trace Project	`e2f37910-6a4f-4f45-a877-889c62526e6b`	planned

When to Use This Skill

何时使用此技能

User provides a Linear issue ID and wants to begin work on it
User asks to find or search for Linear issues
User wants to see what's assigned to them or what's in a specific state
User asks to update an issue's status or add a comment
Agent needs to read issue requirements before starting implementation

用户提供Linear问题ID并希望开始处理该问题
用户要求查找或搜索Linear问题
用户希望查看分配给自己的问题或特定状态的问题
用户要求更新问题状态或添加评论
Agent需要在开始实现前阅读问题需求