Linear CLI

linear cli

一个用于在 linear 问题跟踪器中列出、开始和创建问题的 CLI。支持 git 和 jj，帮助你在 Linear 中进入正确的视图。还可以像 gh 一样跳转到网页或 Linear 桌面应用。

非常适合与 AI Agent 搭配使用 — CLI 内置了一个 技能，可让 Agent 创建问题、更新状态，并在处理代码的同时管理你的 Linear 工作流。

工作方式如下：

linear config               # setup your repo, it writes a config file

linear issue list           # list unstarted issues assigned to you
linear issue query --all-teams  # query issues across all teams
linear issue query --search "login bug"  # search issues in your configured team
linear issue start          # choose an issue to start, creates a branch
linear issue start ABC-123  # start a specific issue
linear issue view           # see current branch's issue as markdown
linear issue pr             # makes a PR with title/body preset, using gh cli
linear issue create         # create a new issue

它旨在作为网页和桌面应用的补充，让你通过交互式或脚本化的方式留在命令行中。

录屏演示

linear issue create -i

linear issue start

安装

homebrew

brew install schpet/tap/linear

npm / bun / pnpm

将其安装为开发依赖项，以便在项目中固定版本：

npm install -D @schpet/linear-cli
# or
bun add -D @schpet/linear-cli
# or
pnpm add -D @schpet/linear-cli

然后通过包管理器运行：

npx linear issue list
bunx linear issue list

注意： 此包提供预构建二进制文件

npm 包：​@schpet/linear-cli

Shell 安装程序

适用于 macOS 和 Linux：

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/schpet/linear-cli/releases/latest/download/linear-installer.sh | sh

二进制文件

https://github.com/schpet/linear-cli/releases/latest

从源代码安装

安装好 Rust 工具链后：

cargo install --locked --git https://github.com/schpet/linear-cli linear

从 2.x 升级？请参阅变更日志中的从 2.x 升级。

设置

1. 在 linear.app/settings/account/security 创建 API 密钥¹

2. 使用 CLI 进行身份验证：

   linear auth login
   

3. 配置项目：

   cd my-project-repo
   linear config
   

有关多工作区支持和其他身份验证选项，请参阅 docs/authentication.md。

此 CLI 同时支持 git 和 jj 版本控制系统：

• git：分支名称中包含 Linear 问题 ID 时效果最佳（例如 eng-123-my-feature）。使用 linear issue start 或 Linear UI 的“copy git branch name”按钮，以及相关自动化。
• jj：通过提交说明中的 Linear-issue trailers 检测问题。使用 linear issue start 自动添加 trailer，或使用 jj describe 手动添加，例如 jj describe "$(linear issue describe ABC-123)"

命令

问题命令

当前问题由以下内容确定：

• git：当前分支名称中的问题 ID（例如 eng-123-my-feature）
• jj：当前提交或祖先提交中的 Linear-issue trailer

请注意，Linear 的 GitHub 集成会建议 git 分支名称。

linear issue view      # view current issue details in terminal
linear issue view ABC-123
linear issue view 123
linear issue view -w   # open issue in web browser
linear issue view -a   # open issue in Linear.app
linear issue id        # prints the issue id from current branch (e.g., "ENG-123")
linear issue title     # prints just the issue title
linear issue url       # prints the Linear.app URL for the issue
linear issue pr        # creates a GitHub PR with issue details via `gh pr create`
linear issue list      # list your issues in a table view (supports -s/--state and --sort)
linear issue list --project "My Project" --milestone "Phase 1"  # filter by milestone
linear issue list -w   # open issue list in web browser
linear issue list -a   # open issue list in Linear.app
linear issue query --search "login bug"  # search issues by text in your configured team
linear issue query --search "oauth timeout" --team ENG --json  # structured search output for agents
linear issue query --team "Engineering" --state "In Review" --json  # teams by key, name, or ID; states by type, name, or ID
linear issue query --all-teams --json --limit all  # export all issues as JSON
linear issue start     # create/switch to issue branch and mark as started
linear issue create    # create a new issue, asking for the title
linear issue create -i # create a new issue, asking for every field
linear issue create -t "title" -d "description"  # create with flags
linear issue create --project "My Project" --milestone "Phase 1"  # create with milestone
linear issue create --template "Bug report" -t "Login fails"  # create from a template (see template commands)
linear issue update ENG-123 -s started  # change only the fields you pass
linear issue update ENG-123 --milestone "Phase 2"  # set milestone on existing issue
linear issue update ENG-123 --clear-due-date --clear-parent  # remove values (also --clear-estimate, --clear-project, --clear-milestone, --clear-cycle, --unassign)
linear issue archive ENG-123 --yes  # archive an issue (Linear normally auto-archives closed issues; see docs/usage.md)
linear issue archive --yes --bulk ENG-123 ENG-124  # archive several issues
linear issue delete    # delete an issue
linear issue comment list          # list comments on current issue
linear issue comment add           # add a comment to current issue
linear issue comment add --reply-to <id>   # reply to a comment (-p / --parent are aliases)
linear issue comment list --json   # comments as JSON, with quotedText and parent for inline comments and replies
linear issue comment update <id>   # update a comment
linear issue commits               # show all commits for an issue (jj only)

