Persistent HTTP server + thin CLI client for Payload CMS Local API.

用于Payload CMS Local API的持久化HTTP服务器+轻量CLI客户端。

Quick Start

快速开始

bash

undefined

bash

undefined

Resolve plugin root even when CLAUDE_PLUGIN_ROOT is missing

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(node -e "const fs=require('fs');const path=require('path');const os=require('os');const c=['C:/.config/vercel-skills/skills/payload-cms',path.join(os.homedir(),'.claude/skills/payload-cms'),path.join(os.homedir(),'.agents/skills/payload-cms'),'P:/aromatt/payload/skills/payload-cms'];const hit=c.find(p=>fs.existsSync(path.join(p,'scripts','payload.js')));if(!hit){process.exit(1)};process.stdout.write(hit);")}"

1. Start the server (from project root)

1. 启动服务器（从项目根目录执行）

node "$PLUGIN_ROOT/scripts/payload.js" start

2. Query data

2. 查询数据

node "$PLUGIN_ROOT/scripts/payload.js" find users --limit 5 node "$PLUGIN_ROOT/scripts/payload.js" schema tutors

undefined

node "$PLUGIN_ROOT/scripts/payload.js" find users --limit 5 node "$PLUGIN_ROOT/scripts/payload.js" schema tutors

undefined

CLI

bash

node "$PLUGIN_ROOT/scripts/payload.js" $ARGUMENTS

Run with

help

for full command list. Use

$PLUGIN_ROOT

from Quick Start in all examples below when

CLAUDE_PLUGIN_ROOT

is not set.

bash

node "$PLUGIN_ROOT/scripts/payload.js" $ARGUMENTS

运行时加上

help

参数获取完整命令列表。当未设置CLAUDE_PLUGIN_ROOT时，所有示例请使用快速开始中的

$PLUGIN_ROOT

。

Server Lifecycle

服务器生命周期

The server initializes Payload once and serves requests over HTTP. This avoids re-initializing Payload for each query (~10-15s cold start).

Command	Description
`start [flags]`	Start persistent Payload server (background)
`stop`	Graceful shutdown
`status`	Check if server is running + uptime

服务器会初始化一次Payload，并通过HTTP处理请求。这样避免了每次查询都重新初始化Payload（冷启动约10-15秒）。

命令	描述
`start [flags]`	启动持久化Payload服务器（后台运行）
`stop`	优雅关闭服务器
`status`	检查服务器是否运行及运行时长

Start Flags

启动参数

Flag	Default	Description
`--port`	`8100`	HTTP port
`--idle-timeout`	`1800000`	Auto-shutdown after idle (ms, default 30min)
`--test-db-url`	env `TEST_POSTGRES_URL`	Test database connection string
`--test-db-port`	env `POSTGRES_TEST_PORT` or `7357`	Test database port

参数	默认值	描述
`--port`	`8100`	HTTP端口
`--idle-timeout`	`1800000`	空闲自动关闭超时时间（毫秒，默认30分钟）
`--test-db-url`	环境变量 `TEST_POSTGRES_URL`	测试数据库连接字符串
`--test-db-port`	环境变量 `POSTGRES_TEST_PORT` 或 `7357`	测试数据库端口

Examples

示例

bash

undefined

bash

undefined

Start with defaults

使用默认配置启动

node $PLUGIN_ROOT/scripts/payload.js start

Start with custom port and test DB

使用自定义端口和测试数据库启动

node $PLUGIN_ROOT/scripts/payload.js start --port 9000 --test-db-url "postgresql://localhost:7357/test"

Check status

检查状态

node $PLUGIN_ROOT/scripts/payload.js status

Stop server

停止服务器

node $PLUGIN_ROOT/scripts/payload.js stop

---

node $PLUGIN_ROOT/scripts/payload.js stop

---

Schema & Discovery

架构与发现

Command	Description
`collections list`	List all collection slugs, field counts, labels
`schema <collection>`	Full field definitions (name, type, required, relationships)

Schema includes recursive field mapping for: text, number, email, relationship, upload, array, group, blocks, select, radio, checkbox, date, point, json, code, richText, tabs, collapsible, row.

命令	描述
`collections list`	列出所有集合别名、字段数量和标签
`schema <collection>`	获取完整字段定义（名称、类型、必填项、关联关系）

Schema包含以下字段的递归映射：text、number、email、relationship、upload、array、group、blocks、select、radio、checkbox、date、point、json、code、richText、tabs、collapsible、row。

Examples

示例

bash

undefined

bash

undefined

List all collections

列出所有集合

node $PLUGIN_ROOT/scripts/payload.js collections list

Get schema for a collection

获取某个集合的Schema

node $PLUGIN_ROOT/scripts/payload.js schema users node $PLUGIN_ROOT/scripts/payload.js schema calendarEntries

---

