Utiliser WP CLI pour gérer votre site WordPress

Si vous êtes développeur ou que vous utilisez WordPress depuis un certain temps, vous avez forcément entendu parler de WP CLI. Tout comme Git, c’est un outil quasi-incontournable pour vous aider à gérer vos sites WordPress ou accélerer vos développements.

Dans cette petite série d’articles, on va voir ce qu’est WP CLI exactement, explorer ses commandes les plus courantes et voir comment vous pouvez l’utiliser dans votre travail quotidien.

Qu’est-ce que WP CLI ?

WP CLI est l’outil de ligne de commande de WordPress (CLI pour Command Line Interface). Un CLI est simplement un outil qui s’utilise dans un terminal et qui donne accès à certaines commandes pour vous faciliter le travail.

WP CLI est donc un package que vous installez sur votre serveur et qui vous donnera accès à différentes commandes dans votre terminal pour interagir avec votre installation de WordPress.

Par exemple, avec une simple commande vous pourrez mettre à jour vos extensions, créer un utilisateur, importer un média ou même (et c’est le plus utile pour un développeur) générer des fichiers.

Potentiellement, une grande partie de ce que vous pouvez faire dans votre administration de WordPress pourra être faite dans votre terminal. Je dis bien “potentiellement”, car comme on va le voir, certaines actions restent plus confortables à effectuer dans l’interface d’administration de WordPress.

Installation

Pour installer WP CLI sur votre machine, le plus simple est de télécharger le wp-cli.phar et de l’installer manuellement dans les fichiers de votre système.

La procédure est détaillée dans la documentation officielle, mais en voici un résumé :

Ouvrez un terminal puis téléchargez le fichier wp-cli.phar avec curl.

curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar

Rendez ce fichier exécutable.

chmod +x wp-cli.phar

Déplacez ce fichier dans un des répertoires de votre PATH, en le renommant wp. Cela rendra WP CLI accessible globalement via la commande wp, au lieu d’avoir besoin de vous placer où votre fichier wp-cli.phar est pour l’appeler.
Les commandes accessibles dans votre terminal sont en fait de petits scripts que vous exécutez. Selon votre OS vous pourrez ranger ces scripts dans différents dossiers. Ces dossiers sont listés dans la variable d’environnement appelée PATH. Sur mon système, je peux placer des commandes dans /usr/local/bin/wp. Vérifiez où ranger votre script selon votre OS.

sudo mv wp-cli.phar /usr/local/bin/wp

Si tout va bien, la commande wp devrait être accessible. Vérifiez cela avec la commande suivante.

wp --info

La sortie de la commande `wp --info` affiche des informations de version et sur l'environnement — La sortie de la commande `wp --info` affiche des informations de version et sur l’environnement

vincent@Swift:~$ wp --info
OS:    Linux 6.8.0-51-generic #52-Ubuntu SMP PREEMPT_DYNAMIC Thu Dec  5 13:09:44 UTC 2024 x86_64
Shell:    /bin/bash
PHP binary:    /usr/bin/php8.3
PHP version:    8.3.6
php.ini used:    /etc/php/8.3/cli/php.ini
MySQL binary:    /usr/bin/mysql
MySQL version:    mysql  Ver 8.0.40-0ubuntu0.24.04.1 for Linux on x86_64 ((Ubuntu))
SQL modes:    
WP-CLI root dir:    phar://wp-cli.phar/vendor/wp-cli/wp-cli
WP-CLI vendor dir:    phar://wp-cli.phar/vendor
WP_CLI phar path:    /home/vincent
WP-CLI packages dir:    /home/vincent/.wp-cli/packages/
WP-CLI cache dir:    /home/vincent/.wp-cli/cache
WP-CLI global config:    
WP-CLI project config:    
WP-CLI version:    2.11.0

Si vous avez un message d’erreur indiquant une commande introuvable, essayez de fermer votre terminal et d’en ouvrir un nouveau.

Local by Flywheel

Si vous utilisez un outil de gestion de sites locaux comme Local by Flywheel ou DevKinsta, alors WP CLI est déjà installé et disponible pour vos sites locaux.

Cliquez simplement sur Site Shell pour ouvrir un terminal, et vous serez placé directement dans le dossier contenant votre installation de WordPress.

Local By Flywheel propose un bouton pour ouvrir un terminal local à votre site

Sur la capture suivante, vous pourrez voir que la version de WP CLI proposée par Local est la 2.10, alors que la version installée sur ma machine globalement est la 2.11. Aussi, sur le site Local, la version de PHP utilisée est différente de celle utilisée globalement.

