payload-post

payload-post 是一個給 Payload CMS 使用的終端機 CLI，主打管理 posts 內容、支援腳本化操作，也支援帳密登入到任意專案。

特色

• 支援 list、create、update、delete、publish 指令
• 支援 --config 指定不同專案設定檔
• 支援 --profile 切換多網站 / 多帳號設定
• 支援 --json，方便管線處理與 jq
• 支援 --verbose，可顯示實際 HTTP request
• 支援三種認證方式：
  • jwt
  • apiKey
  • login（username/password 或 email/password）
• 內建一個 Ink TUI 預覽頁面：tui

安裝

全域安裝

npm install -g @anlstudio/payload-post-cli

安裝完成後會提供 payload-post 指令：

payload-post --help
payload-post list

一次性執行

如果你只是想先試用，不需要全域安裝：

npx @anlstudio/payload-post-cli --help

從原始碼開發

如果你是從這個 repo 本地開發：

npm install

開發

啟動開發模式：

npm run dev

建置專案：

npm run build

執行測試：

npm test

型別檢查：

npm run typecheck

使用方式

首次使用時，先建立設定檔：

payload-post config init

這會在 ~/.config/payload-post/ 產生 payload-post.config.ts（可用 --out <dir> 指定其他目錄）。

設定檔

載入順序：

1. 目前目錄尋找以下其中一個檔案：

• payload-post.config.ts
• payload-post.config.mts
• payload-post.config.js
• payload-post.config.mjs
• payload-post.config.cjs
• payload-post.config.json

2. 若目前目錄無設定檔，則回退到 ~/.config/payload-post/payload-post.config.ts

你也可以用 --config 指定路徑。

範例設定

import type { PayloadPostWorkspaceConfig } from '@anlstudio/payload-post-cli';

export default {
  defaultProfile: 'main',
  profiles: {
    main: {
      baseUrl: 'http://localhost:3000',
      collection: 'posts',
      auth: {
        type: 'login',
        collection: 'users',
        username: 'writer',
        password: 'secret',
      },
      list: {
        columns: ['title', 'slug', 'status', 'updatedAt'],
        searchFields: ['title', 'slug', 'excerpt', 'content'],
      },
      fields: {
        id: 'id',
        title: 'title',
        slug: 'slug',
        status: 'status',
        excerpt: 'excerpt',
        content: 'content',
        updatedAt: 'updatedAt',
        publishedAt: 'publishedAt',
        author: 'author',
      },
    },
    // Add more sites or accounts here.
    // newsroom: {
    //   baseUrl: 'https://news.example.com',
    //   collection: 'articles',
    //   auth: { type: 'jwt', token: 'replace-me' },
    //   list: {
    //     columns: ['slug', 'title', 'status'],
    //     searchFields: ['slug'],
    //   },
    //   fields: {
    //     id: 'id',
    //     title: 'headline',
    //     slug: 'slug',
    //     status: 'state',
    //     excerpt: 'summary',
    //     content: 'body',
    //     updatedAt: 'updated_at',
    //     publishedAt: 'published_at',
    //     author: 'author',
    //   },
    // },
  },
} satisfies PayloadPostWorkspaceConfig;

認證方式

1. JWT

auth: {
  type: 'jwt',
  token: 'replace-me',
}

2. API Key

auth: {
  type: 'apiKey',
  key: 'replace-me',
  collection: 'users',
}

3. 帳密登入

適合你想直接對某個專案登入使用時：

auth: {
  type: 'login',
  collection: 'users',
  username: 'writer',
  password: 'secret',
}

也可以改成 email：

auth: {
  type: 'login',
  collection: 'users',
  email: '[email protected]',
  password: 'secret',
}

login 會先呼叫 Payload 的登入 API 取得 JWT，再用該 JWT 存取 posts collection。

指令

列出文章

payload-post list
payload-post list --status draft
payload-post list --search hello
payload-post list --limit 20 --page 2
payload-post --profile newsroom list

建立文章

payload-post create --title "Hello" --slug hello

更新文章

payload-post update 123 --title "New title"

刪除文章

payload-post delete 123
payload-post delete 123 --yes

發佈 / 取消發佈

payload-post publish 123
payload-post publish 123 --unpublish

顯示 TUI 預覽

payload-post tui
payload-post tui --once

全域 flags

• --config <path>：指定設定檔
• --profile <name>：從多 profile 設定檔中選擇網站 / 帳號，例如 payload-post --profile newsroom list
• --verbose：顯示 HTTP request
• --json：輸出原始 JSON，方便 pipe 到其他工具

範例

輸出 JSON 並交給 jq：

payload-post --json list | jq '.docs[0].title'

使用自訂設定檔：

payload-post --config ./configs/blog.config.json list

切換到另一個網站或帳號：

payload-post --profile newsroom list

Payload 相容性說明

這個 CLI 是為 Payload CMS 的 posts 流程設計，預設假設：

• 你的 Payload 專案有 posts collection
• fields 已經映射到你的實際欄位名稱
• 若你要用帳密登入，對應的 auth collection 必須允許登入

需求環境

• Node.js 18+
• Payload CMS 專案

升級與移除

升級到最新版：

npm install -g @anlstudio/payload-post-cli@latest

解除安裝：

npm uninstall -g @anlstudio/payload-post-cli

AI Agent Authoring

payload-post CLI 支援 AI agent 作為子程序呼叫，透過 Markdown 撰寫文章內文。CLI 會自動將 Markdown 轉換為 Lexical JSON，agent 不需要知道 Lexical 內部結構。

支援的 Markdown 元素

| 元素 | 語法 | |------|------| | 標題 (H1-H6) | # Heading ~ ###### Heading | | 粗體 | **bold** 或 __bold__ | | 斜體 | *italic* 或 _italic_ | | 刪除線 | ~~strikethrough~~ | | 水平線 | --- | | 無序列表 | - item 或 * item | | 有序列表 | 1. item | | 引用 | > blockquote | | 行內程式碼 | `code` | | 程式碼區塊 | ``` | | 連結 | [text](url) | | 表格 | \|a\|b\|\n\|---\|---\|\n\|1\|2\| |

直接傳入 Markdown

# 簡單範例
payload-post create --title "Hello" --content "# Welcome\n\nThis is **bold** text"

# 完整 Agent 流程
payload-post create --title "Draft" --content "# Getting Started\n\nWelcome to the guide.\n\n## Setup\n\n1. Install\n2. Configure"

從檔案讀取 Markdown (@path)

# 從 Markdown 檔案建立文章
payload-post create --title "My Post" --content @post.md

# 預覽 Lexical JSON 輸出（不實際發送）
payload-post create --title "Preview" --content @post.md --dry-run

完整 Agent Pipeline

# 建立草稿
ID=$(payload-post create --title "Draft" --content "# Draft\n\nContent here" --json | jq -r '.id')

# 更新內容
payload-post update "$ID" --content "# Published\n\nUpdated content with **rich text**"

# 發佈
payload-post publish "$ID" --yes

與 contentTemplate 的互動

當同時設定 contentTemplate 且輸入為 Markdown 時，Markdown 會先轉換為 Lexical JSON，再套用 template 包裝節點。這讓 agent 可以用 Markdown 撰寫內文，同時保留 template 的結構（圖片、嵌入等）。

payload-post create --title "Rich Post" --content "# My Content\n\n**bold**" --content-template template.json

專案開發備註

• v0.1 以非互動式 CRUD 為主
• v0.2 加入 Markdown→Lexical 轉換、TUI 表單操作、$EDITOR 整合