I’ve become a big fan of LocalWP (formerly Local by Flywheel) for local WordPress development (i.e. running websites on my Mac). One thing I do find frustrating is the need to use “Open Site Shell” when I want to run a WP-CLI command.
If you’re in a hurry to set this up, you can jump to the Quick Setup below.
Configure WP-CLI to work without “Open Site Shell”
The key to making this work is adding two files
Where to Add These Files
Both of these files go in the project root directory. The project root directory for the website contains three folders (
/logs) by default. Your two new files with be alongside these directories.
What Goes In These Files
The contents of
wp-cli.local.php will vary for each Local site. The information you will need can be found in the LocalWP dashboard for your site under the heading DATABASE. We are looking for the
In my screenshot the
Socket value is:
We combine this Socket value with
local:, to define the
DB_HOST value in the file
define('DB_HOST', 'localhost:/Users/sal/Library/Application Support/Local/run/lBW9-Gu_J/mysql/mysqld.sock');
// Only display fatal run-time errors.
// See http://php.net/manual/en/errorfunc.constants.php.
// Disable WordPress debug mode.
// See https://codex.wordpress.org/WP_DEBUG.
Confirm WP-CLI Works
To confirm everything is setup correctly from the command line (on your Mac, without using “Open Site Shell”) run:
$ wp option get siteurl
and if everything is working properly, you’ll get back the URL for your website.
My most common error at this point is forgetting to have the website running in the LocalWP Dashboard. We can’t use WP-CLI with the site, if the site is not running.
If you get a response like “command not found: wp”, then you likely need to install WP-CLI.
How Does this Work?
WP-CLI checks for config files named
wp-cli.yml inside the current working directory (or upwards).
By adding our
wp-cli.local.yml to the project root, any command run anywhere inside the project will use our
wp-cli.local.yml configuration (WP-CLI config documentation).
We define the
path to the WordPress install in relation to
wp-cli.local.yml and we require the file
wp-cli.local.php be run before any of the WordPress files.
We override the
DB_HOST database connection value defined in
wp-config.php to include the database socket specific to our site. Since our database connection information is set before
wp-config.php, our information is used. Since WordPress tries to set these constants after they are already set, PHP throws notices. To suppress these notices we set PHP to only display fatal run-time errors.
Other Methods to Setup
Run this command from the the project root directory of the site.
$ curl -O https://raw.githubusercontent.com/salcode/wpcli-localwp-setup/main/wpcli-localwp-setup && bash wpcli-localwp-setup && rm -rf ./wpcli-localwp-setup
Running the following at the command line will:
- download a bash script to create the two files (
- run the bash script (you’ll be prompted for the Database
socketvalue, which can be found on the Database tab of the site in LocalWP)
- delete the bash script, leaving the two new files behind
The Quick Setup files come from my salcode/wpcli-localwp-setup project.
Thanks to my employer WebDevStudios who provides weekly time when our programmers can gather and chat about technology and bounce around ideas. The updates to make this compatible with LocalWP (instead of the old Local by Flywheel) came out of one of those meetings. Particular thanks to my co-workers Aubrey Portwood, Richard Aber, Ashar Irfan, and Justin Foell for all their input and solutions to problems I couldn’t figure out.
In addition to providing invaluable time for programmers to chat and bounce around ideas, WebDevStudios also sets aside time for Five for the Future, which is dedicated time for us to give back to the open source community. Some of this time I used to put together this information.
This project was originally inspired by Morgan Estes’s work with his project BigWing/Local-WP-CLI.
Thanks to Justin Sternberg for sharing his similar quick setup in his Dot-Files.