附加文件

将文件附加到问题或评论。上传的文件默认是私有的（仅工作区成员可读），与 Linear 网页应用的行为一致。

linear issue attach ENG-123 ./screenshot.png            # attach a file to an issue
linear issue attach ENG-123 ./doc.pdf -t "Spec"         # custom attachment title
linear issue attach ENG-123 ./img.png -c "see this"     # add a linked comment
linear issue comment add ENG-123 -a ./screenshot.png    # attach a file to a comment
linear issue comment add ENG-123 -a ./a.png -a ./b.png  # attach multiple files

附件默认是私有的。传入 --public 可将栅格图像（png/jpeg/gif/webp/bmp/tiff）上传到公开的 public.linear.app URL，任何人都可在未经身份验证的情况下读取 — 适合在工作区外分享，但由于这会绕过工作区访问控制，因此会显示警告。非图像文件无法设为公开。

linear issue attach ENG-123 ./screenshot.png --public           # public image URL
linear issue comment add ENG-123 -a ./screenshot.png --public   # public image URL

团队命令

linear team list       # list teams
linear team list --json  # as JSON, e.g. to map a team name to its key or id in scripts
linear team id         # print the configured team key (e.g. for scripts)
linear team members    # list team members
linear team members --all --json  # include inactive members, as JSON
linear team create     # create a new team
linear team autolinks  # configure GitHub repository autolinks for Linear issues

用户命令

linear user list        # list everyone in the workspace
linear user list --all  # include deactivated members
linear user list --json # machine-readable output

项目命令

linear project list    # list projects
linear project view https://linear.app/acme/project/mobile-launch-272f50ef9250  # paste a URL from Linear
linear project view    # pick from a searchable list of projects
linear project view <projectId>   # overview, milestones, resources, documents, related projects
linear project view "Mobile launch"   # a UUID, slug ID, or exact name all work
linear project view <projectId> --json  # project details as JSON
linear project create --name "API v2" --team ENG --content-file overview.md
linear project create --name "Mobile launch" --team APP --priority high --label Launch --member [email protected]
linear project create --name "Q3 launch" --team APP --template "Kickoff"  # create from a project template
linear project update <projectId> --content-file overview.md  # replace the project's overview body
linear project update <projectId> --clear-lead --clear-target-date  # remove values (also --clear-start-date)
linear project update <projectId> --add-team OPS --remove-label Launch --add-initiative "Q4 Bets"  # change teams, labels, initiatives incrementally
linear project update <projectId> --team ENG --team OPS   # replace the whole team set (--label and --initiative replace likewise)
linear project comment list <project>                         # list the project's discussion thread (UUID, slug, or name)
linear project comment add <project> --body "Kickoff Monday"  # comment on a project
linear project comment add <project> --body "+1" --reply-to <commentId>  # reply in a thread

计划命令

linear initiative list                                            # list initiatives
linear initiative view <initiative>                               # view an initiative (UUID, slug, or name)
linear initiative comment list <initiative>                       # list the initiative's discussion thread
linear initiative comment add <initiative> --body-file note.md   # comment on an initiative
linear initiative comment add <initiative> --body "+1" --reply-to <commentId>  # reply in a thread

周期命令

linear cycle list --team ENG          # list a team's cycles (--team takes a key, name, or ID)
linear cycle list --team ENG --json   # as JSON
linear cycle view 12 --team ENG       # view a cycle by number or name
linear cycle view 12 --team ENG --json  # cycle details and its issues, as JSON

里程碑命令

linear milestone list --project <projectId>     # list milestones for a project
linear m list --project <projectId>             # list milestones (alias)
linear milestone list --project <projectId> --json  # as JSON
linear milestone view <milestoneId>             # view milestone details
linear m view <milestoneId>                     # view milestone (alias)
linear milestone view <milestoneId> --all       # list every issue, not just the first 10
linear milestone view <milestoneId> --json      # milestone with every issue, as JSON
linear milestone create --project <projectId> --name "Q1 Goals" --target-date "2026-03-31"  # create a milestone
linear m create --project <projectId>           # create a milestone, asking for its name
linear milestone update <milestoneId> --name "New Name"  # update milestone name
linear m update <milestoneId> --target-date "2026-04-15"  # update target date
linear milestone delete <milestoneId>           # delete a milestone
linear m delete <milestoneId> --yes             # delete without confirmation