Pour éviter les soucis de compatibilité, si vous utilisez Local by Flywheel, je vous conseille de toujours passer par le bouton Site Shell pour ouvrir une session dans le bon environnement et dans le bon dossier.

La session du terminal lancée par Local vous place directement au bon endroit, dans le bon environnement

Connexion à distance

Si vous voulez expérimenter sur un site en production, vous pouvez vous connecter à votre site WordPress via SSH. Pour cela, il faut que WP CLI soit installé et disponible sous wp sur votre serveur et activer un accès SSH vers votre serveur. Vous pouvez ensuite ouvrir un terminal local et passer vos identifiants de connexion pour vous connecter à distance.

wp --ssh=[<scheme>:][<user>@]<host>[:<port>][<path>]

C’est un aspect plus technique que nous ne traiterons pas dans cet article.

Par contre, il y a de grandes chances que WP CLI soit déjà installé sur votre hébergement et votre hébergeur vous permet surement d’ouvrir un terminal sur votre hébergement. Vous pouvez donc probablement accéder à votre cPanel (ou autre outil) et ouvrir un terminal directement en production pour manipuler votre site live.

Toujours est-il que si vous souhaitez explorer WP CLI pour tester, je recommande de le faire sur un site local.

Premières commandes

Maintenant que WP CLI est installé, on peut commencer à explorer ses possibilités.

Assurez-vous de vous placer dans votre installation de WordPress. Si vous êtes passé par le bouton Site Shell de Local, vous êtes déjà au bon endroit.

On a déjà vu wp --info qui donne des informations sur l’environnement.

Vous pouvez obtenir uniquement le numéro de version de WP CLI avec wp cli version

$ wp cli version
WP-CLI 2.10.0

Vous pouvez vérifier si des mises à jours sont disponibles avec wp cli check-update

`wp cli check-update` affiche les nouvelles versions disponibles

Vu que sur mon site actuel, Local utilise la version 2.10 de WP CLI, on a effectivement une mise à jour disponible.

Pour mettre à jour, on utilise simplement wp cli update.

Obtenir de l’aide

Pour obtenir la liste des commandes disponibles, on peut utilise wp sans argument, ou alors wp help.

$ wp help

NAME

  wp

DESCRIPTION

  Manage WordPress through the command-line.

SYNOPSIS

  wp <command>

SUBCOMMANDS

  action-scheduler       Commands for Action Scheduler.
  cache                  Adds, removes, fetches, and flushes the WP Object Cache object.
  cap                    Adds, removes, and lists capabilities of a user role.
  cli                    Reviews current WP-CLI info, checks for updates, or views defined aliases.
  comment                Creates, updates, deletes, and moderates comments.
  config                 Generates and reads the wp-config.php file.
  core                   Downloads, installs, updates, and manages a WordPress installation.
  cron                   Tests, runs, and deletes WP-Cron events; manages WP-Cron schedules.
  db                     Performs basic database operations using credentials stored in wp-config.php.
  dist-archive           Create a distribution archive based on a project's .distignore file.
  embed                  Inspects oEmbed providers, clears embed cache, and more.
...

La liste des commandes et paramètres est un peu longue donc je vous laisse expérimenter et lire la liste dans votre terminal.

Vous pouvez voir que l’on a beaucoup de commandes à disposition, et qu’on peut donc faire énormément de choses via ce CLI !

Comprendre les commandes WP CLI

WP CLI est organisé en commandes et sous-commandes.

Les commandes listées par wp help font référence aux domaines/aspects de WordPress sur lesquels vous voulez intervenir, mais les actions sur ces domaines sont gérés par les sous-commandes.

Par exemple, wp cli ne fait rien seul. Si vous entrez wp help cli dans le terminal, vous aurez la liste des sous-commandes que vous pouvez utiliser pour interagir avec votre installation de WP CLI, mais aucune action n’est effectuée.

`wp help cli` affiche la liste des sous-commandes disponibles pour `wp cli`

Dans notre exemple précédent, wp cli update, la commande est cli, et la sous-commande est update. Vous pouvez voir dans la liste ci-dessus qu’on a bien une sous-commande update listée.

Vous pouvez vous représenter cela de cette façon : wp <domaine> <action> <param> [<param_optionnel>] [–flagOptionel] [–param=valeur]

Pour obtenir de l’aide vous pouvez utiliser :

$ wp help                          ## liste toutes les commandes et paramètres de wp
$ wp help <command>                ## liste toutes les sous-commandes de <command> et ses paramètres
$ wp help <command> <subcommand>   ## liste une description et les paramètres de <subcommand>

