Back to Details

pp-linear

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Linear - Printing Press CLI

Linear - Printing Press CLI

Prerequisites: Install the CLI

前提条件：安装CLI

This skill drives the 
linear-pp-cli
binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:
  1. Install via the Printing Press installer (use the 
    cli-only
    flag to skip the MCP component): <!-- npx -y @mvanhorn/printing-press install linear cli-only --> 
    npx -y @mvanhorn/printing-press install linear cli-only
  2. Verify: 
    linear-pp-cli --version
  3. Ensure 
    $GOPATH/bin
    (or 
    $HOME/go/bin
    ) is on 
    $PATH
    .
If the 
npx
install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.23+):
bash
go install github.com/mvanhorn/printing-press-library/library/project-management/linear/cmd/linear-pp-cli@latest
If 
--version
reports "command not found" after install, the install step did not put the binary on 
$PATH
. Do not proceed with skill commands until verification succeeds.
本技能驱动
linear-pp-cli
二进制文件。在调用本技能的任何命令之前，必须先验证CLI已安装。如果未安装，请先执行以下步骤：
  1. 通过Printing Press安装程序进行安装（使用
    cli-only
    标志跳过MCP组件）： <!-- npx -y @mvanhorn/printing-press install linear cli-only --> 
    npx -y @mvanhorn/printing-press install linear cli-only
  2. 验证安装：
    linear-pp-cli --version
  3. 确保
    $GOPATH/bin
    （或
    $HOME/go/bin
    ）已添加到
    $PATH
    环境变量中。
如果
npx
安装失败（如无Node环境、离线等情况），可回退到直接使用Go安装（需要Go 1.23及以上版本）：
bash
go install github.com/mvanhorn/printing-press-library/library/project-management/linear/cmd/linear-pp-cli@latest
如果安装后执行
--version
提示“command not found”，说明安装步骤未将二进制文件添加到
$PATH
中。请在验证成功前不要继续执行技能命令。

When to Use This CLI

何时使用本CLI

Reach for this when the user wants:
  • a fast "what's on my plate today" view across teams (
    today
    , 
    me
    )
  • find or look up a specific issue by identifier (
    issues ESP-1155
    )
  • list issues assigned to them or a teammate, filtered by team / state (
    issues list --assignee me --state started
    )
  • sprint velocity / team workload / bottleneck analysis (
    velocity
    , 
    workload
    , 
    load
    , 
    bottleneck
    )
  • find stale issues, duplicates, or orphaned items (
    stale
    , 
    similar
    , 
    orphans
    )
  • search across issues, projects, and cycles offline (
    sync
    once, then 
    similar
    hits SQLite)
  • list or inspect projects, cycles, milestones, roadmaps, initiatives, releases
  • create / update issues, projects, or cycles (via the typed subcommands and 
    workflow
    )
  • export Linear data to JSONL for backup or migration
  • stream live changes without polling the web UI (
    tail
    )
  • run read-only SQL against the synced store (
    sql
    for power users)
Trigger phrases: "what's assigned to me", "look up issue ABC-123", "find my Linear tickets", "what's on my plate", "show me my Linear queue".
Skip it when the user wants to configure team settings, integrations, or OAuth apps; those admin surfaces live in the Linear web admin.
当用户有以下需求时，可使用本工具：
  • 快速查看跨团队的“今日待办事项”（
    today
    、
    me
    命令）
  • 通过标识符查找或查看特定问题（
    issues ESP-1155
    ）
  • 列出分配给自己或队友的问题，并按团队/状态筛选（
    issues list --assignee me --state started
    ）
  • 迭代速度/团队工作量/瓶颈分析（
    velocity
    、
    workload
    、
    load
    、
    bottleneck
    命令）
  • 查找陈旧问题、重复问题或孤立条目（
    stale
    、
    similar
    、
    orphans
    命令）
  • 离线搜索问题、项目和迭代周期（先执行
    sync
    ，之后
    similar
    命令会读取SQLite数据库）
  • 列出或查看项目、迭代周期、里程碑、路线图、行动计划、发布版本
  • 创建/更新问题、项目或迭代周期（通过类型化子命令和
    workflow
    ）
  • 将Linear数据导出为JSONL格式用于备份或迁移
  • 无需轮询Web UI即可实时流变更（
    tail
    命令）
  • 对同步后的存储执行只读SQL查询（面向高级用户的
    sql
    命令）