文档命令

从命令行管理 Linear 文档。每份文档都必须且只能关联到一个目标：项目、问题、计划、团队、周期或发布（Linear 的 API 要求如此）。

# list documents
linear document list                            # list all accessible documents
linear docs list                                # alias for document
linear document list --project <project>        # filter by project (UUID, slug ID, or name)
linear document list --issue TC-123             # filter by issue
linear document list --team ENG                 # filter by team
linear document list --initiative <initiative>  # filter by initiative
linear document list --team ENG --cycle active  # filter by cycle (team scopes the lookup)
linear document list --release <release>        # filter by release (UUID, name, or version)
linear document list --json                     # output as JSON

# view a document
linear document view <slug>                     # view document rendered in terminal
linear document view <slug> --raw               # output raw markdown (for piping)
linear document view <slug> --web               # open in browser
linear document view <slug> --json              # output as JSON, including document comments

# comment on a document
linear document comment list <slug>             # list comments; inline comments show the text they quote
linear document comment list <slug> --json      # comments as JSON (quotedText, parent, ...)
linear document comment add <slug> --body "Looks good"              # add a top-level comment
linear document comment add <slug> --body-file note.md --reply-to <commentId>  # reply in a thread

# create a document (exactly one attachment target is required)
linear document create --title "Doc" --project <project>              # attach to project
linear document create --title "Notes" --issue TC-123                 # attach to issue
linear document create --title "Handbook" --team ENG                  # attach to team
linear document create --title "Brief" --initiative <initiative>      # attach to initiative
linear document create --title "Sprint" --team ENG --cycle next       # attach to cycle
linear document create --title "Notes" --release 2026.8               # attach to release
linear document create --title "Spec" --content-file ./spec.md --project <project>  # content from file
cat spec.md | linear document create --title "Spec" --project <project>             # content from stdin

# update a document
linear document update <slug> --title "New Title"                     # update title
linear document update <slug> --content-file ./updated.md             # update content
linear document update <slug> --edit                                  # open in $EDITOR
linear document update <slug> --team ENG                              # re-point attachment (replaces current)
linear document update <slug> --content-file ./updated.md --force     # bypass comment-anchor guard

# delete a document
linear document delete <slug>                   # soft delete (move to trash)
linear document delete --bulk <slug1> <slug2>   # bulk delete

默认情况下，如果文档有未解决的 Linear 行内评论，系统会拒绝更新内容，因为替换 Markdown 可能会使这些评论锚点脱离或隐藏。文档顶层评论不会阻止更新。请先查看行内评论，然后在确实想替换内容时，使用 --force 重新运行。

模板命令

linear template list                       # every issue, project, and document template in the workspace
linear template list --type issue --team ENG  # ENG's issue templates plus workspace-level ones
linear template list --json                # the raw template objects (templateData is a JSON-encoded string)
linear template view "Bug report"          # what the template pre-fills: title, priority, labels, body, sub-issues, ...
linear template view <template-id> --json  # raw GraphQL object; `jq '.templateData | fromjson'` decodes the data

# apply a template on create (name or ID). Linear fills the template in server-side.
linear issue create --team ENG --template "Bug report"                    # the template supplies the title
linear issue create --team ENG --template "Bug report" -t "Login fails" -l security  # flags override, labels merge
linear project create --name "Q3 launch" --team APP --template "Kickoff"

--template 会替代团队的默认模板，因此无需使用 --no-use-default-template（两者同时传入也可以）。你显式传入的任何内容都会覆盖模板中的对应值；--label 会与模板的标签合并；--description 会替换模板正文，因此若要保留正文，请不要传入该选项。可以列出和查看文档模板，但 Linear 的 API 不支持在创建文档时应用模板。

其他命令

linear --help          # show all commands
linear --version       # show version
linear config          # setup the project
linear completions     # generate shell completions

配置选项

CLI 支持通过环境变量或 .linear.toml 配置文件进行配置。环境变量的优先级高于配置文件中的值。