Vous pouvez aussi simplement aller sur la documentation, qui est très bien écrite et qui résume toutes ces informations sur une page web, plus agréable à lire qu’une entrée dans un terminal.

Anatomie d’une commande

Lire une description de commande n’est pas très compliqué. Prenons l’exemple de wp cli check-update.

$ wp cli
usage: wp cli alias <command>
    ...
    or: wp cli check-update [--patch] [--minor] [--major] [--field=<field>] [--fields=<fields>] [--format=<format>]
    ...

Les paramètres positionnels obligatoires (dont la position est importante) sont marqués par <> et se situent en général juste après la sous-commande. Ici wp cli check-update ne prend pas de paramètre positionel obligatoire, mais wp cli alias en prend un : il demande une commande <command>.

Les flags (paramètres booléens) sont marqués par --. Dans notre cas, inclure --patch dans notre commande indique de ne lister que les patches disponibles, par exemple.

Les paramètres optionnels sont marqués par []. Ici, les flags --patch, --minor, --major sont optionnels, ainsi que les paramètres --field, --fields et --format.

Les paramètres nommés (ou associatifs) sont marqués aussi par --, mais demandent de spécifier une valeur. Ici --field, --fields et --format demandent une valeur spécifique pour fonctionner. Par exemple, vous pouvez uniquement afficher uniquement la version de la mise à jour disponible en passant --field=version. Les valeurs acceptées sont disponibles dans la documentation.

Pour résumer, on décompose une commande comme ceci :

wp <commande> <sous-commande> <parametreObligatoire1> <parametreObligatoire2> --parametreObligatoire3=valeur3 [--flagOptionnel1] [--flagOptionnel2] [--parametreOptionnel1=valeur1] [--parametreOptionnel2=valeur2]

Utiliser WP CLI pour gérer son site

WP CLI est un outil puissant qui va vous permettre de gérer de nombreux aspects de votre site WordPress. Vous pouvez gérer vos mises à jour, vos extensions, vos thèmes, vos utilisateurs, votre cache, etc…

Dans cet article, on va se concentrer sur les aspects de webmastering simples dont vous allez avoir besoin souvent. Dans les articles suivants, on va monter en puissance et attaquer des sujets plus pointus.

Mettre à jour le coeur de WordPress

wp core est la commande permettant de gérer le coeur de WordPress.

$ wp core

usage: wp core check-update [--minor] [--major] [--force-check] [--field=<field>] [--fields=<fields>] [--format=<format>]
   or: wp core download [<download-url>] [--path=<path>] [--locale=<locale>] [--version=<version>] [--skip-content] [--force] [--insecure] [--extract]
   or: wp core install --url=<url> --title=<site-title> --admin_user=<username> [--admin_password=<password>] --admin_email=<email> [--locale=<locale>] [--skip-email]
   or: wp core is-installed [--network]
   or: wp core multisite-convert [--title=<network-title>] [--base=<url-path>] [--subdomains] [--skip-config]
   or: wp core multisite-install [--url=<url>] [--base=<url-path>] [--subdomains] --title=<site-title> --admin_user=<username> [--admin_password=<password>] --admin_email=<email> [--skip-email] [--skip-config]
   or: wp core update [<zip>] [--minor] [--version=<version>] [--force] [--locale=<locale>] [--insecure]
   or: wp core update-db [--network] [--dry-run]
   or: wp core verify-checksums [--include-root] [--version=<version>] [--locale=<locale>] [--insecure]
   or: wp core version [--extra]

See 'wp help core <command>' for more information on a specific command.

Attention, cet affichage n’est pas le contenu de l’aide. C’est un message indiquant que mon utilisation de wp core est incorrecte et me suggérant les commandes possibles. Pour une aide mieux formattée et plus complète, utilisez wp help core.

Avec wp core, on peut télécharger et installer WordPress complètement, installer une version spécifique, mettre à jour l’installation, mettre à jour la base de donnée et même passer une installation simple en multisite.

Parmi les commandes les plus utiles, on a wp core check-update qui va vous indiquer si une mise à jour est disponible. La sortie est similaire à celle donnée par wp cli check-update. Vous pouvez aussi voir la version de WordPress installée en utilisant wp core version.

`wp core check-update` affiche les nouvelles versions disponibles

J’ai deux mises à jour disponibles pour ma version installée. Je vais donc mettre à jour à la dernière version avec wp core update et mettre à jour ma base de données avec wp core update-db.