触发短语：“我有哪些待办任务”、“查看问题ABC-123”、“查找我的Linear工单”、“我今天要做什么”、“展示我的Linear任务队列”。
当用户想要配置团队设置、集成或OAuth应用时，请跳过本工具；这些管理操作需在Linear Web管理界面中进行。

Argument Parsing

参数解析

Parse 
$ARGUMENTS
:
  1. Empty, 
    help
    , or 
    --help
     -> show 
    linear-pp-cli --help
  2. Starts with 
    install
     -> ends with 
    mcp
    -> MCP installation; otherwise -> CLI installation
  3. Anything else -> Direct Use (map to the best command and run it)
解析
$ARGUMENTS
：
  1. 为空、
    help
    或
    --help
     -> 显示
    linear-pp-cli --help
  2. 以
    install
    开头     -> 如果结尾是
    mcp
    -> 安装MCP；否则 -> 安装CLI
  3. 其他情况 -> 直接使用（映射到最合适的命令并执行）

MCP Server Installation

MCP服务器安装

The CLI ships an MCP server at 
linear-pp-mcp
:
bash
go install github.com/mvanhorn/printing-press-library/library/project-management/linear/cmd/linear-pp-mcp@latest
claude mcp add -e LINEAR_API_KEY=lin_api_... linear-pp-mcp -- linear-pp-mcp
Ask the user for the actual key value before running.
CLI附带了一个MCP服务器
linear-pp-mcp
：
bash
go install github.com/mvanhorn/printing-press-library/library/project-management/linear/cmd/linear-pp-mcp@latest
claude mcp add -e LINEAR_API_KEY=lin_api_... linear-pp-mcp -- linear-pp-mcp
执行前请向用户索要实际的密钥值。

Direct Use

直接使用

  1. Check installed: 
    which linear-pp-cli
    . If missing, offer CLI installation.
  2. Run 
    linear-pp-cli sync
    once (or when data is stale) to populate the local SQLite store. Analytics and search commands then run offline.
  3. Discover commands: 
    linear-pp-cli --help
    ; drill into 
    linear-pp-cli <cmd> --help
    .
  4. Execute with 
    --agent
    for structured output:
    bash
    linear-pp-cli <command> [args] --agent
  5. --data-source auto
    (default) hits the local store first with live fallback; use 
    --data-source live
    to force a live call (e.g. for time-sensitive queries on unsynced fields).
  1. 检查是否已安装：
    which linear-pp-cli
    。如果未安装，提供CLI安装指引。
  2. 先执行一次
    linear-pp-cli sync
    （或数据过期时）以填充本地SQLite存储。之后分析和搜索命令即可离线运行。
  3. 查看可用命令：
    linear-pp-cli --help
    ；查看具体命令详情：
    linear-pp-cli <cmd> --help
    。
  4. 添加
    --agent
    参数执行命令以获取结构化输出：
    bash
    linear-pp-cli <command> [args] --agent
  5. --data-source auto
    （默认值）优先读取本地存储，本地无数据时回退到实时API调用；使用
    --data-source live
    强制实时调用（例如对未同步字段进行时间敏感的查询）。

Notable Commands

重要命令