选项	环境变量	TOML 键	示例	描述
团队 ID	LINEAR_TEAM_ID	team_id	"ENG"	操作的默认团队
工作区	LINEAR_WORKSPACE	workspace	"mycompany"	Web/App URL 使用的工作区 slug
问题排序	LINEAR_ISSUE_SORT	issue_sort	"priority" 或 "manual"	问题列表的排序方式
询问项目	LINEAR_ISSUE_CREATE_ASK_PROJECT	issue_create_ask_project	true 或 false	交互式 issue create 过程中询问所属项目
指派给自己	LINEAR_ISSUE_CREATE_ASSIGN_SELF	issue_create_assign_self	"always"、"auto" 或 "never"	控制创建问题时是否默认将问题指派给自己
版本控制系统	LINEAR_VCS	vcs	"git" 或 "jj"	版本控制系统（默认：git）
下载图片	LINEAR_DOWNLOAD_IMAGES	download_images	true 或 false	查看问题时下载图片
PR 模板	LINEAR_PR_TEMPLATE	pr_template	".github/pull_request_template.md"	issue pr 正文使用的模板文件（会附加 Linear 问题 URL；使用 --no-template 跳过）

设置会从两个配置文件中读取：项目文件和全局文件。每个选项都按以下顺序使用找到的第一个值：

1. 命令行标志（如果该命令支持）
2. 环境变量，来自 Shell 或 .env 文件（Shell 中的值优先）
3. 项目配置文件：依次查找 ./linear.toml、./.linear.toml，然后是仓库根目录下的 linear.toml、.linear.toml 或 .config/linear.toml
4. 全局配置文件：macOS 和 Linux 上的 $XDG_CONFIG_HOME/linear/linear.toml（或 ~/.config/linear/linear.toml），Windows 上的 %APPDATA%\linear\linear.toml

因此，全局文件可以存放 issue_sort 等默认值，而仓库的 .linear.toml 可以为该项目覆盖这些值。所有值都会经过验证，即使它们被更高优先级的配置覆盖也不例外；无效值会报错，并指出其所在的文件和键。

退出状态

脚本可以根据退出状态判断命令失败的原因，而无需解析错误消息：

状态	含义
0	成功
1	其他任何失败，包括 GraphQL 错误，例如 linear api 中的无效查询
2	用法错误：标志或值无效，在发送任何内容到 Linear 之前就被拒绝
3	未找到：命令查找的问题、团队、项目或其他实体不存在
4	身份验证：没有可用的 API 密钥，或 Linear 拒绝了该密钥（已撤销、输入错误或缺少访问权限）
5	服务不可用：无法连接到 Linear、请求超时、请求受到速率限制，或服务器出错。稍后重试可能会成功，但创建或更新操作仍可能已生效
130	在提示或编辑器中取消

因多种原因失败的批量命令（--bulk）会退出并返回其中优先级最高的状态：4、5、1、3。因此，3 表示所有失败都是因为项目不存在。linear --help 也会列出这些状态。

技能

linear-cli 附带一项帮助 AI Agent 高效使用 CLI 的技能。对于 CLI 以外的用例，它还包含直接与 GraphQL API 交互的说明，包括身份验证。

claude code

使用 claude code 的插件系统安装该技能：

# from claude code
/plugin marketplace add schpet/linear-cli
/plugin install linear-cli@linear-cli

# from bash
claude plugin marketplace add schpet/linear-cli
claude plugin install linear-cli@linear-cli

# to update
claude plugin marketplace update linear-cli
claude plugin update linear-cli@linear-cli

面向其他 Agent 的 skills.sh

使用 skills.sh 安装该技能：

npx skills add schpet/linear-cli

查看 skills.sh/schpet/linear-cli/linear-cli 上的技能

开发

linear-cli 使用 rust 编写；工具链版本固定在 rust-toolchain.toml 中。常见任务见 justfile：

just dev issue list   # run the cli from source (cargo run -- issue list)
just install          # install this checkout as `linear`
just check            # cargo fmt --check, clippy, and tests, as CI runs them

更新技能文档

技能的命令列表和 skills/linear-cli/references/ 根据 CLI 的帮助信息生成。编辑 skills/linear-cli/SKILL.template.md，然后重新生成：

just skill-docs

更新 GraphQL 架构

graphql/schema.graphql 是 Linear 的 API 架构，用于在编译时对每个查询进行类型检查。使用已登录的 CLI 刷新它：

just sync-schema

缘由

Linear 的 UI 非常出色，但它拖慢了我的速度。以下这些情况经常让我觉得很烦：

• 从代码仓库切换到 Linear
• 打开 Linear 时没有进入正确的视图
• Linear 建议了一个 git 分支，但创建或切换到该分支的工作还得由我来做
• Linear 建议的 git 分支没有考虑该分支是否已存在，或是否已有合并的拉取请求

这个 CLI 解决了这些问题。它知道你在做什么（通过 git 分支或 jj 提交尾注），会管理你的版本控制状态，还会帮你填写拉取请求详情。

Footnotes

1. 创建 API 密钥需要成员访问权限，访客账户无法使用此功能。 ↩