$ wp core update
Updating to version 6.7.1 (en_US)...
Downloading update from https://downloads.wordpress.org/release/wordpress-6.7.1-new-bundled.zip...
Unpacking the update...
<p>Some of your translations need updating. Sit tight for a few more seconds while they are updated as well.</p>
...
No files found that need cleaning up.
Success: WordPress updated successfully.

$ wp core update-db
Success: WordPress database upgraded successfully from db version 57155 to 58975.

Vous pouvez voir que par défaut, la commande a téléchargé la version en_US de WordPress et a mis à jour mes traductions. Vous pouvez aussi passer une locale lors de la mise à jour, comme ceci :

$ wp core update --locale=fr_FR

Installer une version spécifique de WordPress

Si vous avez besoin de revenir à une version antérieure de WordPress, vous pouvez utiliser wp core download, qui va télécharger WordPress et l’installer dans le dossier dans lequel vous vous situez ou dans un dossier spécifié par le paramètre --path.

$ wp core download https://wordpress.org/wordpress-6.6.zip
Error: WordPress files seem to already be present here.

Dans le dossier où je me trouve, il y a déjà une installation, donc la commande refuse de télécharger et écraser mes fichiers existants. Vous pouvez le forcer avec le flag --force.

$ wp core download https://wordpress.org/wordpress-6.6.zip --force
Downloading from https://wordpress.org/wordpress-6.6.zip ...
md5 hash verified: c3c6632072a7460e64443f2733b6f69e
Warning: Failed to find WordPress version. Please cleanup files manually.
Success: WordPress downloaded.

$ wp core version
6.6

$ wp core update-db
Success: WordPress database upgraded successfully from db version 58975 to 57155.

Je suis passé à la version 6.6, et j’ai mis à jour ma base de données. Maintenant, wp core check-update va m’indiquer de nouveau les mêmes mises à jour que dans l’exemple précédent.

Installer WordPress

Pour installer WordPress, il y a trois étapes distinctes :

Télécharger les fichiers de WordPress et les placer dans le bon dossier à l’aide de wp core download, comme on a vu précédemment.
Créer un fichier de configuration avec les informations de la base de données avec wp config create. Cela sous-entends que votre base de données et votre utilisateur soient mis en place.
Effectuer la fameuse “installation en 5 minutes” qui mets en place les tables de la base de données en utilisant wp core install.

D’abord, je télécharge et place WordPress dans le dossier souhaité. Ce sera wp/ pour cet exemple. Puis je navigue dans ce dossier pour éviter de devoir passer un paramètre --path à toutes mes futures commandes.

$ wp core download --path=wp
Success: WordPress downloaded.

$ cd wp

Dans ce dossier, j’ai tous les fichiers d’une installation classique de WordPress, sauf le wp-config.php.

Ensuite, je crée le fichier de configuration wp-config.php en passant les informations de ma base de données. J’ai au préalable créé la base de données et l’utilisateur dans mon outil de gestion de bases de données (PHPMyAdmin par exemple, ou Adminer dans mon cas, car je travaille avec Local by Flywheel). Remplacez les informations de la base de données avec les vôtres, évidemment.

$ wp config create --dbhost=localhost --dbname=example --dbuser=myuser --dbpass=strongpassword
Success: Generated 'wp-config.php' file.

Maintenant que mes fichiers sont en place, que ma base de données est créée et que mon fichier de configuration existe et contient les bonnes références à ma base de données, je peux installer WordPress avec wp core install.

Passez les informations de l’administrateur via les paramètres --admin-user, --admin-email et --admin-password, et les informations sur votre site avec --url et --title.

Attention, si vos fichiers sont dans un sous-dossier (c’est-à-dire pas à la racine où pointe votre domaine), alors il faudra mettre à jour l’option site_url avec wp option update siteurl https://example.local/mondossier. Bizarrement, on peut passer --url à la commande pour mettre à jour l’option home_url, mais pas --site-url pour l’option site_url.

$ wp core install --url=example.local --title=Example --admin_user=example --admin_password=password --admin_email=contact@example.com
Success: WordPress installed successfully.

WordPress est prêt à être utilisé !

Gérer vos extensions

Tout comme vous pouvez gérer le coeur de WordPress, vous pouvez gérer vos extensions à l’aide de WP CLI. Les sous-commandes pour ce faire sont sous la commande wp plugin.

$ wp help plugin

NAME

  wp plugin

DESCRIPTION

  Manages plugins, including installs, activations, and updates.

SYNOPSIS

  wp plugin <command>