CommandWhat it does
today
Your issues across all teams, triaged to today's queue
me
Current authenticated user plus a snapshot of your open work
issues <ID>
Get a single issue by identifier (e.g. 
issues ESP-1155
)
issues list
List issues from the local store with filters (
--assignee
, 
--state
, 
--team
, 
--project
, 
--limit
)
projects
Get/list projects with milestones and health status
cycles
Get/list sprint cycles for any team
velocity
Sprint velocity trends across recent cycles
workload
/ 
load
Issue + estimate distribution per team member
bottleneck
Overloaded assignees and blocked issues
stale
Issues not updated in N days
similar <text>
Fuzzy-find potential duplicate issues
orphans
Items missing assignee, project, or estimate
sync
Populate local SQLite from the GraphQL API
tail
Stream live changes by polling at an interval
export
/ 
import
JSONL round-trip for backup and migration
sql
Read-only SQL against the local store (power users)
Run any command with 
--help
for full flag documentation.
命令功能
today
跨所有团队的个人问题列表，按今日优先级排序
me
当前认证用户信息及未完成工作快照
issues <ID>
通过标识符获取单个问题（例如
issues ESP-1155
）
issues list
从本地存储列出问题，支持筛选（
--assignee
、
--state
、
--team
、
--project
、
--limit
）
projects
获取/列出项目及里程碑和健康状态
cycles
获取/列出任意团队的迭代周期
velocity
最近迭代周期的速度趋势
workload
/ 
load
按团队成员划分的问题+预估工作量分布
bottleneck
负载过重的负责人和阻塞的问题
stale
N天未更新的问题
similar <text>
模糊查找潜在重复问题
orphans
缺少负责人、项目或预估工作量的条目
sync
从GraphQL API填充本地SQLite存储
tail
通过定时轮询实时流变更
export
/ 
import
JSONL格式的备份和迁移往返操作
sql
对本地存储执行只读SQL查询（面向高级用户）
执行任何命令时添加
--help
可查看完整的参数文档。

Finding Issues

查找问题

Three patterns cover the common cases:
bash
undefined
以下三种模式覆盖常见场景：
bash
undefined

Look up a specific issue by identifier

通过标识符查看特定问题

linear-pp-cli issues ESP-1155
linear-pp-cli issues ESP-1155

List all issues assigned to the authenticated user, excluding completed/canceled

列出分配给当前认证用户的所有问题，排除已完成/已取消的

linear-pp-cli issues list --assignee me
linear-pp-cli issues list --assignee me

Narrow to a team and state (also accepts --project, --limit, --json)

按团队和状态筛选（也支持--project、--limit、--json参数）

linear-pp-cli issues list --team ESP --state started --json

`issues list` reads from the local store, so run `linear-pp-cli sync` first. `issues <ID>` tries the local store, then falls back to a live GraphQL query, and works without sync.

`--state` matches on state.type so it works across teams with customized state names: `started`, `backlog`, `unstarted`, `completed`, `canceled`, `triage`, or `all`. The default `active` excludes completed and canceled.

`--assignee` accepts `me`, a user UUID, a display name, or an email. `--team` and `--project` accept either a key (e.g. `ESP`) or a UUID.
linear-pp-cli issues list --team ESP --state started --json

`issues list`读取本地存储，因此需先执行`linear-pp-cli sync`。`issues <ID>`先尝试本地存储，失败则回退到实时GraphQL查询，无需同步即可使用。

`--state`匹配state.type，因此可跨自定义状态名称的团队使用：`started`、`backlog`、`unstarted`、`completed`、`canceled`、`triage`或`all`。默认值`active`会排除已完成和已取消的问题。

`--assignee`接受`me`、用户UUID、显示名称或邮箱。`--team`和`--project`接受键值（例如`ESP`）或UUID。

Agent Mode

Agent模式

Add 
--agent
to any command. Expands to: 
--json --compact --no-input --no-color --yes
.
  • Pipeable — JSON on stdout, errors on stderr
  • Filterable — 
    --select
    keeps a subset of fields, with dotted-path support (see below)
  • Previewable — 
    --dry-run
    shows the request without sending
  • Cacheable — GET responses cached for 5 minutes, bypass with 
    --no-cache
  • Non-interactive — never prompts, every input is a flag
在任何命令后添加
--agent
参数。该参数等价于：
--json --compact --no-input --no-color --yes
。
  • 可管道传输 — 标准输出为JSON，错误信息输出到标准错误
  • 可筛选 — 
    --select
    保留字段子集，支持点路径（见下文）
  • 可预览 — 
    --dry-run
    显示请求但不发送
  • 可缓存 — GET响应缓存5分钟，使用
    --no-cache
    可绕过缓存
  • 非交互式 — 从不提示，所有输入均通过参数传递

Filtering output

输出筛选

