CLI 教程

概述

@baklib/baklib-cli 是 Baklib Open API 的命令行客户端：在终端或 CI 中管理站点、知识库、DAM、成员等，并支持 本地主题预览（theme dev：经 Open API 同步 Liquid 到服务端 preview_render，无需本地 Rails）。

与 MCP 教程相比，CLI 更适合 可脚本化、可重复、可管道 的任务；与 MCP 共用同一套 API 密钥鉴权。

操作步骤

步骤一：安装 CLI

npm install -g @baklib/baklib-cli
baklib --version

从源码开发请参阅 GitHub README（npm install → npm run build → npm link）。

预期结果：终端可执行 baklib 命令。

步骤二：配置鉴权

CLI 惰性读取配置：仅执行需鉴权的子命令时才要求 Token；baklib --help 不强制。

写入 Token（项目级，推荐在仓库根目录）：

cd /path/to/your-project
baklib config set-token "<key>:<secret>"

写入用户级（-g）：

baklib config set-token "<key>:<secret>" -g

查看当前生效配置：

baklib config show

配置优先级（后者覆盖前者；环境变量始终最后生效）：

~/.config/baklib/baklib.json（用户级）
自当前目录向上查找的第一个 .baklib/baklib.json
兼容：工作区或用户 ~/.config/ 下平铺凭据（如 BAKLIB_MCP_TOKEN）
环境变量 BAKLIB_TOKEN、BAKLIB_API_BASE（API 主机根，默认 https://open.baklib.com；CLI 自动追加 /api/v1）

baklib.json 示例：

{
  "token": "<key>:<secret>",
  "apiHost": "https://open.baklib.com"
}

清除凭据：baklib config reset（加 -g 仅清用户级）。

预期结果：baklib config show 显示已配置 token（通常打码）；后续 API 调用不再报 401。

步骤三：常用 Open API 命令

脚本场景请加 --json，输出机器可读 JSON；默认输出为终端友好文本。

# 站点
baklib --json site list

# 知识库：列出文章、拉取/推送 Markdown
baklib kb articles --space-id <SPACE_ID>
baklib kb pull --space-id <SID> --article-id <AID> --out ./article.md
baklib kb push --file ./article.md

# 站点页面
baklib site pages pull --site-id <SID> --page-id <PID> --out ./page.json

# DAM 上传
baklib dam upload --file-path ./logo.png

站点页创建/更新可用 --vars-file 传入 template_variables 的 JSON 文件。

完整命令树见仓库 references/commands.md 或本地 baklib <子命令> --help。

预期结果：命令返回 JSON 或摘要文本；拉取/推送文件写入指定路径。

步骤四：主题本地开发（可选）

面向 Liquid 模板 作者：

# 脚手架（可选）
baklib theme init cms vcard
cd cms--vcard

# 启动本地开发服 + 管理面板
baklib theme dev
# 可选：baklib theme dev --port 5175

浏览器打开终端打印的 管理面板 地址（形如 http://127.0.0.1:5174/!admin）。
选择目标站点，开启 「同步模版到预览」。
保存主题文件后，预览页经服务端渲染更新 HTML。

列出 / 拉取平台模板：

baklib theme list
baklib theme show cms/guide
baklib theme pull cms/guide --out ./my-theme --yes

单次上传预览（不经面板）：

baklib theme push --theme-dir ./cms--my_theme --entry templates/index.liquid --locale zh-CN

Liquid 语法与 form_tag 等细则请安装 baklib-theme-dev 技能，见模板开发与 Liquid。

预期结果：本地改模板可实时预览与线上一致的 HTML 渲染。

步骤五：安装 CLI 配套 AI 技能

baklib skill install -g                                    # 默认仅 baklib-cli
baklib skill install --skill baklib-cli --skill baklib-theme-dev -g

等价于 npx skills add baklib-tools/skills --skill …，详见 SKILLS 使用指南。

预期结果：在 Cursor 等环境中，AI 可正确选用 baklib 子命令与参数。

常见问题

Q：CLI 与 MCP 应选哪个？
A：对话、探索、辅助写作 优先 MCP；脚本、CI、主题 dev、批量 pull/push 优先 CLI。二者可并存。

Q：BAKLIB_MCP_TOKEN 与 BAKLIB_TOKEN 一样吗？
A：均为 <key>:<secret> 格式；CLI 优先读 baklib.json 与 BAKLIB_TOKEN，也兼容部分 MCP 凭据文件。

Q：如何关闭版本更新提示？
A：设置 BAKLIB_SKIP_VERSION_CHECK=1。

Q：命令报错 422 / 预览空白？
A：主题预览排查见 CLI 仓库 docs/theme-preview.md。

概述