ghost

ghost — 在终端管理 Ghost CMS 内容

通过终端操作 Ghost CMS 站点的 Admin API（v5/v6，Accept-Version: v6.0）：按状态列出文章（包括草稿）、创建并发布页面和文章、管理标签，以及查看站点信息。这里可以查看草稿、定时发布的文章和已发布内容，因为每次调用都会使用 id:secret 集成密钥生成的 Admin JWT 进行身份验证。

设置

export GHOST_URL="https://your-ghost-site.com"
export GHOST_ADMIN_KEY="<RECORD_KEY>"   # id:secret from Ghost Admin → Integrations

1. 在 Ghost Admin → Settings → Integrations 中创建（或打开）一个 Custom Integration。
2. 复制其 Admin API Key——这是由两个以冒号分隔的十六进制部分组成的字符串（id:secret）。同一页面中的独立 Content API key 无法让你查看草稿；请参阅“已知注意事项”。
3. 每次请求时，CLI 都会为该调用签署一个短期 JWT：使用将 secret 部分十六进制解码为原始字节后的值作为密钥进行 HS256 签名，kid 请求头携带 id 部分，audience 为 /admin/，exp 比 iat 晚五分钟，并以 Authorization: Ghost <token> 发送。你无需自行处理令牌。
4. 无需凭据即可使用 --help 和 --dry-run（延迟进行身份验证）。

基本命令

查看

ghost site                       # title, url, description, version
ghost get-post POST_ID           # full record incl. exact updated_at for edits

浏览（意图：查找内容）

ghost posts                                   # latest 20
ghost posts --status draft                    # unpublished work queue
ghost posts --status scheduled                # what publishes next
ghost posts --limit 100 --page 2              # paginate (max page size 100)
ghost posts --order "updated_at desc"         # SQL-style ordering
ghost pages                                   # static pages
ghost tags                                    # tags with usage counts

创建并发布

ghost create-post --title "Notes"                              # safe default: draft
ghost create-post --title "Hello" --html "<p>Hi</p>"
ghost create-post --title "Launch" --status published --html "<p>We're live</p>"
ghost create-post --title "Later" --status scheduled \
  --published-at "2026-09-01T09:00:00.000Z"                    # future ISO-8601 required together
ghost create-page --title "About" --html "<p>…</p>" --slug about
ghost create-tag --name "Engineering" --description "Technical posts"

编辑和删除

ghost update-post POST_ID --title "New title" \
  --updated-at "<RECORD_UPDATED_AT>"          # REQUIRED: latest updated_at, re-read first
ghost update-post POST_ID --status published --updated-at "<RECORD_UPDATED_AT>"
ghost delete-post POST_ID                     # permanent, 204-style removal

工作流示例

立即保存草稿，审核后发布

ghost --json create-post --title "Release notes" > /tmp/post.json
id=$(jq -r '.post.id // .post_id // empty' /tmp/post.json)
ghost get-post "$id"                          # read fresh updated_at
ghost update-post "$id" --status published \
  --updated-at "<exact string from get-post output>"

切勿伪造 updated_at；请从最新读取结果中原样复制该值，否则 Ghost 会以 HTTP 409 UpdateCollisionError 拒绝编辑。

跨状态审核队列

for s in draft scheduled; do
  ghost posts --status "$s" --json | jq -r '.posts[] | "\(.status)\t\(.title)\t\(.slug)"'
done

完整导出

按 meta.pagination.next 翻页（显示为 .page.next），不要依赖总数：

page=1
while :; do
  ghost posts --limit 100 --page "$page" --json > "/tmp/posts-$page.json"
  jq -r '.posts[].id' "/tmp/posts-$page.json"
  next=$(jq -r '.page.next // empty' "/tmp/posts-$page.json")
  [ -z "$next" ] && break
  page=$next; sleep 0.2
done

JSON 输出和 jq

--json 可放在子命令前面或后面：

ghost --json posts        # same as: ghost posts --json

值得了解的 JSON 结构：

• 列表输出 {"total", "page": {pagination}, "posts": [...]}；详情和创建操作会将资源放在对应名词下（post、page、tag、site）。
• 分页结构与 API 一致：.page = {"page", "limit", "pages", "total", "next", "prev"}；next/prev 的值为数字或 null。
• --dry-run --json 输出已执行计划，而非结果：{"dry_run": true, "method", "url", "params"/"json"}——运行实际请求前，可先预览确切请求内容。
• 出错时会以非零状态码退出，并在 stderr 中输出 API 自身的错误消息及代码；JSON 模式不会将错误封装为 stdout 中的 JSON。

