baklib-cli

name	baklib-cli
description	指导在终端用 @baklib/baklib-cli（baklib 命令）通过 Baklib Open API 管理站点、知识库、DAM、成员与用户，以及主题拉取/预览上传与本地 theme dev；含鉴权配置、--json 脚本输出与执行规范。在用户已安装或可安装 baklib CLI、要用命令行/脚本/CI 读写 Baklib 线上数据时使用；Liquid 模版语法见 baklib-theme-dev（需另行安装）。

Baklib CLI（Open API 命令行）

baklib 是面向 Baklib Open API 的独立 CLI：在真实 shell 中查询与变更组织内的站点、知识库、资源库等数据，并支持主题文件拉取、预览上传与本地 theme dev。

读写 Baklib 线上数据一律优先使用本 CLI（或用户明确要求的 HTTP 脚本）；不要改用 MCP 或其它未配置的集成方式替代。

安装 CLI

npm install -g @baklib/baklib-cli
baklib --version   # 需 Node ≥ 20

开发源码：git clone → npm install && npm run build → npm link。

安装本技能（供 AI 加载）

baklib skill install -g
baklib skill install --skill baklib-cli --skill baklib-theme-dev -g

与 npx skills add baklib-tools/skills --skill <id> 相同；可 npx skills add baklib-tools/skills --list 查看 id。

鉴权与配置

惰性读取：仅 --help / --version 不强制 Token；执行需鉴权的子命令前须已配置。

合并优先级（环境变量最后覆盖文件）：

1. ~/.config/baklib/baklib.json（token、apiHost）
2. 自 CWD 向上首个 .baklib/baklib.json
3. 兼容平铺凭据（如 ~/.config/BAKLIB_TOKEN 等，见 baklib config --help）
4. BAKLIB_TOKEN、BAKLIB_API_BASE（主机根，默认 https://open.baklib.com；CLI 固定请求 {apiHost}/api/v1）

baklib config set-token "<token>"
baklib config set-api-base "https://open.baklib.com"
baklib config set-token "<token>" -g          # 仅用户级
baklib config show

全局选项：--json（机器可读 JSON；默认人类可读摘要）、-B / --api-base <url>。

代理执行规范

1. 先查后写：list / get 确认 site_id、space_id、article_id、DAM id 等，再 create / update / delete / upload / push。
2. 脚本与非交互：加 --json；theme pull 等需确认时加 --yes（非 TTY 脚本常用）。
3. 写入前确认：删除、批量覆盖、发布到线上等须征得用户同意。
4. 正文格式：经 CLI 写入 KB/站点/DAM 片段时，若目标字段为 BKE 富文本，遵循 baklib-bke-markdown；站点页 template_variables 可用 --vars-file 传入 JSON。
5. 错误处理：401/403 时引导检查 baklib config show 与 Token 是否过期；勿编造 API 响应。

命令域速查

完整子命令与选项以 baklib <域> --help 为准；详见 references/commands.md。

域	用途	典型入口
config	本地凭据	config show / set-token / reset
site	站点、页面、标签	site list → site pages list --site-id → pages pull / update
kb	知识库空间与文章	kb spaces → kb articles → kb pull / kb push
dam	资源上传与片段/链接	dam upload / dam list / fragment-create
theme	平台模板与本地开发	theme list / pull / dev / push / preview
member / user	组织成员与账户	member list / user me
skill	安装 AI 技能	skill install --skill <id>（可重复；默认 baklib-cli）

常用工作流

列出并导出知识库文章

baklib --json kb spaces
baklib --json kb articles --space-id <SPACE_ID>
baklib kb pull --space-id <SID> --article-id <AID> --out ./article.md

站点页面 round-trip

baklib --json site list
baklib site pages pull --site-id <SID> --page-id <PID> --out ./page.json
# 编辑 JSON 后
baklib site pages update --site-id <SID> --page-id <PID> --file ./page.json

DAM 上传

baklib dam upload --file-path ./logo.png
baklib --json dam list

主题：拉取与本地预览

baklib theme pull cms/guide --out ./cms--guide --yes
cd ./cms--guide && baklib theme dev
baklib theme preview set --path / --template index --vars '{"title":"demo"}'
baklib theme preview url --path /

Liquid/schema 规则见 baklib-theme-dev（baklib skill install --skill baklib-theme-dev）。

与仓库文档

• CLI 用户说明：baklib-cli README
• 主题预览：theme-preview.md

附加参考

• references/commands.md — 子命令树与 --json / 环境变量要点