Comandi WP-CLI

01Panoramica

Nucleo registra otto comandi WP-CLI sotto il prefisso wp nucleo. Nucleo registra i comandi solo nel contesto WP-CLI, cioè quando la costante WP_CLI è definita. I comandi si dividono in tre gruppi: server MCP, stato e ability; sito come file; documentazione generata. Ogni ability nucleo/* ha in più un comando proprio, per esempio wp nucleo doc get: vedi Comandi per ability. wp nucleo status, wp nucleo ability run e i comandi per ability eseguono le ability nucleo/* con le stesse regole di permesso di MCP e REST. wp nucleo export, import e sync non passano dalle ability nucleo/site-export e nucleo/site-import.

Utente: WP-CLI parte senza utente (ID 0). L'utente si sceglie con l'opzione globale di WP-CLI --user=<id|login>. Solo wp nucleo mcp rifiuta l'esecuzione senza utente. export, import e sync si fermano senza un utente con manage_options. Gli altri comandi non controllano l'utente. Le ability eseguite da status, ability run e dai comandi per ability però controllano la capability, quindi senza --user falliscono quasi tutte. docs non fa nessun controllo di capability.

Errori e codici di uscita: WP_CLI::error() stampa Error: <messaggio> ed esce con codice 1. WP_CLI::warning() stampa Warning: <messaggio> e non cambia il codice di uscita. Le eccezioni non catturate (cartella mancante, file non scrivibile) interrompono il comando con un errore fatale di PHP.

02Server MCP e stato

wp nucleo mcp

Cosa fa: avvia il server MCP di Nucleo sul trasporto STDIO. Legge una richiesta JSON-RPC 2.0 per riga da STDIN e scrive una risposta per riga su STDOUT. Termina alla fine dell'input (EOF).

Come si usa: wp nucleo mcp --user=<id|login>. Un client MCP locale avvia il comando come processo figlio. La pagina admin degli agenti mostra lo stesso comando come alternativa a OAuth (wp nucleo mcp --user=<login>).

Parametri: nessun argomento proprio. --user è l'opzione globale di WP-CLI ed è obbligatoria.

Permessi: richiede un utente. Senza --user il comando esce con Error: Indica l'utente con --user=<id|login>. (codice 1). Ogni tool gira con le capability dell'utente indicato. Su STDIO non c'è un token OAuth, quindi non si applicano gli ambiti: tools/list mostra tutte le ability nucleo/* registrate e nessuna chiamata fallisce per ambito. Restano i controlli di capability di ogni ability.

Edizione: Free. Le ability Pro compaiono tra i tool solo con licenza attiva, perché senza licenza non si registrano.

Limiti noti:

• Metodi supportati: initialize, ping, tools/list, tools/call. Un altro metodo risponde con errore JSON-RPC -32601.
• Batch JSON-RPC non supportato (errore -32600). JSON non valido: errore -32700.
• Le notifiche (messaggi senza id) non ricevono risposta. Le righe vuote si ignorano.
• Versione di protocollo dichiarata in initialize: 2025-06-18. capabilities.tools.listChanged vale false.
• Il nome del tool è il nome dell'ability con / sostituito da - (nucleo/doc-get diventa nucleo-doc-get).
• Il comando nasconde gli errori del database e scarta l'output scritto da altro codice con un buffer: su STDOUT passa solo JSON-RPC.
• Le ability di scrittura hanno lo stesso limite di frequenza di MCP HTTP: 60 scritture per finestra di 60 secondi per utente e gruppo di scope (filtro nucleo/rate_limit). Oltre il limite l'ability risponde rate_limited.
• Dettagli del protocollo e dei tool: vedi il capitolo Server MCP, OAuth e meccanismi comuni.

wp nucleo status

Cosa fa: esegue l'ability nucleo/status e stampa il risultato. Il risultato contiene versione di Nucleo, PHP e WordPress, driver dello store, numero di documenti, conflitti con plugin di cache e budget di performance.

Come si usa: wp nucleo status --user=admin.

Parametri: nessuno. L'ability riceve un input vuoto ([]).

Permessi: l'ability richiede manage_options. Il comando non verifica l'utente: senza --user di un amministratore l'ability restituisce un WP_Error e il comando esce con codice 1. Scope OAuth dell'ability: nucleo:admin (non applicato in CLI).

Edizione: Free.

Limiti noti:

• Output: JSON con indentazione (JSON_PRETTY_PRINT), Unicode e barre non escapati. Nessuna opzione --format.
• Se l'ability non è registrata, il comando esce con Error: nucleo_status_missing: Ability nucleo/status is not registered.
• Errore dell'ability: Error: <codice>: <messaggio>, codice di uscita 1.
• Ability equivalente: nucleo/status.

03Ability

wp nucleo ability list

Cosa fa: elenca le ability registrate il cui nome inizia con nucleo/, una per riga, con la descrizione.

Come si usa: wp nucleo ability list.

Parametri: nessuno.

Permessi: nessun controllo. Il comando non filtra per capability dell'utente né per ambito.

Edizione: Free. Le ability Pro compaiono solo con licenza attiva.

Limiti noti:

• Formato di ogni riga: <nome> <descrizione> (due spazi). Nessuna opzione --format.
• Ordine: quello del registro delle ability di WordPress. Il comando non ordina.

wp nucleo ability run

Cosa fa: esegue un'ability nucleo/* con un input JSON e stampa il risultato.

Come si usa: wp nucleo ability run <nome> [--input=<json>] --user=<id|login>. Esempio: wp nucleo ability run doc-get --input='{"postId":12}' --user=admin.

Parametri:

Permessi: la capability richiesta dall'ability. Il comando non verifica l'utente: senza --user le ability con un controllo di capability falliscono. Lo scope OAuth non si applica, perché in CLI non c'è un token.

Edizione: Free. Le ability Pro esistono solo con licenza attiva: senza licenza il comando risponde unknown_ability.

Limiti noti:

• Ability non registrata: Error: unknown_ability: Unknown ability: nucleo/<nome>. (codice 1).
• --input che non decodifica in un array: Error: invalid_json: --input must be a JSON object. (codice 1). Il controllo è is_array(), quindi anche un array JSON ([...]) passa questo controllo e arriva alla validazione dello schema.
• Input non valido per lo schema o permesso negato: l'ability restituisce un WP_Error e il comando esce con Error: <codice>: <messaggio> (codice 1).
• Molte ability segnalano un errore con un oggetto {"ok": false, "error": {...}} invece di un WP_Error. In quel caso il comando stampa il JSON ed esce con codice 0. Uno script deve leggere il campo ok.
• Output: JSON con indentazione, come wp nucleo status.
• Le ability di scrittura hanno il limite di frequenza descritto in wp nucleo mcp. Al superamento la risposta è {"ok": false, "error": {"code": "rate_limited", ...}} e il comando esce con codice 0: va letto il campo ok.

04Comandi per ability

wp nucleo <gruppo> <azione>

Cosa fa: registra un comando per ogni ability nucleo/*. Il nome dell'ability perde il prefisso, e il primo trattino diventa uno spazio: nucleo/doc-get diventa wp nucleo doc get, nucleo/css-optimize-apply diventa wp nucleo css optimize-apply. Il comando esegue l'ability e stampa il risultato come wp nucleo ability run.

Come si usa: wp nucleo doc get --input='{"postId":12}' --user=admin. Il comando generico wp nucleo ability run doc-get dà lo stesso risultato.

Parametri:

Permessi: come wp nucleo ability run: la capability richiesta dall'ability. Il comando non verifica l'utente: serve --user.

Edizione: Free. Le ability Pro generano un comando solo con licenza attiva.

Limiti noti:

• I nomi occupati restano dei comandi esistenti: status, export, import, sync, docs, mcp e ability. L'ability nucleo/status quindi non ha un comando proprio: si usa wp nucleo status.
• Un'ability il cui primo gruppo è occupato non ha un comando: si esegue con wp nucleo ability run.
• wp nucleo quality scan senza --all si comporta come ability run. Con --all legge tutti i lotti, tiene le regole di sito del primo lotto, unisce le pagine e stampa il risultato unito. Un errore su un lotto: Error: <codice>: <messaggio>.
• Errori e codici di uscita: come in wp nucleo ability run.

05Sito come file

Il formato della cartella, la risoluzione dei riferimenti simbolici e le regole di conflitto sono nel capitolo Import, export e sincronizzazione. Questa sezione descrive solo i comandi.

wp nucleo export

Cosa fa: scrive il sito in una cartella di file JSON. Contenuto: site.json (token, breakpoint, impostazioni del sito, impronte di base), pages/, posts/, layouts/, sections/, rules/assets.json, media/manifest.json e un file per menu in menus/<slug>.json.

Come si usa: wp nucleo export <dir>. Esempio: wp nucleo export ./nucleo-site.

Parametri:

Permessi: manage_options. Senza un utente con questa capability il comando si ferma con Error: This command needs a user with manage_options. Pass --user=<admin>. (codice 1). Esporta i post Nucleo di tutti gli stati (post_status any).

Edizione: Free. Con il pacchetto Pro ogni documento porta anche wp.lang e wp.translations.

Limiti noti:

• Senza <dir>: Error: Specify the site folder. (codice 1).
• Esito positivo: Success: Site exported to <dir>.
• Il comando sovrascrive i file con lo stesso percorso e non cancella i file già presenti nella cartella. Un documento eliminato sul sito resta nella cartella.
• Le voci di menu non esportate (bersaglio non pubblicato o cancellato) non compaiono nell'output del comando. L'ability nucleo/site-export le restituisce in skipped.
• Non esporta content/ né terms/.
• Un file non scrivibile interrompe il comando con un errore non catturato (Cannot write file: <percorso>).
• Ability equivalente: nucleo/site-export, che restituisce i file invece di scriverli su disco.

wp nucleo import

Cosa fa: legge i file .json di una cartella, sottocartelle comprese, e crea o aggiorna token, impostazioni, menu, sezioni, pagine, post, layout, regole degli asset e media. Trova i documenti esistenti per slug e tipo di post.

Come si usa: wp nucleo import <dir> [--dry-run] [--force].

Parametri:

Permessi: manage_options, come per wp nucleo export. Senza un utente con questa capability il comando si ferma con lo stesso errore (codice 1).

Edizione: Free. Con il pacchetto Pro l'import imposta anche la lingua dei post e collega le traduzioni.

Limiti noti:

• Senza <dir>: Error: Specify the site folder. (codice 1).
• Cartella inesistente: eccezione non catturata (Directory does not exist: <dir>).
• Output: una riga Creati: <n>, aggiornati: <n>, invariati: <n>. e un Warning: <file>: <messaggio> per ogni errore. Con --dry-run la riga è la stessa: i numeri indicano cosa cambierebbe.
• Un errore su un file non ferma gli altri. Il comando esce con codice 0 anche con errori.
• Codici d'errore interni del report: error, conflict, duplicate, not_json, invalid_document, quality_blocking. Il comando stampa solo il messaggio, non il codice.
• Il comando non stampa gli avvisi (warnings) del report.
• Il comando non passa consensi (acknowledge): un documento con problemi di qualità bloccanti non si importa (quality_blocking).
• --force non accetta un elenco di file. L'ability accetta force come lista di percorsi.
• Il comando non aggiorna base, tokensBase e siteBase in site.json dopo l'import. La CLI locale nucleo push invece li riscrive.
• Le cartelle content/ e terms/ si ignorano: l'import legge solo site.json, media/manifest.json, menus/, sections/, pages/, posts/, layouts/ e rules/assets.json.
• Ability equivalente: nucleo/site-import, che accetta in più force per file, acknowledge e pending.

wp nucleo sync

Cosa fa: importa la cartella come wp nucleo import senza opzioni. Con --prune sposta nel cestino i documenti Nucleo del sito che non hanno un file corrispondente nella cartella.

Come si usa: wp nucleo sync <dir> [--prune].

Parametri:

Permessi: manage_options, come per wp nucleo import.

Edizione: Free.

Limiti noti:

• Output: la riga di wp nucleo import, gli avvisi per gli errori e, con --prune, Cestinati: <n>.
• Il comando non accetta --dry-run né --force: l'import gira sempre con salvataggio e senza forzatura.
• --prune agisce anche se l'import ha avuto errori. Il confronto usa lo slug: un post rinominato sul sito risulta assente dalla cartella.
• --prune sposta nel cestino, non elimina in modo definitivo. Non tocca menu, token, media né regole.
• Nessuna ability equivalente per --prune. Per l'import vedi l'ability nucleo/site-import.

06Documentazione generata

wp nucleo docs

Cosa fa: genera tre file in una cartella a partire dal codice: blocchi.md (ogni blocco con campi, valori ammessi, default e supporti), abilities.md (ogni ability nucleo/* con descrizione, scope OAuth, sola lettura e schema di input) e llms.txt (URL MCP, comando STDIO e regole d'uso).

Come si usa: wp nucleo docs [<dir>]. Esempio: wp nucleo docs ./nucleo-docs.

Parametri:

Permessi: nessun controllo di capability.

Edizione: Free. abilities.md elenca le ability Pro solo con licenza attiva.

Limiti noti:

• Esito positivo: Success: Documentazione scritta in <dir>.
• Cartella non creabile o file non scrivibile: eccezione non catturata (Directory cannot be created: <dir>, Write failed: <file>).
• I testi generati sono in inglese.
• Un'ability senza scope mappato compare con scope none.
• llms.txt contiene l'URL home_url('/wp-json/nucleo/v1/mcp') del sito su cui gira il comando.
• I file sovrascrivono quelli esistenti con lo stesso nome.
• Nessuna ability equivalente. Gli argomenti di nucleo/catalog-get non fanno parte di questo comando.