全局标志

标志	作用
--json	输出机器可读的 JSON（位置不限）
--dry-run	打印计划执行的 API 调用（方法、URL、负载），但不实际执行
--quiet	禁止输出诊断信息
--verbose	调试日志

已知注意事项

• 草稿需要 Admin 平面。 公共 Content API（那个将密钥作为查询参数的 API）只提供已发布的文章，并会悄然隐藏草稿——不会报错，只是看不到，即使密钥完全有效也是如此。它的 status:draft 等筛选条件会被忽略，而不是被拒绝。此 CLI 的所有操作都通过 Admin API 执行，正是为了让草稿和定时发布的文章始终可访问。
• 两个密钥，共用一个集成页面。 Content 密钥可在浏览器中安全使用，但只能读取公开内容；Admin 密钥（GHOST_ADMIN_KEY）用于签署修改操作，也能访问草稿。切勿让脚本使用 Content 密钥后还指望能看到草稿。
• 令牌有效期为 5 分钟。 每个 JWT 的有效期最多为 300 秒（exp ≤ iat + 300），验证器也会限制令牌的年龄，因此长时间的批处理作业必须在每次请求时重新签署（CLI 会这样做）。时钟偏差会导致签署时间窗口失效；请确保 NTP 正常运行。
• 仅支持 HS256，密钥必须使用解码后的密钥值。 使用 HS512 签署的令牌会被拒绝（“invalid algorithm”）；未先对密钥进行十六进制解码就直接签署，会产生“看似有效”的无效数据，并导致 401。CLI 会处理这两项规则。
• 使用 Authorization: Ghost，而不是 Bearer。 Bearer 方案会返回 401 INVALID_AUTH_HEADER。
• 编辑需要冲突保护。 未携带文章当前 updated_at 的 PUT 请求会失败并返回 409；关联数组（tags、authors）会整体替换，而不是合并。
• --html 必须配合 source=html 使用，而且转换有损。 每个携带 html 负载的写入操作（create-post、update-post、create-page）都必须发送 ?source=html 查询标志——CLI 会自动附加该标志，dry-run 计划也会在 params 中显示它——否则 Ghost 会将正文解析为 mobiledoc/lexical。即使带上该标志，转换仍有损：请发送正确的 Lexical，或将固定标记包在 HTML 卡片注释中。
• 分页上限为 100，因为 Ghost 6 移除了 limit=all；超出上限的请求会悄然最多返回 100 行，因此务必通过 next 循环获取数据。
• 删除不可撤销，并会立即在公开网站上生效。

适用场景

当任务涉及正在运行的 Ghost 网站上的内容工作流时，请使用此技能：浏览或导出文章、起草、发布、安排发布时间、维护标签、创建页面，或诊断这些流程中的问题（身份验证错误、分页、草稿缺失）。

不适用场景

请勿将其用于安装、托管或运维 Ghost 服务（ghost install、nginx/SSL/systemd 配置、升级、备份）——这些属于 Ghost 官方 npm ghost-cli 网站管理工具的用途，与此工具无关，尽管两者名称相同。也不适用于其他发布平台（WordPress、Hugo 各有自己的工具）、主题开发，或更适合在 Admin 控制面板中一次性完成的网站配置（员工账号、会员等级）。

参考文件

文件	用途
references/admin-auth-and-basics.md	完整的 JWT 签署步骤、密钥格式、受众/有效期规则、身份验证错误表
references/content-vs-admin-api.md	如何选择 API 平面；草稿可见性陷阱；诊断清单
references/posts-pages-tags-endpoints.md	端点映射、字段语义、分页循环、错误封装
references/worked-recipes.md	可直接复制粘贴的工作流：草稿→发布、导出、安排发布时间、问题分诊
references/gotchas-field-guide.md	按症状查找身份验证、编辑和数据量问题

脚本和先决条件

• scripts/ghost — 可执行的 Python CLI（仅使用标准库和 requests）。支持上述标志；延迟进行身份验证；结构化日志记录。
• scripts/test_ghost.py — 离线测试套件（模拟 HTTP，不访问网络）。
• Python 3.8+、requests。不监听端口，也不安装任何内容；作用范围仅限于通过 GHOST_URL 配置的一个网站。