linear-cli是一个让 Linear 用户不用离开终端的命令行工具，支持列出、创建 issue、创建 PR 等操作。本文揭秘它的模板工作流：用linear template list和linear template view浏览模板，再用linear issue create --template和linear project create --template预填标题、优先级、标签、描述正文等字段，让创建 issue 与 project 的效率翻倍。

一、为什么要在命令行里用 Linear 模板？

在 Linear 网页里，模板帮你"一键预填"表单字段。但在终端里手写每一条--priority high --label bug ...又长又容易漏。linear-cli 的解法很直接：

--template接管团队默认模板，模板负责填你没传的字段，你显式传的 flag 负责覆盖它。

这样一条命令 = 网页上点"从模板创建"的全部效果，而且完全可脚本化、可被 AI Agent 调用（该项目本身定位就是agent friendly）。

核心机制一句话总结：Linear 在服务器端应用模板，CLI 只负责把正确的模板 ID 传过去（见 crates/linear-cli/src/commands/project/common.rs 中template()的解析逻辑）。

二、30 秒上手：两条命令找到模板

模板相关功能由linear template命令族提供，源码位于 crates/linear-cli/src/commands/template/。

1. 一键列出工作区模板

# 列出工作区内所有 issue / project / document 模板 linear template list # 只看 ENG 团队的 issue 模板（含工作区级模板） linear template list --type issue --type issue --team ENG # 供脚本消费的结构化输出 linear template list --json

列表按「类型 → 名称 → 作用域」稳定排序，表格里会标注模板属于Workspace还是某个团队，带表单字段的模板会额外显示(form)标记（实现见 crates/linear-cli/src/commands/template/list.rs）。

2. 查看模板到底预填了什么

# 按名称（不区分大小写）或 UUID 查看 linear template view "Bug report" # 原始 JSON 输出，templateData 可用 jq 解码 linear template view "Bug report" --json

文本输出会分三段：元信息（团队、创建者、最后应用时间）、Pre-fills 列表（标题、优先级、标签、子 issue 等），以及富文本正文的 Markdown 版，方便你直接确认再创建。渲染逻辑在 crates/linear-cli/src/commands/template/view.rs。

三、issue 创建：--template 让 --title 变可选

创建流程三步骤

# ① 找到团队期望使用的模板 linear template list --type issue --team ENG # ② 看它预填了什么（标题、字段、正文、子 issue） linear template view "Bug report" # ③ 一条命令创建，模板补全其余字段 linear issue create --team ENG --template "Bug report" --title "Login fails on Safari"

关键行为规则（与 crates/linear-cli/src/cli/issue.rs 的参数说明一致）：

也就是说，下面两条命令效果不同，第二条多了security标签（合并进模板标签），标题被你的 flag 覆盖：

linear issue create --team ENG --template "Bug report" linear issue create --team ENG --template "Bug report" -t "Login fails" -l security

💡 小细节：--template本身就"顶替"了团队默认模板的位置，所以无需再配--no-use-default-template；不传--template时才会走团队默认模板（相关字段定义见 crates/linear-cli/src/commands/issue/create.rs）。

四、project 创建：同名规则完全一致

project 侧的--template行为与 issue 侧对齐，参数说明见 crates/linear-cli/src/commands/project/create.rs：

# 从 "Kickoff" 项目模板创建 Q3 发布项目 linear project create --name "Q3 launch" --team ENG --template "Kickoff"

规则同样是：搜索工作区模板 + 项目所属团队的模板，模板填你没传的字段，flag 覆盖它。解析入口common::template()位于 crates/linear-cli/src/commands/project/common.rs。

五、避坑指南：报错信息都在提示你下一步

模板校验逻辑集中在 crates/linear-cli/src/commands/template/scope.rs，常见报错都有明确的修复提示：

实用建议：名称跨团队重名时，优先用 UUID；脚本场景可加--no-input让缺失必填值直接失败而不是弹出交互提示，配合退出码（2=用法错误，3=未找到）做自动化分支。

六、进阶：JSON 输出与 Agent 自动化

templateData在接口里是JSON 编码的字符串，拿到后可解码查看全部预填字段：

linear template view "Bug report" --json | jq '.templateData | fromjson'

完整字段结构（template_type、team、inherited_from、last_applied_at等）定义在 crates/linear-cli/src/commands/template/json.rs。配合 skills/linear-cli/SKILL.md 里的 "Create an issue or project from a template" 配方，AI Agent 可以完成"查模板 → 核对预填 → 创建"的完整闭环，这也是该项目agent friendly定位的典型落地场景。

七、小结

• linear template list/view先侦察，确认模板预填内容再动手
• issue create --template与project create --template按「flag 覆盖、label 合并、description 替换」三条规则工作
• 重名或跨团队场景直接用模板 UUID，配合报错提示快速定位
• 文档模板（document）目前只能列出和查看，Linear API 尚不支持在创建文档时应用

更多模板命令细节可查 skills/linear-cli/references/template.md、skills/linear-cli/references/issue.md 与 skills/linear-cli/references/project.md，上手体验见 README.md 的 template commands 一节。掌握这套--template工作流，issue 与 project 的创建效率自然翻倍。