CLI reference

Payload CMS projects use two command-line tools with similar names. The official Payload CLI creates projects, generates types and import maps, and manages database migrations. The community-built Payload Components CLI installs blocks and wires them into a Payload v3 project. It complements the Payload CLI; it does not replace it.

This guide maps each job to the right command, then documents every Payload Components command. Start with the table below if you arrived here looking for the Payload CMS CLI.

Which Payload CLI command should I run?

The pnpm payload ... examples assume your package.json has a payload script. If it does not, run the binary through your package manager or add the script used by the official starter. The commands after payload stay the same with npm, pnpm, or Yarn.

Use the official Payload CMS CLI

Create a new app

Payload's project initializer is the fastest route to a supported Payload v3 and Next.js app:

npx create-payload-app@latest

Choose the website starter when you want an existing Pages collection, blocks renderer, and media setup. A blank app can also accept Payload Components, but it needs the starter scaffold before a block can be wired.

See Payload's installation documentation for the current runtime requirements and starter choices.

Generate TypeScript types

Run type generation after changing collections, globals, or block fields:

pnpm payload generate:types

Payload reads your config and updates the generated declaration file. If the CLI cannot find the config, set PAYLOAD_CONFIG_PATH to its location for that command. The dedicated Payload type-errors guide covers stale generated types, config-path failures, and the checks to run before committing the output.

Payload's generated types documentation is the source of truth for typescript.outputFile and config-specific behavior.

Generate the admin import map

Payload normally regenerates the import map while the dev server runs. Generate it directly after moving admin components, changing component paths, or repairing a stale map:

pnpm payload generate:importmap

The Payload import-map command guide explains the output, custom config paths, and common repair sequence. Payload's custom-components documentation defines how component paths become import-map entries.

Run database migrations

Migration commands belong to the official Payload CLI. Create a migration after a schema change, inspect what is pending, then apply it in the environment that owns the database:

pnpm payload migrate:create
pnpm payload migrate:status
pnpm payload migrate

Payload also provides rollback and reset commands. Those can destroy or replace local data, so read the adapter-specific behavior before running them. Payload's migration documentation lists the complete command set and the production workflow.

Use the Payload Components CLI

Run the package help command to see the available commands and flags:

npx payload-components --help

Payload Components commands accept --cwd <path> when the target project is not the working directory. Commands that change files validate the project shape first. Planning commands such as diff, doctor, and --dry-run do not write to the target project.

Install blocks

add accepts any number of component names and installs each through the full wrapper pipeline, so one command can stand up a whole page:

npx payload-components add hero-basic faq-card pricing-cards

The component catalog builds this command for you: tick components as you browse and copy the single command from the tray at the bottom.

Repeats are collapsed, and each name is installed exactly once. Because every stage is idempotent, a name that is already installed is a no-op rather than an error.

Install from another registry

add also takes shadcn's namespaced form, so a block from someone else's registry installs through the same command:

npx payload-components add @acme/hero

The scope must be configured in your components.json (or package.json) first:

{
  "registries": {
    "@acme": "https://acme.example/r/{name}.json"
  }
}

Install a template

A template concept is a block set plus a page plan. add-template installs and wires every block it composes, then prints which blocks each page uses:

npx payload-components templates
npx payload-components add-template saas-launch

Add --demo to also write one seed script per page of the concept:

npx payload-components add-template saas-launch --demo

Each script creates a single draft Page holding that page's blocks, in the order the page composes them, and never publishes it. Every page owns its own private ownership record, so re-running one script updates only its own Page — the same adopt-or-refuse rules a single-component seed follows.

It validates your project shape before installing anything, so an unsupported repo fails on the first check rather than part-way through twenty blocks. --dry-run prints the block list and page plan without touching the project.

Localize

Payload internationalization has two halves that have to agree, and either one alone does nothing: the config declares which locales exist, and the block fields declare which text stores one value per locale. localize sets both, across every block already installed:

npx payload-components localize --locales en,zh