node $PLUGIN_ROOT/scripts/payload.js schema users node $PLUGIN_ROOT/scripts/payload.js schema calendarEntries

---

Query Operations

查询操作

All query commands require a running server (

start

first).

Command	Description
`find <collection> [flags]`	Find documents with filters, sort, pagination
`find-by-id <collection> --id <id> [flags]`	Get a single document by ID
`count <collection> [flags]`	Count matching documents

所有查询命令需要先启动服务器（执行

start

命令）。

命令	描述
`find <collection> [flags]`	使用筛选器、排序、分页查找文档
`find-by-id <collection> --id <id> [flags]`	通过ID获取单个文档
`count <collection> [flags]`	统计匹配的文档数量

Query Flags

查询参数

Flag	Description	Example
`--db`	Database: `dev` (default) or `test`	`--db test`
`--where`	JSON filter object	`--where '{"status":{"equals":"active"}}'`
`--sort`	Sort field (prefix `-` for desc)	`--sort -createdAt`
`--limit`	Max results	`--limit 10`
`--page`	Page number (1-indexed)	`--page 2`
`--depth`	Population depth (default 1)	`--depth 0`
`--select`	Field selection	`--select '{"name":true,"email":true}'`
`--timeout`	Per-request timeout (ms)	`--timeout 60000`

参数	描述	示例
`--db`	数据库： `dev` （默认）或 `test`	`--db test`
`--where`	JSON筛选对象	`--where '{"status":{"equals":"active"}}'`
`--sort`	排序字段（前缀 `-` 表示降序）	`--sort -createdAt`
`--limit`	最大结果数	`--limit 10`
`--page`	页码（从1开始）	`--page 2`
`--depth`	关联数据加载深度（默认1）	`--depth 0`
`--select`	字段选择	`--select '{"name":true,"email":true}'`
`--timeout`	单请求超时时间（毫秒）	`--timeout 60000`

Where Clause Operators

Where子句操作符

json

{ "field": { "equals": "value" } }
{ "field": { "not_equals": "value" } }
{ "field": { "greater_than": 100 } }
{ "field": { "less_than": 100 } }
{ "field": { "like": "partial" } }
{ "field": { "contains": "text" } }
{ "field": { "in": ["a", "b"] } }
{ "field": { "not_in": ["a", "b"] } }
{ "field": { "exists": true } }

Compound:

json

{ "and": [{ "status": { "equals": "active" } }, { "role": { "equals": "tutor" } }] }
{ "or": [{ "status": { "equals": "active" } }, { "status": { "equals": "pending" } }] }

json

{ "field": { "equals": "value" } }
{ "field": { "not_equals": "value" } }
{ "field": { "greater_than": 100 } }
{ "field": { "less_than": 100 } }
{ "field": { "like": "partial" } }
{ "field": { "contains": "text" } }
{ "field": { "in": ["a", "b"] } }
{ "field": { "not_in": ["a", "b"] } }
{ "field": { "exists": true } }

复合条件：

json

{ "and": [{ "status": { "equals": "active" } }, { "role": { "equals": "tutor" } }] }
{ "or": [{ "status": { "equals": "active" } }, { "status": { "equals": "pending" } }] }

Query Examples

查询示例

bash

undefined

bash

undefined

Find first 5 users

查找前5个用户

node $PLUGIN_ROOT/scripts/payload.js find users --limit 5

Find active tutors sorted by name

查找活跃的导师并按名称排序

node $PLUGIN_ROOT/scripts/payload.js find tutors --where '{"status":{"equals":"active"}}' --sort name

Find recent calendar entries

查找最近的日历条目

node $PLUGIN_ROOT/scripts/payload.js find calendarEntries --sort -createdAt --limit 10

Count customers

统计客户数量

node $PLUGIN_ROOT/scripts/payload.js count customers

Get user by ID with minimal depth

通过ID获取用户，最小关联深度

node $PLUGIN_ROOT/scripts/payload.js find-by-id users --id abc123 --depth 0

Select specific fields only

仅选择特定字段

node $PLUGIN_ROOT/scripts/payload.js find users --select '{"email":true,"name":true}' --limit 10

Query test database

查询测试数据库

node $PLUGIN_ROOT/scripts/payload.js find users --db test --limit 5

---

node $PLUGIN_ROOT/scripts/payload.js find users --db test --limit 5

---

Mutate Operations

修改操作

Command	Description
`create <collection> --data <json> [flags]`	Create a new document
`update <collection> --id <id> --data <json> [flags]`	Update an existing document
`delete <collection> --id <id>`	Delete a document

Data can be passed via

--data

flag or piped through stdin.

命令	描述
`create <collection> --data <json> [flags]`	创建新文档
`update <collection> --id <id> --data <json> [flags]`	更新现有文档
`delete <collection> --id <id>`	删除文档

数据可通过

--data

参数传递，或通过标准输入管道传入。

Mutate Flags

修改参数

