linearis

linearis

通过 linearis CLI 从 shell 操作 Linear.app（仅输出 JSON；linear 是别名）。不要猜测命令用法——CLI 会自行说明，而本技能讲解的是协议，不是标志。

预检查（响应式——根据 CLI 自身的输出采取相应操作；不要每轮都预先运行检查）

• 未安装 — 如果 shell 报告找不到命令，告诉用户尚未安装 linearis，并提供 npm install -g linearis。无需安装的备用方案是为命令加上前缀 npx linearis@latest（会增加冷启动延迟，而且每次调用都需要网络——仅作备用方案，并非默认选项）。绝不要静默运行 npm install -g。
• 需要身份验证 — 任何命令都可能在 stderr 上输出以下内容并以退出代码 42 失败： { "error": "AUTHENTICATION_REQUIRED", "action": "USER_ACTION_REQUIRED", "instruction": "Run 'linearis auth login' …", "exit_code": 42 }。 通过 exit_code === 42 / error === "AUTHENTICATION_REQUIRED"（而不是改述后的文本）检测，并向用户展示 CLI 自身的 instruction。linearis auth login 是你无法完成的交互式浏览器流程——请交由用户操作。
• 调用无效 — 未知命令或选项、参数数量错误，或指定命令组却未提供子命令时，会在 stderr 上以退出代码 2 失败： { "error": "UNKNOWN_COMMAND", "message": "…", "suggestion": "Did you mean read?", "command": "linearis issues", "available_commands": [...], "instruction": "Run 'linearis issues usage' …", "exit_code": 2 }。 根据错误内容恢复，而不要靠猜测：从 available_commands 中选择，或运行 instruction。error 可能是 UNKNOWN_COMMAND、UNKNOWN_OPTION、MISSING_ARGUMENT、MISSING_REQUIRED_OPTION、MISSING_OPTION_ARGUMENT、TOO_MANY_ARGUMENTS、MISSING_SUBCOMMAND、INVALID_USAGE。仅输入命令组（linearis issues）会导致失败，并不表示请求帮助。
• 更新（仅供参考，绝不阻塞操作） — 可以选择运行一次 linearis version check → { current, latest, channel, updateAvailable }。如果 updateAvailable 为 true，告知用户并在运行 npm install -g linearis@latest 前征求同意，同时遵循 channel（不要将 next 用户切换到 latest）。npm 可能会卡住或触发速率限制；发生超时或任何错误时，直接使用已安装的版本继续操作。通过 linearis version（JSON）读取已安装版本，不要使用 --version。

先探索，再操作

1. 运行一次 linearis usage，查看域列表（issues、projects、cycles 等）。
2. 操作前运行 linearis <domain> usage，查看该域完整的命令和标志参考。
3. 绝不要编造标志或子命令——usage 是权威依据，并始终保持最新。

输出

每条命令都会在 stdout 上输出 JSON。使用全局标志 --fields identifier,title,state.name 和 --compact 在源头整理输出——无需外部二进制文件，且适用于 Windows 和全新容器。只有在需要复杂重塑数据时才使用 jq；如果没有 jq，则回退到原始 JSON。

值得了解的不变规则（其他内容见 usage）

• ID 的格式要求宽松：UUID、团队键（ENG）、工单标识符（ABC-123）或名称均可互换使用。引用工单时请使用标识符。
• issues create 必须指定 --team；某些筛选条件需要指定范围标志——请在 usage 中确认，不要死记。
• 线程式讨论位于 issues discuss / discussions / replies / reply 下。顶层的 comments 域是已弃用的接口（仍可使用）——请优先使用 issues 下的讨论命令。将重要进展记录在讨论线程中，并在状态变更时同步更新描述。
• files download <url> 仅获取 Linear 存储 URL（uploads.linear.app）；files upload 会返回可嵌入的 assetUrl；issues read --with-attachments 会列出关联资源（PR、文档、URL）——这些是引用，不一定是可下载文件。

本文未涵盖的内容，请参阅 linearis <domain> usage。