It inserts a localization block into your buildConfig({ ... }) call — labelled in each language, rtl where the script needs it — copies src/blocks/shared/localizeFields.ts, wraps each installed block config's field list in it, and records policy version semantic-v1 in install state so update re-applies the wrapper rather than reinstalling a config without it.

Every step is idempotent, so re-run it after installing more blocks. Once the locales are declared, drop the flag and it wraps only what is new:

npx payload-components localize

Naming components narrows it to those:

npx payload-components localize hero-basic faq-card

A single block — or every block of a template — can also be installed localized in one step, which is the same field-level transform without the config half:

npx payload-components add hero-basic --localized
npx payload-components add-template saas-launch --localized

On a template the locale notice is printed once for the run, not once per block.

localize refuses rather than guesses, exiting non-zero with the config or block left exactly as you wrote it. That includes a config with no buildConfig({ ... }) call, a localization value it cannot safely replace (such as a reference, assertion, or later spread), and an existing direct localization block that declares something else (--force replaces that last shape). A block config with local edits is skipped the same way, because wrapping it would re-baseline your edit as pristine.

See Internationalization for the full story — what localizeFields marks and deliberately does not, querying a locale from the front end, and translating the admin UI itself.

Maintain an install

A recorded install has a lifecycle. These four commands read and act on .payload-components/state.json.

list

npx payload-components list
npx payload-components list --json

Joins the registry catalog with what this project recorded: which components are installed, which are behind the version this CLI ships, and which recorded components no longer have a manifest. It works in any directory, including one that was never initialized.

diff

npx payload-components diff
npx payload-components diff hero-basic --json

Compares each recorded install against the source baseline captured by its successful install and reports three kinds of drift: a version behind this CLI, a file whose content no longer matches, and wiring that has gone missing. Comparison is content-normalized, so line endings and a trailing newline are never reported as edits.

Current installs record normalized source hashes in .payload-components/state.json. Older state is migrated automatically; the CLI carries the known pre-hash release baselines and fails closed when it cannot prove one, instead of guessing whether an upstream change is a local edit.

Mutating CLI invocations lock the target project for their full operation, including host-file patches and state writes. A second add, update, remove, seed, or init against the same project exits with the active command and PID instead of racing a read-modify-write step.

When a component is behind, diff also prints the changelog entries the upgrade would apply, and the migration any breaking entry demands — 0.1.0 → 0.2.0 on its own is not a decision anyone can make.

diff exits non-zero when anything has drifted, which makes it usable as a CI gate on install drift.

update

npx payload-components update
npx payload-components update hero-basic --force
npx payload-components update --accept-localization-policy-change

Re-installs recorded components at the version this CLI ships. Canonical source replacements and retired-file deletions are staged, then committed as one rollback-capable batch; add then reconciles dependencies, wiring, generators, and state through its idempotent stages. A failed upgrade no longer creates a window where the live component source is simply missing.

Local edits are protected. A component with a modified file is skipped, listed by name, and the command exits non-zero. Pass --force to overwrite it, or copy your edits out first. Run diff to see exactly which files are involved.

If an older recorded version has no reconstructable source baseline, it is protected the same way: update skips it until you review the installed files and explicitly pass --force.

Content-breaking upgrades are held back. A component whose changelog marks a pending version breaking is not installed at all — rewriting the files is the easy half, and you still have to migrate the documents already in your database. update prints the migration the manifest declares and exits non-zero until you pass --accept-breaking.

npx payload-components update --accept-breaking

These are separate decisions with separate flags: --force means "discard my local edits", while --accept-breaking means "I have migrated the manifest's content change".

Legacy localized installs have a third guard. They used field-type inference, which could localize URLs, prices, or form actions. After migrating those stored values back to global fields, --accept-localization-policy-change adopts the explicit semantic-v1 policies. The CLI updates source and state only; it never migrates the database.

With no names, update targets every component that is behind, left in a partial state, or recorded as localized under the legacy policy. A current non-localized install is not rewritten merely because older state predates the localization-policy field. --dry-run prints the plan.

Changelogs

Each manifest carries its own release notes, newest first:

