---

name: payload-content description: | Manages Payload CMS content via the payload-content CLI. Supports CRUD operations, content sync (pull/push), richtext editing, and locale management. Use when reading, creating, updating, deleting, or syncing CMS content, editing richtext nodes, or working with locales. user-invocable: false

Payload Content CLI

Manages Payload CMS content from the command line. Provides two modes: direct CRUD for simple changes and file-based content sync for bulk edits.

Overview

The payload-content CLI connects to a Payload CMS instance and exposes content operations. CRUD commands (find, update, create, delete, upload) work directly against the API. Content sync (pull → edit → push) downloads documents as JSON files for local editing.

Run payload-content --help to discover all commands and options.

Prerequisites

• payload-content CLI installed and on PATH

• Environment configured with required environment variables

• Plugin is optional — needed only for _schema.json / _jsonschema.json files, virtual-field stripping, and custom endpoint metadata in discover. Run payload-content discover to check whether it is installed. To install it, add to payload.config.ts:

  import { contentCliPlugin } from "payload-content-cli/plugin";
  
  export default buildConfig({
    plugins: [contentCliPlugin()],
  });
  

Instructions

Step 1: Verify connectivity and discover the API

Before doing any real work, always run these two commands:

payload-content me                # confirm auth works
payload-content discover          # list collections, globals, and custom endpoints

discover lists available collection and global slugs. If the content-cli plugin is installed, it also lists custom endpoints registered by plugins (with descriptions and schemas).

Step 2: Choose the right mode for the task

• Quick CRUD (find, update, create, delete, upload) — for simple, targeted changes: toggling a status, updating a title, uploading media, checking a field value. No local files needed.
• Content sync (pull → edit → push) — for bulk edits, richtext changes, or when the full document structure is needed. Edit files locally and push once.

Start with CRUD. Escalate to content sync when constructing JSON inline becomes harder than editing files.

Important: For create, update, and request commands, prefer --file over --data. Write your JSON to a temporary file and pass it with --file. Only use --data for trivially small inline JSON (e.g. a single field). Never pipe cat into --data.

Step 3: Read schemas before editing

Read _schema.json files to understand field types. Fields with virtual: true are computed and read-only — never include them in updates.

Step 4: Minimize response size

• Use --select to request only needed fields. Works on find, create, and update.
• Use --depth 0 to avoid expanding relationships. Only increase depth when populated data is actually needed.
• Use --where to scope operations: '{"slug":{"equals":"hello"}}' (Payload query syntax as JSON).

Step 5: Preview before writing

Use --dry-run on push to preview changes before committing them.

Step 6: Use lexical subcommands for richtext

Prefer lexical subcommands (add, remove, replace, set) over rewriting the entire Lexical tree. Use lexical list to see node structure first. Pipe nodes between files with lexical get and lexical add.

Step 7: Handle locales

Pull multiple locales (--locale en de), use lexical diff to compare, and lexical link --from to sync links between locale files.

Output

Commands return JSON to stdout. CRUD commands return the affected document(s). Content sync writes JSON files to a local content directory. payload-content status shows pending changes as a diff summary.

Examples

Quick read — only fetch what you need

payload-content find posts --where '{"slug":{"equals":"hello"}}' --select '{"title":true,"slug":true}' --depth 0

Quick update

# For non-trivial data, write a file and use --file
payload-content update posts <id> --file changes.json --select '{"id":true,"title":true}'
# For single-field updates, inline --data is fine
payload-content update posts <id> --data '{"title":"New Title"}' --select '{"id":true,"title":true}'

Bulk workflow

payload-content pull --collections posts
# ... edit files ...
payload-content status          # see what changed
payload-content push --dry-run  # preview
payload-content push            # commit

Upload media

payload-content upload media --file ./photo.jpg --data '{"alt":"Hero image"}'
payload-content upload media --url "https://example.com/image.png" --data '{"alt":"Remote image"}'
echo '<svg>...</svg>' | payload-content upload media --filename icon.svg --data '{"alt":"Icon"}'

Richtext surgery

payload-content lexical list <file>
payload-content lexical add <file> --at 0 --position after --paragraph "New text."

Error Handling

| Error | Cause | Solution | | -------------------------------- | ----------------------------------- | ----------------------------------------------------------- | | Auth failure on any command | Missing or expired credentials | Run payload-content me to verify auth configuration | | Virtual field in update payload | Included a virtual: true field | Read _schema.json and remove virtual fields from the data | | Unexpected nested objects | Default depth expands relationships | Add --depth 0 to keep references as IDs | | Push conflict or unexpected diff | Stale local files | Re-pull, review status, then push again |

Run payload-content <command> --help for full options on any command.