CLI Environment Setup

Getting wp dbtk to work means getting WP-CLI to connect to your WordPress site’s database. Once that works, the plugin commands are available automatically.

Quick check

Run this from your site’s root directory:

wp --info

If you see PHP and WordPress version information, you’re set. Skip to the command reference.

If you get command not found or a database connection error, keep reading.

Why `wp` might not work

Some development environments bundle their own PHP and MySQL binaries, using Unix sockets or custom paths that aren’t visible to your regular terminal. The most common case:

Local by Flywheel — Each site has its own PHP binary and MySQL socket managed by Local’s “lightning-services” runtime. The system wp command can’t connect to the database because it doesn’t know the socket path.
MAMP / MAMP Pro — PHP runs through MAMP’s own binary, not the system PHP. WP-CLI may not be installed or may use the wrong PHP version.
Docker / DDEV / Lando — WordPress runs inside a container. You need to exec into the container or use the tool’s built-in wrapper.

Install the agent skill (recommended for AI-assisted development)

If you’re using Claude Code, Cursor, or a similar AI coding assistant, install the wpdt-cli agent skill. It includes a wrapper script that auto-detects Local by Flywheel, finds the correct PHP binary and MySQL socket, and proxies WP-CLI commands.

npx skills add WP-Debug-Toolkit/wpdt-cli

After installation, the agent uses the wrapper script at scripts/wp inside the skill directory for all WP-CLI commands. No manual path configuration needed.

Use the wrapper script directly

The wrapper script works independently of the agent skill. Clone or download it from the wpdt-cli repository:

bash /path/to/wpdt-cli/scripts/wp dbtk api list
bash /path/to/wpdt-cli/scripts/wp dbtk api discover
bash /path/to/wpdt-cli/scripts/wp --probe   # Show detected environment

The --probe flag outputs what the script detected as JSON — useful for verifying it found the right PHP binary and MySQL socket.

Local by Flywheel manual setup

If you prefer not to use the wrapper script, you can call WP-CLI directly through Local’s PHP binary with the MySQL socket specified.

1. Find your site’s ID and PHP version:

Open ~/Library/Application Support/Local/sites.json and find your site entry. Note the id, services.php.version, and path fields.

2. Locate the PHP binary:

~/Library/Application Support/Local/lightning-services/php-<version>/bin/darwin-arm64/bin/php   # Apple Silicon
~/Library/Application Support/Local/lightning-services/php-<version>/bin/darwin/bin/php          # Intel

Replace <version> with your site’s PHP version (e.g., 8.2.23+0).

3. Locate the MySQL socket:

~/Library/Application Support/Local/run/<site-id>/mysql/mysqld.sock

The site must be running in Local for the socket to exist.

4. Locate WP-CLI:

/Applications/Local.app/Contents/Resources/extraResources/bin/wp-cli/wp-cli.phar

5. Run commands:

"$PHP" -d "mysqli.default_socket=$SOCKET" "$WP_CLI" --path="$WP_ROOT" dbtk api list

Full example for Apple Silicon:

"/Users/you/Library/Application Support/Local/lightning-services/php-8.2.23+0/bin/darwin-arm64/bin/php" \
  -d "mysqli.default_socket=/Users/you/Library/Application Support/Local/run/abc123/mysql/mysqld.sock" \
  "/Applications/Local.app/Contents/Resources/extraResources/bin/wp-cli/wp-cli.phar" \
  --path="/Users/you/Local Sites/my-site/app/public" \
  dbtk api list

This is why the wrapper script exists — it constructs this invocation automatically.

Docker, DDEV, and Lando

Detailed setup guides for these environments are planned. In the meantime, each tool has a built-in wp wrapper that handles container access:

# DDEV
ddev wp dbtk api discover

# Lando
lando wp dbtk api discover

# Plain Docker
docker compose exec wordpress wp dbtk api discover --allow-root

The --allow-root flag is sometimes needed in Docker containers where WordPress runs as root.

For LLM agents

If you’ve installed the wpdt-cli agent skill (npx skills add WP-Debug-Toolkit/wpdt-cli), the agent has everything it needs — the SKILL.md teaches it how to use the wrapper script and what commands are available.

For manual configuration without the skill, add this to your CLAUDE.md or equivalent context file:

## WP-CLI Access

Use the wrapper script for all WP-CLI commands:
  bash /path/to/wpdt-cli/scripts/wp <command>

Example:
  bash /path/to/wpdt-cli/scripts/wp dbtk api list --format=json
  bash /path/to/wpdt-cli/scripts/wp dbtk api call GET /wp/v2/posts --profile

The wrapper auto-detects Local by Flywheel and handles PHP/MySQL socket configuration.

Troubleshooting

“Error establishing a database connection” The most common issue in Local by Flywheel. The system wp can’t find the MySQL socket. Use the wrapper script or specify the socket path manually with -d "mysqli.default_socket=...".

“Error: This does not seem to be a WordPress install.” You’re running wp from the wrong directory. Add --path=/path/to/wordpress pointing to the folder with wp-config.php, or cd into that directory first.

“MySQL socket not found” (from the wrapper script) The site isn’t running in Local by Flywheel. Start it in the Local app, then retry.

“Could not find WordPress root” (from the wrapper script) Run the command from within a WordPress installation directory (any subdirectory of the WordPress root).

“Your PHP installation appears to be missing the MySQL extension” You’re using the system PHP instead of Local’s PHP binary. Use the wrapper script or specify Local’s PHP path.

wp dbtk commands not found but wp works WP Debug Toolkit Pro isn’t installed or isn’t active. Check with wp plugin list and activate with wp plugin activate wpdebugtoolkit.