--select
accepts dotted paths to descend into nested responses; arrays traverse element-wise:
bash
linear-pp-cli <command> --agent --select id,name
linear-pp-cli <command> --agent --select items.id,items.owner.name
Use this to narrow huge payloads to the fields you actually need — critical for deeply nested API responses.
--select
接受点路径以遍历嵌套响应；数组会逐个元素遍历：
bash
linear-pp-cli <command> --agent --select id,name
linear-pp-cli <command> --agent --select items.id,items.owner.name
使用该参数可将庞大的响应缩小到实际需要的字段 — 这对深度嵌套的API响应至关重要。

Response envelope

响应信封

Data-layer commands wrap output in 
{"meta": {...}, "results": <data>}
. Parse 
.results
for data and 
.meta.source
to know whether it's 
live
or local. The 
N results (live)
summary is printed to stderr only when stdout is a TTY; piped/agent consumers see pure JSON on stdout.
数据层命令会将输出包裹在
{"meta": {...}, "results": <data>}
中。解析
.results
获取数据，
.meta.source
可了解数据是来自
live
（实时）还是本地存储。当标准输出为TTY时，
N results (live)
摘要会输出到标准错误；管道/Agent消费者仅会在标准输出看到纯JSON。

Exit Codes

退出码

CodeMeaning
0Success
2Usage error (wrong arguments)
3Resource not found (issue, project, team)
4Authentication required (LINEAR_API_KEY missing or invalid)
5API error (Linear upstream, including GraphQL errors)
7Rate limited (Linear enforces per-key complexity budgets)
代码含义
0成功
2使用错误（参数错误）
3资源未找到（问题、项目、团队）
4需要认证（LINEAR_API_KEY缺失或无效）
5API错误（Linear上游错误，包括GraphQL错误）
7请求受限（Linear按密钥执行复杂度预算限制）

Unique Capabilities

独特功能

These capabilities aren't available in any other tool for this API.
这些功能是其他同类型API工具所不具备的。

Local state that compounds

