CookCLI 介绍与选型指南

CookCLI 是 Cooklang 食谱标记语言的官方命令行工具集：单个二进制即可解析、展示、检索纯文本食谱，生成购物清单，管理食材库存，还能以 cook server 形态把整个食谱库变成一个可浏览的 Web 站点。项目由 cooklang 组织维护，Rust 编写，MIT 协议开源，GitHub 仓库 cooklang/cookcli（约 1.4k stars，查询于 2026-11-01）。本文基于官方 README、命令文档与 GitHub Releases 页面（均于 2026-11-01 查询）梳理其定位、功能与安装方式，并给出与同类方案的选型对比。本专栏后续部署与实操均基于最新稳定版 v0.39.0（2026-10-24 发布）。

一、Cooklang 与 CookCLI：先分清语言与工具

Cooklang 是一种为「人类可读、机器可解析」设计的食谱标记语言：食谱就是普通文本文件（扩展名 .cook），用纯文本写步骤，用固定语法内联标注食材、炊具与用量，无需数据库、无需专用编辑器，任何文本工具都能改，Git 能管版本。

官方示例食谱 Easy Pancakes.cook 的原文（节选自 cook seed 生成的示例库）：

---
servings: 2
tags: breakfast, quick
source: https://cooklang.org
author: CookCLI Team
prep time: 5 min
cook time: 20 min
description: Simple crepes that are perfect for a lazy weekend breakfast.
---

Crack the @eggs{3} into a blender, then add the @flour{125%g},
@milk{250%ml} and @sea salt{pinch}, and blitz until smooth.

Pour into a bowl and leave to stand for ~{15%minutes}.

Melt @butter{knob} in a #large non-stick frying pan{} on \
a medium heat, then tilt the pan so the butter coats the surface.

三条核心语法：

文件头部的 YAML frontmatter 承载份数（servings）、标签、来源、耗时等元数据。

CookCLI 则是围绕这套语言的全套命令行工具：把 .cook 文件渲染成人类可读文本或 JSON/YAML/Markdown/LaTeX/Typst 等格式、聚合多份食谱生成购物清单、按菜单文件做膳食计划、跟踪家里食材库存、全文检索食谱、起一个 Web 服务在任意设备上浏览食谱库。官方定位一句话概括："Command line tools for working with Cooklang recipes"，设计哲学是 UNIX 式的——输出可管道、与既有脚本工具组合，同时也能独立充当食谱 Web 服务器。

二、项目速览

两点值得注意的背景：

1. 代码传承：CookCLI 的部分源文件取自早期桌面客户端 cooklang-chef（同为 MIT），可以视为 Cooklang 工具链从桌面端向「CLI + 服务器」路线的延续与重写。
2. 持续活跃：v0.39.0 前后每月都有版本落地，README 中的安装矩阵、cook server 的用户认证、pantry 库存分析等能力都是近一年迭代新增，选型时可放心其维护状态。

三、核心能力拆解

以 v0.39.0 的实际子命令清单为准（cook --help 列出 14 个命令）：

几条官方给出的组合用法，能直观感受 UNIX 哲学：

# 缩放：任何食谱路径后加 :N，2 倍量、半份皆可
cook recipe "Pizza.cook:2"
cook shopping-list "Pasta.cook:0.5"

# 检索结果直接管道给购物清单
cook search chicken | xargs cook shopping-list

# 批量把食谱转成 Markdown 文档
for r in *.cook; do
  cook recipe "$r" -f markdown > "docs/${r%.cook}.md"
done

数据侧只有两类纯文本配置文件（详见本专栏配置篇）：aisle.conf 定义购物清单的商店分区，pantry.conf（TOML）记录家中库存的数量、保质期与低库存阈值——库存食材会自动从购物清单中剔除。

四、安装方式与平台支持

CookCLI 官方提供五种安装路径，覆盖主流平台：

二进制矩阵覆盖：Linux x86_64（musl 静态 / glibc）、Linux i686、Linux aarch64 与 armhf（树莓派）、macOS（Apple Silicon / Intel）、Windows（x86_64 / i686 / aarch64）、FreeBSD x86_64。其中 musl 静态版不依赖发行版的 C 库，老系统、Alpine 之类都能直接跑，这也是资源受限设备的首选。

Cargo features 可裁剪依赖面：server（Web 服务器）、import（网页抓取）、lsp（语言服务器）、sync（CookCloud 同步）、self-update（自更新）五个可选特性默认全开；只要核心食谱工具时可全部关闭——依赖图从 412 个 crate 降到 225 个，二进制从约 23 MB 缩到约 9 MB：

cargo build --release --no-default-features                # 仅核心 CLI
cargo build --release --no-default-features --features server  # 核心 + Web 服务器

装好后 cook update 可从 GitHub Releases 原地自更新（--check-only 只查不装）。

五、选型对比

Cooklang 生态内与自托管食谱管理领域，常见对照对象如下（各对象信息以其官方仓库/站点为准，查询于 2026-11-01）：

判断逻辑：

• 食谱以「我的文件」为中心（用 Git 管、用脚本批处理、不想被数据库绑架）→ CookCLI 是当前唯一同时提供 CLI、Web 服务器、静态站点三种形态的 Cooklang 官方工具。
• 只想要一个好看的桌面菜谱浏览器 → cooklang-chef 曾是该角色，但维护已停滞，且其能力已被 CookCLI 的 cook server Web 界面覆盖。
• 要全家共享、含营养计算/复杂权限/网页剪藏的一站式平台 → Mealie 或 Tandoor 更合适；代价是引入数据库与更大的运维面，且食谱不再是纯文本主存储。
• 用 iOS/Android 端 Cooklang App，同时想要服务端 → 食谱目录放服务器上跑 cook server，文件与 App 天然互通，这是 CookCLI 独有的组合。

六、适用与不适用场景

适合：

• 个人/家庭自托管食谱库，习惯纯文本与 Git；
• NAS / 树莓派等资源有限设备（静态 musl 二进制、可裁剪特性，aarch64/armhf 官方构建）；
• 想把「本周菜单 → 购物清单」自动化进 shell 脚本或定时任务；
• 需要把食谱库发布为静态站点或内网 Web 界面。

不适合：

• 期望开箱即用的富媒体菜谱社区体验（评分、评论、社交）——CookCLI 是工具不是平台；
• 强依赖网页一键剪藏且不想配置任何 API Key（cook import 需 OPENAI_API_KEY）；
• 需要多租户、细粒度企业权限——cook server 的认证只有 reader/shopper/editor/admin 四档角色，面向家庭与小团队。

七、小结

CookCLI 把「食谱 = 纯文本」这件事做成了完整闭环：语言规范（Cooklang）→ 命令行工具（解析/清单/库存/体检）→ 服务器形态（Web 浏览与编辑）→ 静态站点发布 → 移动端 App 互通。单二进制、MIT、活跃发版，是自托管食谱管理里「数据完全属于自己」路线的最优解。

本专栏后续三篇基于 v0.39.0 实测展开：部署篇覆盖二进制裸装与 Compose 编排两种落地形态；配置篇逐项讲解 COOK_CONFIG_DIR、users.toml、aisle.conf、pantry.conf 与服务器参数；命令篇按子命令给出完整实测回显。

参考资料（均于 2026-11-01 查询）：

• CookCLI 仓库与 Releases：https://github.com/cooklang/cookcli
• 官方文档：https://cooklang.org/cli/
• Cooklang 规范：https://cooklang.org/docs/spec
• Web 界面演示：https://demo.cooklang.org
• Cooklang 移动应用：https://cooklang.org/app/