"changelog": [
  {
    "version": "0.2.0",
    "summary": "Renamed the headline field.",
    "breaking": true,
    "dataMigration": "Rename the stored `heading` field to `title` before publishing."
  },
  { "version": "0.1.0", "summary": "Initial release." }
]

The registry validates this on every load: entries must be real semver, ordered newest first, include the manifest's own version, and a breaking entry must say what to migrate — otherwise update could refuse an upgrade without being able to tell you why. A component's newest entry also appears on its docs page once it has moved past its first release.

remove

npx payload-components remove hero-basic --dry-run
npx payload-components remove hero-basic --accept-stored-content
npx payload-components remove hero-basic --force --accept-stored-content

The inverse of an install: it deletes the files this component owns, unregisters the block, drops its imports, regenerates types and the import map, and removes its state record.

Owned source is protected. Removal refuses an exclusively owned file that changed after installation. It also refuses matching source or wiring with no install record, an unknown legacy baseline, or a retained orphan whose shared-file ownership cannot be resolved. Review and copy out anything you need first; --force is the explicit instruction to accept that destructive uncertainty.

Three things it deliberately does not do:

• Shared family files survive. A file another recorded component also ships is kept and reported. Ownership comes from each component's recorded install-time file set, so removing hero-basic while hero-video is installed leaves the shared hero field base in place even if a retained component's current manifest moved or disappeared.
• Package dependencies stay. The CLI cannot know whether your own code adopted them.
• Stored content is untouched. Existing Page documents keep their block data. A real removal therefore stops until you pass --accept-stored-content, confirming that you migrated or deleted those blocks in the admin. This consent is independent from --force, which only accepts source-ownership risk.

Removal is idempotent, and a repeat run that changes nothing skips the generators instead of spending minutes regenerating for no effect.

Use it from a coding agent

npx payload-components mcp

Runs a Model Context Protocol server over stdio, so an agent can search the catalog, read a component's install contract, and preview what an install would change — instead of guessing at component names.

{
  "mcpServers": {
    "payload-components": {
      "command": "npx",
      "args": ["-y", "payload-components", "mcp"]
    }
  }
}

Contribute a component

pnpm payload-components new hero-split

This is repository-only contributor tooling and is not part of the published consumer CLI. It scaffolds a whole component bundle in a checkout of this repository: the block source, manifest, registry item, doc page, and demo twin, plus entries in the demos registry, the docs sidebar, generated site-catalog projection, and README inventory table. Consumer CLI help derives its component list from the registry at runtime.

It then prints what it deliberately did not decide — its editorial entry in src/lib/component-catalog.ts, its dbName abbreviation with a uniqueness check against every existing block, the Content model prose, and the demo sample content. See the component template README for the full workflow.

Set up and diagnose

npx payload-components init
npx payload-components doctor
npx payload-components doctor --json
npx payload-components seed hero-basic

init creates the components.json that registry installs need. doctor runs a read-only health check — see Installation. seed writes the demo seed script for an already-installed component.

doctor --json emits the same run as a structured report. Every finding carries a scope (project, scripts, state, or a component name) so a CI job can group results without parsing prose, and the exit code separates the two failures that need different responses: 2 means the project itself cannot accept installs, 1 means the project is fine but a recorded install has drifted.

Supported project shapes

Installs are gated on a recognised project shape. Two are supported, matched in order:

A target declares candidate paths per file plus the anchors the patcher needs, so a file at the right path with the wrong shape is not a match. doctor prints which files it resolved.

Starting from a bare Payload app

A project scaffolded by create-payload-app has none of the pieces an install needs: no blocks renderer, no Pages collection with a layout field, and none of the primitives installed blocks import. init --scaffold lays that base down:

npx payload-components init --scaffold

It copies eight files and registers two collections in your Payload config:

The result is the official starter's shape, which is why a scaffolded project then detects as payload-website-starter rather than as a target of its own. The CLI records only files whose bytes came from this scaffold. Matching starter files are adopted; custom existing implementations stay unowned. A later init --scaffold updates pristine managed files and reports local edits, while init --scaffold --force explicitly replaces those managed edits.

Exit codes