可累积的本地状态

  • today
     — See all your issues for today across every team, ranked by priority and cycle deadline.
    When an agent is asked 'what should I work on right now?', this returns the ranked list in one call instead of N team-scoped list queries.
    bash
    linear-pp-cli today --json --select identifier,title,priority,cycle.endsAt
  • bottleneck
     — See which team members are overloaded and which issues are blocked before sprint planning.
    Pre-sprint-planning question 'who is overloaded right now' becomes a single agent call instead of scrolling N tabs.
    bash
    linear-pp-cli bottleneck --team ENG --json
  • projects burndown
     — Project a project's landing date by linear-regressing remaining estimate against the team's measured velocity.
    Replaces static project target-dates with a velocity-driven projection an agent can compare against the milestone date.
    bash
    linear-pp-cli projects burndown PROJ-42 --json
  • cycles compare
     — Side-by-side metrics between any two cycles: completion %, scope added, scope cut, carryover, average cycle time.
    Friday-update ritual: 'how does this cycle compare to last cycle?' becomes one call.
    bash
    linear-pp-cli cycles compare 42 43 --json
  • stale
     — Find issues that haven't been touched in N days, grouped by team and project.
    Backlog-grooming workflow: surface zombie issues without paying API complexity for a full scan.
    bash
    linear-pp-cli stale --days 30 --team ENG --json
  • slipped
     — Show what carried over from last cycle into this cycle, grouped by team and reason heuristic.
    Maya's Friday update needs 'what slipped' as a structured list, not a manual count.
    bash
    linear-pp-cli slipped --team ENG --json
  • blocking
     — Show issues you are blocking — sorted by impact (downstream count and priority).
    Daily ritual: 'what's blocked because of me' becomes one call instead of clicking through every assigned issue.
    bash
    linear-pp-cli blocking --json
  • similar
     — Find issues that look like duplicates of a query string using offline FTS5 fuzzy matching.
    Triage and grooming: catch dupes before filing or while sweeping the inbox.
    bash
    linear-pp-cli similar "login button broken" --json
  • velocity
     — Track sprint completion rates over the last N cycles to spot productivity trends.
    Multi-cycle trend lines feed the burndown projection and the weekly stakeholder update.
    bash
    linear-pp-cli velocity --weeks 8 --team ENG --json
  • initiatives health
     — Rolled-up portfolio view per initiative: child project progress, milestone target-vs-projected dates, slippage flags.
    Portfolio review: 'which milestone in my portfolio is most at risk this month' becomes one ranked answer.
    bash
    linear-pp-cli initiatives health --json
  • today
     — 查看跨所有团队的今日个人问题，按优先级和迭代截止日期排序。
    当Agent被问及“我现在应该先做什么？”时，该命令可一次性返回排序后的列表，无需执行N次团队范围的列表查询。
    bash
    linear-pp-cli today --json --select identifier,title,priority,cycle.endsAt
  • bottleneck
     — 在迭代规划前查看哪些团队成员负载过重，哪些问题被阻塞。
    迭代规划前的问题“现在谁负载过重？”可通过一次Agent调用解决，无需在N个标签页间切换。
    bash
    linear-pp-cli bottleneck --team ENG --json
  • projects burndown
     — 通过线性回归剩余预估工作量与团队实测速度，预测项目完成日期。
    用速度驱动的预测替代静态项目目标日期，Agent可将其与里程碑日期进行对比。
    bash
    linear-pp-cli projects burndown PROJ-42 --json
  • cycles compare
     — 任意两个迭代周期的并排指标对比：完成率、新增范围、削减范围、遗留工作量、平均周期时间。
    周五更新惯例：“本次迭代与上次相比如何？”可通过一次调用解决。
    bash
    linear-pp-cli cycles compare 42 43 --json
  • stale
     — 查找N天未更新的问题，按团队和项目分组。
    待办事项梳理流程：无需支付全量扫描的API复杂度成本即可发现僵尸问题。
    bash
    linear-pp-cli stale --days 30 --team ENG --json
  • slipped
     — 显示从上一个迭代周期遗留到当前周期的问题，按团队和原因启发式分组。
    Maya的周五更新需要结构化的“遗留问题”列表，而非手动统计。
    bash
    linear-pp-cli slipped --team ENG --json
  • blocking
     — 显示因你而阻塞的问题 — 按影响程度（下游问题数量和优先级）排序。
    日常惯例：“哪些问题因我而阻塞？”可通过一次调用解决，无需逐个点击已分配的问题。
    bash
    linear-pp-cli blocking --json
  • similar
     — 使用离线FTS5模糊匹配查找与查询字符串相似的重复问题。
    问题分类和梳理：在创建问题或清理收件箱前发现重复项。
    bash
    linear-pp-cli similar "login button broken" --json
  • velocity
     — 跟踪最近N个迭代周期的完成率，发现生产力趋势。
    多周期趋势线可用于燃尽图预测和每周利益相关者更新。
    bash
    linear-pp-cli velocity --weeks 8 --team ENG --json
  • initiatives health
     — 按行动计划汇总的组合视图：子项目进度、里程碑目标日期与预测日期对比、延迟标记。
    组合评审：“本月我的组合中哪个里程碑风险最高？”可通过一次排序后的回答解决。
    bash
    linear-pp-cli initiatives health --json

Agent-native plumbing

Agent原生管道

  • pp-test list
     — List Linear issues this CLI created in the current or named session, then archive them with pp-cleanup.
    Lets agents create test issues during a session and clean up only their own fixtures, never touching pre-existing tickets.
    bash
    linear-pp-cli pp-test list --session current && linear-pp-cli pp-cleanup --session current --dry-run
  • issues create
     — Refuse mutations on Linear issues not in the local pp_created ledger when --trust-mode strict is set; works on the create command and any future mutation surfaces.
    When an agent runs against a real workspace, this is the safety net that prevents silent damage to non-test data.
    bash
    linear-pp-cli issues create --title "test" --team ENG --trust-mode strict --session demo
  • pp-test list
     — 列出本CLI在当前或指定会话中创建的Linear问题，然后使用pp-cleanup归档这些问题。
    允许Agent在会话期间创建测试问题，并仅清理自己的测试数据，绝不会触及已存在的工单。
    bash
    linear-pp-cli pp-test list --session current && linear-pp-cli pp-cleanup --session current --dry-run
  • issues create
     — 当设置
    --trust-mode strict
    时，拒绝修改不在本地pp_created ledger中的Linear问题；该规则适用于create命令及任何未来的变更操作。
    当Agent在真实工作区运行时，这是防止意外损坏非测试数据的安全网。
    bash
    linear-pp-cli issues create --title "test" --team ENG --trust-mode strict --session demo