The MySQL Socket Problem: Connecting WP-CLI to Local by Flywheel

You install WP-CLI, navigate to your Local by Flywheel site, run wp post list, and get slapped with Error: Error establishing a database connection. Your site works fine in the browser. MySQL is running. The credentials are correct. So what’s broken?

The Socket Mismatch

Local by Flywheel runs its own MySQL instance with its own Unix socket — typically something like /Users/you/Library/Application Support/Local/run/XXXXXXXX/mysql/mysqld.sock. When you run WP-CLI from your terminal, it reads your site’s wp-config.php, finds DB_HOST set to localhost, and tries to connect via the system’s default MySQL socket, usually /tmp/mysql.sock.

Those are two different sockets. Your system might not even have MySQL installed globally — Local bundles its own. The connection fails because WP-CLI is knocking on a door that either doesn’t exist or leads to the wrong MySQL instance.

You can verify this by checking what socket Local is using. Open your site’s wp-config.php or check Local’s site info panel. You’ll see the MySQL socket path buried in the configuration.

The Quick Fix: Define the Socket

You can tell PHP which socket to use by setting an environment variable before running WP-CLI:

export MYSQL_UNIX_PORT="/Users/you/Library/Application Support/Local/run/abcdefgh/mysql/mysqld.sock"
wp post list

That works, but the socket path changes when Local recreates the site or updates. You’d have to update it constantly.

The Better Fix: A Wrapper Script

I wrote a shell script that dynamically finds Local’s MySQL socket and sets it before calling WP-CLI. Save this as wp in your project root and make it executable:

#!/bin/bash
# wp - WP-CLI wrapper for Local by Flywheel
# Finds the active MySQL socket and sets it before calling wp-cli

# Find Local's MySQL socket
LOCAL_SOCKET=$(find "$HOME/Library/Application Support/Local/run" 
  -name "mysqld.sock" -type s 2>/dev/null | head -1)

if [ -z "$LOCAL_SOCKET" ]; then
  echo "Error: Could not find Local by Flywheel MySQL socket."
  echo "Make sure Local is running and your site is started."
  exit 1
fi

export MYSQL_UNIX_PORT="$LOCAL_SOCKET"

# Find WP-CLI - check common locations
WPCLI=$(which wp 2>/dev/null)

if [ -z "$WPCLI" ]; then
  # Try Homebrew location
  WPCLI="/opt/homebrew/bin/wp"
fi

if [ ! -f "$WPCLI" ]; then
  echo "Error: WP-CLI not found. Install with: brew install wp-cli"
  exit 1
fi

# Pass all arguments through to WP-CLI
"$WPCLI" "$@" --path="$(dirname "$0")/path/to/wordpress"

Now ./wp post list from your project root just works. The script finds the socket automatically, so it survives Local restarts and site recreations.

Debugging Connection Issues

If you’re still having trouble after setting the socket, work through this checklist:

1. Is the site started in Local? The MySQL socket only exists while the site is running. Open Local and make sure your site shows “Running” — not just that Local is open, but that the specific site is started.

# Check if the socket file exists
ls -la "$HOME/Library/Application Support/Local/run/"/*/mysql/mysqld.sock

2. Are the credentials correct? Local typically uses root / root for MySQL. Check your wp-config.php:

# These should match Local's settings
grep -E 'DB_(NAME|USER|PASSWORD|HOST)' wp-config.php

3. Is PHP using the right socket? Check what socket PHP thinks it should use:

php -r "echo ini_get('mysqli.default_socket') . PHP_EOL;"
# Compare with:
echo $MYSQL_UNIX_PORT

4. Can you connect directly? Test the MySQL connection outside of WordPress:

# Using Local's socket directly
mysql -u root -proot -S "$MYSQL_UNIX_PORT" -e "SHOW DATABASES;"

If that works but WP-CLI doesn’t, the problem is in how PHP resolves the socket, not in MySQL itself.

The Nuclear Option: TCP Instead of Socket

If socket paths keep causing grief, you can bypass Unix sockets entirely by connecting over TCP. In your wp-config.php, change DB_HOST from localhost to 127.0.0.1:

define('DB_HOST', '127.0.0.1:10008');

When you use an IP address instead of localhost, PHP uses TCP instead of a Unix socket. Check Local’s site info for the correct MySQL port — it’s not always the default 3306. This approach is less performant than sockets (TCP adds overhead), but it eliminates socket path issues entirely.

Why This Matters for Development

WP-CLI is essential for headless WordPress development. Importing content, managing post types, clearing caches, running database queries — you need a working CLI connection. Spending 20 minutes to set up the wrapper script saves hours of frustration down the road.

Keep the wrapper script in your project repo. When a teammate clones the project and asks “how do I run WP-CLI with Local?”, the answer is just ./wp.