SUBCOMMANDS

  activate              Activates one or more plugins.
  auto-updates          Manages plugin auto-updates.
  deactivate            Deactivates one or more plugins.
  delete                Deletes plugin files without deactivating or uninstalling.
  get                   Gets details about an installed plugin.
  install               Installs one or more plugins.
  is-active             Checks if a given plugin is active.
  is-installed          Checks if a given plugin is installed.
  list                  Gets a list of plugins.
  path                  Gets the path to a plugin or to the plugin directory.
  search                Searches the WordPress.org plugin directory.
  status                Reveals the status of one or all plugins.
  toggle                Toggles a plugin's activation state.
  uninstall             Uninstalls one or more plugins.
  update                Updates one or more plugins.
  verify-checksums      Verifies plugin files against WordPress.org's checksums.
...

Vous pouvez lister, installer, activer, désactiver, et mettre à jour toutes vos extensions.

Vous pouvez voir toutes vos extensions installées avec wp plugin list.

`wp plugin list` permet de lister les extensions installées

Sur mon installation, j’ai une mise à jour disponible pour Akismet. Je vais donc le mettre à jour avec wp plugin update.

$ wp plugin update akismet

`wp plugin update` permet de mettre à jour les extensions.

Pour tout mettre à jour, on peut aussi utiliser wp plugin update --all, tout simplement.

J’ai aussi l’extension Hello Dolly installée. On va la supprimer avec wp plugin delete.

$ wp plugin delete hello
Deleted 'hello' plugin.
Success: Deleted 1 of 1 plugins.

Secupress est installé, mais pas activé. Pour améliorer la sécurité de mon site, on va l’activer, qu’en pensez-vous ?

$ wp plugin activate secupress
Plugin 'secupress' activated.
Success: Activated 1 of 1 plugins.

Pour toutes ces commandes, vous pouvez passer plusieurs slugs d’extensions, ou utiliser --all pour tout mettre à jour ou activer. Dans le cas de l’activation, --network permet aussi d’activer une extension sur l’ensemble des sites d’une installation multisites.

Vous pouvez aussi rechercher une extension sur le repertoire officiel de WordPress pour pouvoir l’installer ensuite. C’est très pratique si vous ne connaissez pas directement le slug de l’extension dont vous avez besoin.

`wp plugin search` et `wp plugin install` sont très utiles pour chercher et installer une extension.

Si vous avez besoin de consulter les informations sur une extension, vous pouvez utiliser wp plugin get.

Lisez les informations sur une extension avec `wp plugin get`

D’autres commandes sont disponibles mais ces quelques commandes couvriront 95% de vos besoins. N’hésitez pas à explorer et expérimenter ! Sur un site local en toute sécurité, bien sûr !

Gérer vos thèmes

Exactement de la même façon que pour les extensions, vous pouvez gérer vos thèmes depuis votre terminal avec les sous-commandes de wp theme.

Les sous-commandes disponibles sont les mêmes que pour les extensions, donc si vous avez compris comment fonctionnent les exemples précédents, alors vous savez déjà comment lister, mettre à jour, supprimer ou installer des thèmes.

Les sous-commandes `list`, `update`, `activate`, `delete` sont disponibles pour les thèmes.

De plus, les commandes wp theme enable et wp theme disable permettent de rendre disponibles ou non des thèmes sur les installations multisites.

Enfin, on peut aussi manipuler les réglages du thème grâce à wp theme mod. C’est moins confortable que dans l’outil de personnalisation car on n’a pas de prévisualisation, mais si vous savez ce que vous faites, cela peut être pratique.

## Lister les réglages du thème 
$ wp theme mod list

## Récupérer la valeur du réglage `background_color`
$ wp theme mod get background_color

## Régler la valeur du réglage `background_color` sur fff
$ wp theme mod set background_color fff

## Supprimer tous les réglages
$ wp theme mod remove --all

Conclusion

WP CLI est un outil très puissant et relativement simple à utiliser. Il est aussi très bien documenté, aussi bien en interne à l’aide de la commande wp help que sur la documentation officielle.

Une poignée de commandes suffit pour vous permettre de gérer vos sites WordPress locaux et distants facilement et rapidement, sans avoir besoin de vous connecter ou d’accéder à l’interface d’administration du site.

Voici un récapitulatif des commandes essentielles dont vous aurez le plus besoin :

wp help
wp core update
wp core download
wp plugin update
wp plugin search
wp plugin install
wp plugin activate
wp plugin delete
wp theme update
wp theme activate
wp theme delete

Essayez ! Vous serez surpris de combien il est facile d’administrer vos sites !

Dans la prochaine partie de cette mini-série, on étudiera comment gérer le contenu de vos sites.