jhb-software/payload-content-cli

# @jhb.software/payload-content-cli [](https://github.com/jhb-software/payload-content-cli/actions/workflows/ci.yml) [](https://www.npmjs.com/package/@jhb.software/payload-content-cli) [](LICENSE) 一个用于管理 Payload CMS 内容的 CLI，专为 AI 代理构建。 ## 快速开始 ``` # 安装 pnpm add -D @jhb.software/payload-content-cli # 配置（在项目根目录） cat > .env << 'EOF' PAYLOAD_URL=http://localhost:3000 PAYLOAD_API_KEY=your-api-key-here PAYLOAD_AUTH_COLLECTION=api-keys PAYLOAD_OUTPUT_DIR=content # optional: directory for pulled content (default: content) EOF # 验证与发现 pnpm payload-content me pnpm payload-content discover # 安装代理技能，使 Claude Code 知道如何使用 CLI pnpm payload-content skill ``` 请参阅 [USAGE.md](USAGE.md) 获取完整的命令参考。 ## 为什么？ 代理与 CLI 配合最佳 — 结构化命令、可预测的 JSON 输出和可组合的标志。此 CLI 为代理（以及人类）提供了对 Payload REST API 的完整访问，无需编写任何集成代码： - **发现** — `me` 和 `discover` 在执行操作前告知代理可用的内容 - **完全的 REST API 对等性** — 所有 Payload 查询参数（`where`、`select`、`depth`、`locale`、`joins`、`populate`、`draft` 等）均作为 CLI 标志公开 - **所有操作** — `find`、`create`、`update`、`delete`、`count`、`versions`、`restore`、`duplicate`、`upload`，以及用于自定义端点的原始 `request` - **批量上传** — 使用并发上传、共享元数据和试运行支持，上传目录或媒体文件匹配模式 - **富文本精确编辑** — 无需重写整个树即可添加、移除、替换和修改单个节点 - **配置文件** — 为多个 Payload 实例保存连接设置，通过 `--profile` 切换 - **代理技能** — `payload-content skill` 安装一个 Claude Code 技能文件，以便代理知道如何使用 CLI - **编辑器验证** — 拉取的内容会引用一个生成的 JSON Schema，以便 IDE 实时标记缺失的必需字段、错误类型和无效枚举 ## 与官方 MCP 插件的比较 [官方 MCP 插件](https://github.com/payloadcms/payload-mcp) 在简单用例中运行良好，特别是在读取内容方面，但它增加了摩擦： - **需要设置** — MCP 插件需要安装和配置。CLI 只需要一个 API 密钥。 完整比较： | | MCP 插件（截至 2026年05月） | @jhb.software/payload-content-cli | | ------------------ | ----------------------------------------------------- | ------------------------------------------------------ | | 工具扩展性 | 每个集合每个操作一个工具 — 会快速膨胀 | 集合无关的命令 — 工具数量固定 | | REST API 对等性 | 部分 — 查询参数受限 | 完整 — 支持所有 Payload REST API 参数 | | 操作 | 缺少 `count`、版本等 | 所有集合 + 全局操作 | | 读取文档 | 良好 — 单次工具调用 | 良好 — `find` 或读取拉取的 JSON | | 更新单个字段 | 一般 — 需要完整的文档往返 | 良好 — 在文件中编辑一个字段 | | 编辑富文本 | 差 — 代理必须构建完整的 Lexical 树 | 良好 — `lexical add/replace/remove` 进行精确编辑 | | 批量编辑 | 差 — 每个文档一次 API 调用 | 良好 — 编辑文件，一次性推送 | | 冲突检测 | 无 | 内置 — 基于清单的差异比较 | | 试运行 | 不可能 | `push --dry-run` | | 离线工作 | 不可能 | `status` 无需网络即可工作 | | 设置 | 需要安装和配置 MCP 插件 | 只需一个 API 密钥 | | Token 成本 | 高 | 低 | CLI 和 MCP 并非相互排斥。虽然 MCP 插件非常适合简单用例，但 CLI 更适合更复杂的用例，特别是在需要编辑内容时。 ## 内容同步 对于批量编辑或离线工作流，CLI 可以将内容拉取到文件系统作为 JSON 文件，让您在本地编辑，然后将更改推送回去： ``` payload-content pull → JSON files on disk edit files → standard file tools payload-content push → changes sent to CMS ``` 清单会跟踪同步的内容，因此 `status` 可以离线显示本地更改，而 `push` 可以检测与远程的冲突。在提交前使用 `push --dry-run` 进行预览。 对于小型、有针对性的更改（更新标题、切换状态字段），CRUD 命令直接访问 API，无需任何本地文件。 ## 入门指南 请参阅 [USAGE.md](USAGE.md) 获取设置说明和完整的命令参考。 快速入门：`payload-content skill` 命令会安装一个代理技能文件，以便代理知道如何使用 CLI。 ## 路线图 请参阅 [ROADMAP.md](ROADMAP.md) 获取想法和未解决的问题。 ## 页脚 本项目是一个非官方的开源项目，可免费使用。它与 Payload CMS 或其官方 MCP 插件没有关联。如果您遇到任何问题或有任何反馈，请提交问题或拉取请求。

标签：AI代理, GNU通用公共许可证, MITM代理, Node.js, Payload CMS, REST API, 内容管理, 内容管理系统, 创建内容, 删除内容, 发现机制, 命令行界面, 媒体管理, 安全可观测性, 富文本编辑, 恶意代码分析, 批量上传, 操作管理, 文档结构分析, 无头CMS, 更新内容, 查询接口, 版本控制, 自动化攻击, 配置文件