Payload CMS Operations

Manage Payload CMS content using the Local API (preferred) or REST API. Includes markdown-to-Lexical JSON conversion for rich text fields.

When to Use

• Creating or editing posts/pages in Payload CMS
• Converting markdown content to Lexical rich text format
• Listing and querying Payload collections
• Bulk content updates

Authentication Strategy

Payload offers two API approaches:

Prefer Local API for CLI workflows. It runs server-side with full database access and no authentication overhead.

Local API Workflow

Run TypeScript scripts from the Payload project directory. The .env file already contains required credentials:

# From the Payload project directory (e.g., ~/code/bopen-ai)
source .env && bunx tsx scripts/update-post.ts my-post-slug content.json

Or inline for one-off commands:

PAYLOAD_SECRET="$PAYLOAD_SECRET" DATABASE_URI="$DATABASE_URI" bunx tsx scripts/update-post.ts slug content.json

List Posts

source .env && bunx tsx scripts/list-posts.ts

Update Post Content

1. Convert markdown to Lexical JSON
2. Run the update script

# Convert markdown
python3 scripts/md_to_lexical.py article.md > /tmp/content.json

# Update the post
source .env && bunx tsx scripts/update-post.ts my-post-slug /tmp/content.json

Create New Post

source .env && bunx tsx scripts/create-post.ts "Post Title" post-slug /tmp/content.json

Markdown to Lexical Conversion

Payload's Lexical editor stores content as JSON. Convert markdown using the included Python script:

python3 scripts/md_to_lexical.py input.md > output.json

Lexical JSON Structure

{
  "root": {
    "type": "root",
    "format": "",
    "indent": 0,
    "version": 1,
    "children": [
      { "type": "paragraph", ... },
      { "type": "heading", "tag": "h2", ... }
    ],
    "direction": "ltr"
  }
}

Supported Markdown Elements

Text Format Bitmask

Inline Script Example

For simple updates without the helper scripts:

import { getPayload } from "payload";
import configPromise from "@payload-config";

const payload = await getPayload({ config: configPromise });

// Find post by slug
const result = await payload.find({
  collection: "posts",
  where: { slug: { equals: "my-post" } },
});

// Update content
await payload.update({
  collection: "posts",
  id: result.docs[0].id,
  data: {
    content: { root: { ... } },
  },
});

Common Collections

Additional Resources

Reference Files

• references/lexical-format.md - Complete Lexical node type reference with all fields
• references/rest-api.md - REST API documentation for external access

Scripts

• scripts/md_to_lexical.py - Python markdown-to-Lexical converter
• scripts/md-to-lexical.sh - Bash wrapper for conversions
• scripts/list-posts.ts - List posts using Local API
• scripts/update-post.ts - Update post content using Local API
• scripts/create-post.ts - Create new post using Local API

Troubleshooting

"Cannot find module '@payload-config'" Run scripts from the Payload project root directory where tsconfig.json defines this path alias.

"PAYLOAD_SECRET is required" Set the environment variable. Check the project's .env file for the correct value.

"Database connection failed" Verify DATABASE_URI is correct and the database is accessible.

Post not updating Check the post's _status field. Posts must be "published" to appear on the site.