Skip to main content

WP-CLI Local Wrapper

A shell wrapper that enables WP-CLI commands in Local by Flywheel environments where MySQL runs via a Unix socket instead of TCP.

The Problem​

Local by Flywheel runs MySQL through a Unix socket (e.g., ~/Library/Application Support/Local/run/<id>/mysql/mysqld.sock). Standard wp CLI calls fail with database connection errors because localhost doesn't resolve to the socket path.

Quick Start​

1. Create the .local marker file​

cd wp-content/plugins/yoko-core
cp .local.sample .local

2. Update wp-config.php​

Change the DB_HOST definition to support both web and CLI contexts:

define( 'DB_HOST', getenv( 'WP_LOCAL_DB_HOST' ) ?: 'localhost' );

This keeps browser requests working (localhost) while allowing the wrapper to inject the Local socket path via the WP_LOCAL_DB_HOST environment variable.

3. Run WP-CLI commands​

./bin/wp option get siteurl
./bin/wp plugin list
./bin/wp core version

Troubleshooting​

"Error establishing a database connection"​

  1. Verify .local exists: ls -la .local
  2. Verify the Local site is running in the Local app
  3. Check that wp-config.php uses the env-aware DB_HOST: 
    define( 'DB_HOST', getenv( 'WP_LOCAL_DB_HOST' ) ?: 'localhost' );
  4. Test socket detection: ./bin/wp option get siteurl — the log output will show which socket was found

"No Local MySQL socket could be found"​

The Local site may not be running, or the socket path has changed. Start the site in the Local app and try again.

".local file not found" when not using Local​

If you're not using Local by Flywheel, you don't need the .local file. The wrapper will fall back to finding wp-config.php automatically.