| 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
开发源码：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；执行需鉴权的子命令前须已配置。
合并优先级（环境变量最后覆盖文件）：
~/.config/baklib/baklib.json（token、apiHost）- 自 CWD 向上首个
.baklib/baklib.json
- 兼容平铺凭据（如
~/.config/BAKLIB_TOKEN 等，见 baklib config --help）
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>。
代理执行规范
- 先查后写：list / get 确认
site_id、space_id、article_id、DAM id 等，再 create / update / delete / upload / push。
- 脚本与非交互：加
--json；theme pull 等需确认时加 --yes（非 TTY 脚本常用）。
- 写入前确认：删除、批量覆盖、发布到线上等须征得用户同意。
- 正文格式：经 CLI 写入 KB/站点/DAM 片段时，若目标字段为 BKE 富文本，遵循 baklib-bke-markdown；站点页
template_variables 可用 --vars-file 传入 JSON。
- 错误处理：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
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）。
与仓库文档
附加参考
