WP-CLI commands

01Overview

Nucleo registers eight WP-CLI commands under the wp nucleo prefix. Nucleo registers the commands only in the WP-CLI context, that is when the WP_CLI constant is defined. The commands fall into three groups: MCP server, status and abilities; site as files; generated documentation. Each nucleo/* ability also has its own command, for example wp nucleo doc get: see Commands per ability. wp nucleo status, wp nucleo ability run and the commands per ability run the nucleo/* abilities with the same permission rules as MCP and REST. wp nucleo export, import and sync do not go through the nucleo/site-export and nucleo/site-import abilities.

User: WP-CLI starts without a user (ID 0). You choose the user with the WP-CLI global option --user=<id|login>. wp nucleo mcp refuses to run without a user. export, import and sync stop without a user with manage_options. The abilities run by status, ability run and the commands per ability check the capability, so without --user almost all of them fail. docs does not perform any capability check.

Errors and exit codes: WP_CLI::error() prints Error: <message> and exits with code 1. WP_CLI::warning() prints Warning: <message> and does not change the exit code. Uncaught exceptions (missing folder, file not writable) stop the command with a PHP fatal error.

02MCP server and status

wp nucleo mcp

What it does: starts the Nucleo MCP server on the STDIO transport. It reads one JSON-RPC 2.0 request per line from STDIN and writes one response per line to STDOUT. It ends at the end of the input (EOF).

How to use it: wp nucleo mcp --user=<id|login>. A local MCP client starts the command as a child process. The agents admin page shows the same command as an alternative to OAuth (wp nucleo mcp --user=<login>).

Parameters: no argument of its own. --user is the WP-CLI global option and it is required.

Permissions: requires a user. Without --user the command exits with Error: Indica l'utente con --user=<id|login>. (code 1). Each tool runs with the capabilities of the indicated user. On STDIO there is no OAuth token, so the scopes do not apply: tools/list shows all the registered nucleo/* abilities, and no call fails for a scope. The capability checks of each ability still apply.

Edition: Free. The Pro abilities appear among the tools only with an active license, because without a license they are not registered.

Known limits:

• Supported methods: initialize, ping, tools/list, tools/call. Any other method responds with JSON-RPC error -32601.
• JSON-RPC batches are not supported (error -32600). Invalid JSON: error -32700.
• Notifications (messages without id) get no response. Empty lines are ignored.
• Protocol version declared in initialize: 2025-06-18. capabilities.tools.listChanged is false.
• The tool name is the ability name with / replaced by - (nucleo/doc-get becomes nucleo-doc-get).
• The command hides database errors and discards the output written by other code with a buffer: only JSON-RPC goes to STDOUT.
• Write abilities have the same rate limit as MCP over HTTP: 60 writes per 60-second window per user and scope group (filter nucleo/rate_limit). Above the limit the ability responds rate_limited.
• Protocol and tool details: see the chapter MCP server, OAuth and common mechanisms.

wp nucleo status

What it does: runs the nucleo/status ability and prints the result. The result contains the version of Nucleo, PHP and WordPress, the store driver, the number of documents, the conflicts with caching plugins and the performance budgets.

How to use it: wp nucleo status --user=admin.

Parameters: none. The ability receives an empty input ([]).

Permissions: the ability requires manage_options. The command does not check the user: without --user of an administrator, the ability returns a WP_Error and the command exits with code 1. OAuth scope of the ability: nucleo:admin (not applied in CLI).

Edition: Free.

Known limits:

• Output: JSON with indentation (JSON_PRETTY_PRINT), Unicode and slashes not escaped. No --format option.
• If the ability is not registered, the command exits with Error: nucleo_status_missing: Ability nucleo/status is not registered.
• Ability error: Error: <code>: <message>, exit code 1.
• Equivalent ability: nucleo/status.

03Abilities

wp nucleo ability list

What it does: lists the registered abilities whose name starts with nucleo/, one per line, with the description.

How to use it: wp nucleo ability list.

Parameters: none.

Permissions: no check. The command does not filter by user capability or by scope.

Edition: Free. The Pro abilities appear only with an active license.

Known limits:

• Format of each line: <name> <description> (two spaces). No --format option.
• Order: that of the WordPress abilities registry. The command does not sort.

wp nucleo ability run

What it does: runs a nucleo/* ability with a JSON input and prints the result.

How to use it: wp nucleo ability run <name> [--input=<json>] --user=<id|login>. Example: wp nucleo ability run doc-get --input='{"postId":12}' --user=admin.

Parameters:

Permissions: the capability required by the ability. The command does not check the user: without --user, the abilities with a capability check fail. The OAuth scope does not apply, because there is no token in CLI.

Edition: Free. The Pro abilities exist only with an active license: without a license the command responds unknown_ability.

Known limits:

• Ability not registered: Error: unknown_ability: Unknown ability: nucleo/<name>. (code 1).
• --input that does not decode to an array: Error: invalid_json: --input must be a JSON object. (code 1). The check is is_array(), so a JSON array ([...]) also passes this check and reaches the schema validation.
• Input not valid for the schema, or permission denied: the ability returns a WP_Error and the command exits with Error: <code>: <message> (code 1).
• Many abilities report an error with an object {"ok": false, "error": {...}} instead of a WP_Error. In that case the command prints the JSON and exits with code 0. Your script must read the ok field.
• Output: JSON with indentation, as in wp nucleo status.
• Write abilities have the rate limit described in wp nucleo mcp. When the limit is hit, the response is {"ok": false, "error": {"code": "rate_limited", ...}} and the command exits with code 0: read the ok field.

04Commands per ability

wp nucleo <group> <action>

What it does: registers a command for each nucleo/* ability. The ability name loses the prefix, and the first hyphen becomes a space: nucleo/doc-get becomes wp nucleo doc get, nucleo/css-optimize-apply becomes wp nucleo css optimize-apply. The command runs the ability and prints the result as wp nucleo ability run does.

How to use it: wp nucleo doc get --input='{"postId":12}' --user=admin. The generic command wp nucleo ability run doc-get gives the same result.

Parameters:

Permissions: as for wp nucleo ability run: the capability required by the ability. The command does not check the user: --user is needed.

Edition: Free. The Pro abilities generate a command only with an active license.

Known limits:

• The reserved names remain existing commands: status, export, import, sync, docs, mcp and ability. The ability nucleo/status therefore has no command of its own: use wp nucleo status.
• An ability whose first group is reserved has no command: run it with wp nucleo ability run.
• wp nucleo quality scan without --all behaves like ability run. With --all it reads all the batches, keeps the site rules of the first batch, merges the pages and prints the merged result. An error on a batch: Error: <code>: <message>.
• Errors and exit codes: as in wp nucleo ability run.

05Site as files

The folder format, the resolution of symbolic references and the conflict rules are in the chapter Import, export and sync. This section describes only the commands.

wp nucleo export

What it does: writes the site to a folder of JSON files. Content: site.json (tokens, breakpoints, site settings, base fingerprints), pages/, posts/, layouts/, sections/, rules/assets.json, media/manifest.json and one file per menu in menus/<slug>.json.

How to use it: wp nucleo export <dir>. Example: wp nucleo export ./nucleo-site.

Parameters:

Permissions: manage_options. Without a user with that capability the command stops with Error: This command needs a user with manage_options. Pass --user=<admin>. (code 1). It exports the Nucleo posts of all statuses (post_status any).

Edition: Free. With the Pro package each document also carries wp.lang and wp.translations.

Known limits:

• Without <dir>: Error: Specify the site folder. (code 1).
• Successful result: Success: Site exported to <dir>.
• The command overwrites the files with the same path and does not delete the files already in the folder. A document deleted on the site stays in the folder.
• Menu items that are not exported (target not published or deleted) do not appear in the command output. The ability nucleo/site-export returns them in skipped.
• It does not export content/ or terms/.
• A file that is not writable stops the command with an uncaught error (Cannot write file: <path>).
• Equivalent ability: nucleo/site-export, which returns the files instead of writing them to disk.

wp nucleo import

What it does: reads the .json files of a folder, subfolders included, and creates or updates tokens, settings, menus, sections, pages, posts, layouts, asset rules and media. It finds the existing documents by slug and post type.

How to use it: wp nucleo import <dir> [--dry-run] [--force].

Parameters:

Permissions: manage_options, as for wp nucleo export. Without a user with that capability the command stops with the same error (code 1).

Edition: Free. With the Pro package the import also sets the language of the posts and links the translations.

Known limits:

• Without <dir>: Error: Specify the site folder. (code 1).
• Folder that does not exist: uncaught exception (Directory does not exist: <dir>).
• Output: one line Creati: <n>, aggiornati: <n>, invariati: <n>. and one Warning: <file>: <message> for each error. With --dry-run the line is the same: the numbers show what would change.
• An error on one file does not stop the others. The command exits with code 0 even with errors.
• Internal error codes of the report: error, conflict, duplicate, not_json, invalid_document, quality_blocking. The command prints only the message, not the code.
• The command does not print the report warnings (warnings).
• The command does not pass acknowledgements (acknowledge): a document with blocking quality problems is not imported (quality_blocking).
• --force does not accept a list of files. The ability accepts force as a list of paths.
• The command does not update base, tokensBase and siteBase in site.json after the import. The local nucleo push CLI does rewrite them.
• The folders content/ and terms/ are ignored: the import reads only site.json, media/manifest.json, menus/, sections/, pages/, posts/, layouts/ and rules/assets.json.
• Equivalent ability: nucleo/site-import, which also accepts force for each file, acknowledge and pending.

wp nucleo sync

What it does: imports the folder as wp nucleo import does with no options. With --prune it moves to the trash the Nucleo documents of the site that have no matching file in the folder.

How to use it: wp nucleo sync <dir> [--prune].

Parameters:

Permissions: manage_options, as for wp nucleo import.

Edition: Free.

Known limits:

• Output: the line of wp nucleo import, the warnings for the errors and, with --prune, Cestinati: <n>.
• The command does not accept --dry-run or --force: the import always saves and runs without forcing.
• --prune also acts if the import had errors. The comparison uses the slug: a post renamed on the site appears missing from the folder.
• --prune moves to the trash, it does not delete permanently. It does not touch menus, tokens, media or rules.
• No equivalent ability for --prune. For the import see the ability nucleo/site-import.

06Generated documentation

wp nucleo docs

What it does: generates three files in a folder from the code: blocchi.md (each block with fields, allowed values, defaults and supports), abilities.md (each nucleo/* ability with description, OAuth scope, read-only flag and input schema) and llms.txt (MCP URL, STDIO command and usage rules).

How to use it: wp nucleo docs [<dir>]. Example: wp nucleo docs ./nucleo-docs.

Parameters:

Permissions: no capability check.

Edition: Free. abilities.md lists the Pro abilities only with an active license.

Known limits:

• Successful result: Success: Documentazione scritta in <dir>.
• Folder that cannot be created or file that is not writable: uncaught exception (Directory cannot be created: <dir>, Write failed: <file>).
• The generated texts are in English.
• An ability with no scope mapped appears with scope none.
• llms.txt contains the URL home_url('/wp-json/nucleo/v1/mcp') of the site where the command runs.
• The files overwrite the existing ones with the same name.
• No equivalent ability. The arguments of nucleo/catalog-get are not part of this command.