pcms

PCMS — Payload CMS CLI

Manage content on any Payload CMS instance directly from the terminal.

Requires the pcms CLI: npm install -g @mirkobozzetto/pcms-cli Source and docs: https://github.com/mirkobozzetto/pcms-cli

Prerequisites

• pcms installed globally (npm install -g @mirkobozzetto/pcms-cli)
• Authenticated: pcms auth login --domain https://your-site.com

Context

• Auth status: !pcms auth status 2>&1
• PCMS version: !pcms --version 2>&1

Argument Routing

When the user's intent is ambiguous, ask before executing.

Setup Guide (triggered by init)

Install

npm install -g @mirkobozzetto/pcms-cli

Authenticate

pcms auth login --domain https://your-payload-instance.com

Email and password are prompted interactively. Credentials stored in ~/.config/pcms/credentials.json.

Verify

pcms collections

Should list available collections (posts, pages, categories, etc.).

Quick Reference

# Auth
pcms auth login --domain <url> --email <email>
pcms auth status
pcms auth me
pcms auth profiles

# Collections
pcms collections
pcms collections schema <collection>
pcms collections count <collection> --where '<query>'

# Documents
pcms documents list <collection> --where '<query>' --sort '-createdAt' --limit 10
pcms documents get <collection> <id>
pcms documents list <collection> --draft  # include drafts
pcms documents create <collection> --title "Title" --status draft
pcms documents create <collection> --title "Title" --author 1 --category 3 --tags 5,8
pcms documents create <collection> --title "Title" --image ./photo.jpg  # upload + link
pcms documents create <collection> --md --input ./article.md
pcms documents update <collection> <id> --title "New Title" --status published
pcms documents delete <collection> <id> --force

# Publishing
pcms publish <collection> <id>
pcms unpublish <collection> <id>

# Media
pcms media upload ./image.jpg --alt "Description"

# Search
pcms search "query" --limit 10

# Import / Export
pcms import ./article.md --collection posts --status draft
pcms bulk-import ./posts-dir/ --collection posts --status draft
pcms export <collection> <id> -f md -o ./output.md

# Versions
pcms versions <collection> <id>
pcms restore <collection> <versionId>

# Globals
pcms globals
pcms globals <slug>
pcms global:update <slug> --data '{"key": "value"}'

Critical Rules

1. Always verify auth before executing commands — if auth status fails, guide login
2. Never delete without confirmation — always use --force explicitly, and confirm with user first
3. Default to draft — when creating content, always use --status draft unless the user says otherwise
4. Markdown import — for articles with rich content, prefer pcms import with a markdown file over --title/--content flags
5. Where clause — use Payload's native syntax: status[equals]=published, title[like]=keyword
6. Parse output — pcms returns JSON for list/get/search commands. Extract relevant fields for clean display
7. Batch operations — use pcms bulk-import ./directory/ --collection posts instead of shell loops
8. Error handling — if a command fails, read the error message carefully. Common issues: auth expired (re-login), missing required fields, invalid collection name
9. Lexical content with links — the CLI's markdownToLexical() generates link nodes that may cause Lexical error #117 on some Payload versions. When creating content with links via --data, use this link node format:

   {"type":"link","version":3,"format":"","indent":0,"direction":"ltr","fields":{"url":"https://...","linkType":"custom","newTab":true},"children":[{"mode":"normal","text":"link text","type":"text","format":0}]}
   

   For complex articles with many links, build the Lexical JSON via a Node.js script rather than using --md or --content.
10. _status field — Payload uses _status (with underscore) for the draft/publish system, not status. The CLI maps --status to _status automatically since v1.7.0.

Service-Specific References

For detailed commands and workflow patterns:

• Authentication: See references/auth.md
• Documents: See references/documents.md
• Media: See references/media.md
• Content workflows: See references/content-workflows.md
• Markdown format: See references/markdown-format.md