WP-CLI commands

Last updated Oct 3, 20265 min read

All commands start with wp wpmcf. They are available whenever the plugin is active and WP-CLI loads WordPress. They do the same work as the screens, without browser limits (no 5 MB upload form, no cron needed), so they suit deployments and big sites.

Command	Does	Needs
`wp wpmcf export`	Export definitions as JSON
`wp wpmcf import <file>`	Import a JSON file
`wp wpmcf json status` / `sync`	Local JSON folder state and sync
`wp wpmcf acf report` / `migrate`	ACF migration	ACF data on the site
`wp wpmcf tasks list` / `run`	Background tasks
`wp wpmcf code list` / `sync`	Field groups registered in PHP	See Integrations

Add --url=<site url> on multisite so the command runs for the right site, and --user=<admin> where your setup needs it.

`wp wpmcf export`

wp wpmcf export [--kinds=<list>] [--items=<list>] [--file=<path>]

Option	Meaning
`--kinds=<list>`	Comma-separated kinds to export completely: `field_groups`, `post_types`, `taxonomies`, `options_pages`.
`--items=<list>`	Comma-separated single items as `kind:key`, for example `field_groups:book_details,post_types:book`.
`--file=<path>`	Write to this file instead of standard output.

With neither --kinds nor --items, everything is exported. --kinds and --items can be combined. The output is the same document the Tools screen downloads (see Export and import (JSON)).

bash

wp wpmcf export > definitions.json
wp wpmcf export --kinds=field_groups --file=field-groups.json
wp wpmcf export --items=field_groups:book_details,post_types:book --file=book.json

Message	Cause
`Error: Unknown kind "x".`	A name in `--kinds` is not one of the four kinds.
`Error: "x" is not a kind:key item.`	An entry in `--items` has no colon or an unknown kind.
`Error: Could not write <path>.`	The folder does not exist or is not writable.
`Success: Exported to <path>.`	Done.

An item that does not exist is silently left out.

`wp wpmcf import`

wp wpmcf import <file> [--overwrite] [--dry-run]

Option	Meaning
`<file>`	Path of the JSON file (up to 5 MB).
`--overwrite`	Replace existing items with the same key. Without it they are kept.
`--dry-run`	Check everything and print what would happen; write nothing.

bash

wp wpmcf import definitions.json --dry-run
wp wpmcf import definitions.json
wp wpmcf import definitions.json --overwrite

The output is a table with kind, key, action (create, update, skip, error) and message, then one summary line:

| kind         | key              | action | message                                    |
| field_groups | book_details     | skip   | Already exists on this site and was kept.  |
Success: 0 created, 0 replaced, 1 kept, 0 failed.

With --dry-run the line reads Dry run: 1 to create, 0 to replace, 1 kept, 0 failing.

Exit status: a file-level problem (Cannot read <file>., The file is not valid JSON., a wrong format or a newer version) stops with an error and exit code 1. If only some items fail, the command prints a Warning with the summary and still exits with 0, so check the table or the summary line in scripts. The same rules and limits as the screen apply.

`wp wpmcf json`

Local JSON, see Local JSON and version control.

wp wpmcf json status
wp wpmcf json sync [<item>...] [--all]

Command	Meaning
`status`	Prints `Folder: <path> (<state>)` where state is `active`, `missing`, `not_writable` or `disabled`, warnings for unreadable files, and a table of pending files with `key`, `label`, `file`, `action`. When nothing waits: `Success: Everything is in sync.`
`sync <item>...`	Loads the named files. Items are `kind:key`, for example `field_groups:book_details`.
`sync --all`	Loads every pending file.

Without items and without --all, sync stops with Name the items to sync, or pass --all. The result is printed like an import report.

bash

wp wpmcf json status
wp wpmcf json sync --all
wp wpmcf json sync field_groups:book_details post_types:book

A deployment script usually ends with wp wpmcf json sync --all.

`wp wpmcf acf`

ACF migration, see Migrating from ACF. ACF data is never changed.

wp wpmcf acf report
wp wpmcf acf migrate [--dry-run] [--groups=<keys>]

Command or option	Meaning
`report`	Prints whether ACF is active (`ACF 6.x is active.` or `ACF is not active; reading its data from the database.`), a table of groups (`acf_key`, `title`, `key`, `fields`, `unsupported`, `objects`), one warning per field or location rule that is not copied, notes, and a table of post types, taxonomies and options pages with their action. Writes nothing.
`migrate`	Creates the definitions and copies all values in the foreground, batch after batch, without Action Scheduler. Prints each created or kept item, the problems, and `Success: Status: done. N object(s), M value(s) copied in B batch(es); P problem(s).`
`--dry-run`	Same as `report`.
`--groups=<keys>`	Only these ACF field groups (their ACF keys, such as `group_5f3a1b2c4d5e6`, comma-separated). Post types, taxonomies and options pages are always included.

bash

wp wpmcf acf report
wp wpmcf acf migrate --groups=group_5f3a1b2c4d5e6,group_5f3a1b2c4d7f8

The command refuses to start while another migration is running (A migration is already running.). When there is nothing to migrate, report prints No ACF data found. and migrate stops with No ACF data was found on this site. Problems with single values are warnings; the command still ends with Success and a problem count. The state the screen shows (progress, skipped values) is the same, so you can open the Tools screen afterwards to read the full list.

`wp wpmcf tasks`

Background tasks, see Background tasks.

wp wpmcf tasks list
wp wpmcf tasks run <id>

Command	Meaning
`list`	A table with `id`, `name`, `type`, `status`, `next_run` and `attempts` for every task.
`run <id>`	Runs the task in the foreground until its current run finishes, then prints `Success: Ran N batch(es). Status: <status>.`

run only works for tasks whose status is active: otherwise Task <id> is paused; activate it first. (or failed, completed). It stops with Task not found. for an unknown id. Tasks come from the Pro features (Programmatic SEO, data table imports and syncs, AI enrichment, conversion), so the list is empty on a free site without them.

`wp wpmcf code`

wp wpmcf code list
wp wpmcf code sync

Lists and syncs the field groups registered in PHP with wpmcf_register_field_group(). This is documented with the developer tools in Integrations.

Running the queue from the command line

Background work (the ACF migration when started from the screen, task batches, the sync of code groups) runs on Action Scheduler in the group wpmcf. On servers where WP-Cron is unreliable, run the queue from a system cron job:

bash

wp action-scheduler run --group=wpmcf

Troubleshooting

'wpmcf' is not a registered wp command. The plugin is not active on that site, or you are in the wrong folder or site (--path, --url).

The command is slow on a large site. acf migrate and tasks run do the work in one process. Raise PHP's memory_limit for the command: php -d memory_limit=1G $(which wp) wpmcf acf migrate.

import printed a warning and the script went on. Items that fail do not change the exit code. Check the summary line for failed or failing and stop your script on it.

Was this page helpful?

Still stuck? Contact support