Flag	Description
`--data`	JSON string with document data
`--id`	Document ID (required for update/delete)
`--db`	Database: `dev` (default) or `test`
`--depth`	Population depth in response
`--select`	Field selection in response

参数	描述
`--data`	包含文档数据的JSON字符串
`--id`	文档ID（更新/删除时必填）
`--db`	数据库： `dev` （默认）或 `test`
`--depth`	响应中的关联数据加载深度
`--select`	响应中的字段选择

Mutate Examples

修改示例

bash

undefined

bash

undefined

Create a document

创建文档

node $PLUGIN_ROOT/scripts/payload.js create customers --data '{"name":"John","email":"john@example.com"}'

Create via stdin pipe

通过标准输入管道创建

echo '{"name":"Jane","email":"jane@example.com"}' | node $PLUGIN_ROOT/scripts/payload.js create customers

Update a document

更新文档

node $PLUGIN_ROOT/scripts/payload.js update customers --id abc123 --data '{"name":"John Updated"}'

Delete a document

删除文档

node $PLUGIN_ROOT/scripts/payload.js delete customers --id abc123

Mutate on test database

在测试数据库中执行修改操作

node $PLUGIN_ROOT/scripts/payload.js create customers --db test --data '{"name":"Test User"}'

---

node $PLUGIN_ROOT/scripts/payload.js create customers --db test --data '{"name":"Test User"}'

---

Output Format

输出格式

All commands output JSON to stdout:

json

// Success
{ "ok": true, "data": { ... } }

// Error
{ "ok": false, "error": { "message": "...", "code": "..." } }

Find results include Payload pagination:

json

{
  "ok": true,
  "data": {
    "docs": [...],
    "totalDocs": 42,
    "limit": 10,
    "totalPages": 5,
    "page": 1,
    "pagingCounter": 1,
    "hasPrevPage": false,
    "hasNextPage": true,
    "prevPage": null,
    "nextPage": 2
  }
}

所有命令均向标准输出输出JSON：

json

// Success
{ "ok": true, "data": { ... } }

// Error
{ "ok": false, "error": { "message": "...", "code": "..." } }

查询结果包含Payload分页信息：

json

{
  "ok": true,
  "data": {
    "docs": [...],
    "totalDocs": 42,
    "limit": 10,
    "totalPages": 5,
    "page": 1,
    "pagingCounter": 1,
    "hasPrevPage": false,
    "hasNextPage": true,
    "prevPage": null,
    "nextPage": 2
  }
}

Architecture

架构

payload.js (CLI client, CommonJS, zero deps)
    │
    ▼ HTTP
server.ts (persistent, initialized Payload instances)
    │
    ▼ Local API
Payload CMS (dev DB + optional test DB)

Server starts once, stays running (30min idle timeout)
Each CLI call makes an HTTP request to the running server

Server PID + port stored in

${PAYLOAD_CMS_HOME:-~/.payload-cms}/server.json

payload.js (CLI client, CommonJS, zero deps)
    │
    ▼ HTTP
server.ts (persistent, initialized Payload instances)
    │
    ▼ Local API
Payload CMS (dev DB + optional test DB)

服务器启动一次后保持运行（30分钟空闲超时）
每次CLI调用向运行中的服务器发送HTTP请求

服务器PID和端口存储在

${PAYLOAD_CMS_HOME:-~/.payload-cms}/server.json

中

payload-cms

Original

Translation

Quick Start

快速开始

Resolve plugin root even when CLAUDE_PLUGIN_ROOT is missing

Resolve plugin root even when CLAUDE_PLUGIN_ROOT is missing

1. Start the server (from project root)

1. 启动服务器（从项目根目录执行）

2. Query data

2. 查询数据

CLI

CLI

Server Lifecycle

服务器生命周期

Start Flags

启动参数

Examples

示例

Start with defaults

使用默认配置启动

Start with custom port and test DB

使用自定义端口和测试数据库启动

Check status

检查状态

Stop server

停止服务器

Schema & Discovery

架构与发现

Examples

示例

List all collections

列出所有集合

Get schema for a collection

获取某个集合的Schema

Query Operations

查询操作

Query Flags

查询参数

Where Clause Operators

Where子句操作符

Query Examples

查询示例

Find first 5 users

查找前5个用户

Find active tutors sorted by name

查找活跃的导师并按名称排序

Find recent calendar entries

查找最近的日历条目

Count customers

统计客户数量

Get user by ID with minimal depth

通过ID获取用户，最小关联深度

Select specific fields only

仅选择特定字段

Query test database

查询测试数据库

Mutate Operations

修改操作

Mutate Flags

修改参数

Mutate Examples

修改示例

Create a document

创建文档

Create via stdin pipe

通过标准输入管道创建

Update a document

更新文档

Delete a document

删除文档

Mutate on test database

在测试数据库中执行修改操作

Output Format

输出格式

Architecture

架构