CLI Environment Setup

wp dbtk commands become available automatically once WP-CLI can connect to your WordPress database. Run wp --info from your terminal: if you see WP-CLI version and PHP system information, WP-CLI is accessible from this terminal, and you can proceed to the CLI Command Reference. If you see command not found or a database connection error, your terminal lacks access to the correct PHP binary or MySQL socket. Local by Flywheel, MAMP, and containerized environments (Docker, DDEV, Lando) all produce this problem from a regular terminal session.

Quick Check

Run the following command from your terminal:

bash

wp --info

🔀 Decision Point: If you see WP-CLI version and PHP system information, WP-CLI is accessible from your terminal. Run wp dbtk log stats to confirm the database connection. If that command works, go directly to the CLI Command Reference. If you see “command not found: WP-CLI is not installed or not in your terminal’s PATH, install WP-CLI before continuing. If wp --info runs but wp dbtk commands return a database error: Your terminal cannot reach your environment’s database. Continue below to find the setup path for your environment.

Why wp Might Not Work from Your Terminal

If you’re running wp from a Local by Flywheel site shell, a DDEV shell, or any environment where WP-CLI is already configured, everything works without any extra setup. The problem arises in a regular terminal session, which is where AI coding agents like Claude Code, Cursor, and Codex always run. They are not a separate environment category; they just operate in the same regular terminal session that causes this problem for everyone else.

These environments use PHP and MySQL binaries that are not available in a regular terminal’s PATH:

Local by Flywheel: WP-CLI works inside Local’s built-in site shell. A regular terminal has no access to Local’s PHP binary or MySQL socket, so running wp from one fails with a database connection error.

MAMP and MAMP Pro: The same situation. MAMP’s PHP and MySQL are scoped to MAMP’s own environment and are not accessible from a regular terminal. Automatic detection for MAMP is not yet available in the wrapper script. Detailed setup guidance for MAMP is planned.

Docker, DDEV, and Lando: WordPress runs inside a container. A regular terminal cannot reach it directly, so you need to exec into the container or use the tool’s built-in wrapper (ddev wp, lando wp).

The WPDT wrapper script auto-detects Local by Flywheel, locates the correct PHP binary and MySQL socket, and constructs the invocation automatically. For all other environments, the wrapper falls back to a working system wp. If your system wp cannot connect, which is the case in Docker, DDEV, and Lando, use the tool’s own entry points instead, covered in Step 4.

Step-by-Step: Environment Setup

The four steps below are parallel options rather than a sequential workflow. Pick the one that best matches your environment.

Step 1: Use the Agent Skill (Recommended for AI-Assisted Development)

This is the recommended path if you use an AI coding assistant such as Claude Code, Cursor, Codex, or any agent that runs commands from a regular terminal session. The skill installs the wrapper script and automatically registers it with your agent.

bash

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

After installation, your agent uses the wrapper at scripts/wp inside the skill directory. Use the --probe flag to confirm the wrapper resolved your environment correctly:

bash

bash /path/to/wpdt-cli/scripts/wp --probe   # outputs detected PHP binary and MySQL socket as JSON

✅ What You Should See: The probe outputs a JSON object confirming the PHP binary path and MySQL socket that the wrapper detected. If both values point to your local environment’s PHP and database, the setup is complete. Run any wp dbtk command to confirm.

Step 2: Use the Wrapper Script Directly

If you want the wrapper without the agent skill, clone or download the repository directly.

bash

# Clone the wrapper repository — verify URL before use

git clone https://github.com/WP-Debug-Toolkit/wpdt-cli   # [VERIFY: confirm this repo URL is current]

# Run any wp dbtk command through the wrapper

bash /path/to/wpdt-cli/scripts/wp dbtk api list

bash /path/to/wpdt-cli/scripts/wp dbtk api discover

# Probe to confirm the wrapper detected the right environment

bash /path/to/wpdt-cli/scripts/wp --probe   # outputs JSON with detected PHP binary and socket

Run --probe first. If the detected paths match your environment, every wp dbtk command will work through the wrapper.

Step 3: Local by Flywheel — Manual External Terminal Setup

Local by Flywheel stores its PHP binary in your home directory and routes MySQL through a Unix socket. Your system PHP has no access to either. The four steps below configure an external terminal session to use Local’s PHP and socket directly.

Note: The wrapper script (Steps 1 and 2) auto-detects Local by Flywheel and handles this configuration automatically. The steps below follow the same mechanism manually, which is useful if you want to verify what the wrapper is doing or need to invoke PHP directly.

Open Local and start your site. Local’s PHP binary lives in ~/Library/Application Support/Local/lightning-services/. The correct path depends on two independent variables: the PHP version your site is configured to run (visible in Local’s site settings), and your Mac’s CPU architecture.

bash

  # Apple Silicon

   "$HOME/Library/Application Support/Local/lightning-services/php-<version>/bin/darwin-arm64/bin/php"

   # Intel

   "$HOME/Library/Application Support/Local/lightning-services/php-<version>/bin/darwin/bin/php"

Replace <version> with the PHP version assigned to your site in Local, for example, php-8.1.23+0. The architecture subfolder (darwin-arm64 or darwin) reflects your Mac’s chip, not the PHP version.

Locate Local’s WP-CLI phar file. Unlike the PHP binary, the phar is inside the application bundle:

bash

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

Find your site’s MySQL socket path. Open your site in Local and go to the Database tab. The socket follows this pattern:

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

Copy the full path shown in the Database tab. You will pass it directly to PHP in the next step.

Run wp dbtk commands, passing the socket path to PHP with -d "mysqli.default_socket=...":

bash

  # Apple Silicon example — replace <version>, <site-id>, and WordPress root with your own values

   "$HOME/Library/Application Support/Local/lightning-services/php-<version>/bin/darwin-arm64/bin/php" \

     -d "mysqli.default_socket=$HOME/Library/Application Support/Local/run/<site-id>/mysql/mysqld.sock" \

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

     dbtk log stats \

     --path=/path/to/your/wordpress-root   # absolute path to your WordPress installation

✅ What You Should See: The command outputs your current debug log statistics. If you see output from WPDT rather than a database or PHP error, the configuration is working correctly.

Step 4: Docker, DDEV, and Lando

For containerized environments, use the tool’s built-in WP-CLI wrapper or exec into the container directly.

bash

# DDEV — use ddev wp as the entry point for all WP-CLI commands

ddev wp dbtk api discover

# Lando — use lando wp as the entry point

lando wp dbtk api discover

# Plain Docker — exec into the WordPress container and run wp directly

docker compose exec wordpress wp dbtk api discover --allow-root

# --allow-root is required when WordPress runs as root inside the container

For LLM Agents

If your agent runs without the skill installed, add the following block to your CLAUDE.md file (or the equivalent context file for your agent) to give it the wrapper path and usage pattern:

markdown

## 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. For other environments, it falls back to your system wp.

Replace /path/to/wpdt-cli/scripts/wp with the actual path after cloning the repository or installing the skill.

Common Issues and How to Fix Them

Error establishing a database connection

Likely cause: Your terminal session does not have access to the MySQL socket your WordPress installation uses.

Fix: Use the wrapper script (Steps 1 or 2), which automatically locates the correct socket. To specify the socket manually, add -d "mysqli.default_socket=/path/to/socket" to your PHP invocation.

Error: This does not seem to be a WordPress install

Likely cause: You ran wp from a directory that is not the WordPress root.

Fix: Add --path=/path/to/wordpress to your command, or cd into the WordPress root directory before running it.

MySQL socket not found (from wrapper script)

Likely cause: Your Local by Flywheel, Docker, DDEV, or Lando environment is not running.

Fix: Start your environment and retry the command. The wrapper reads the socket path at runtime, so it cannot connect to a socket that does not exist yet.

Could not find WordPress root (from wrapper script)

Likely cause: You ran the wrapper from outside a WordPress installation directory and no --path flag was provided.

Fix: Run the command from within your WordPress installation directory, or add --path=/path/to/wordpress to the command.

Your PHP installation appears to be missing the MySQL extension

Likely cause: The PHP binary your terminal uses does not have MySQL support compiled in, which is common with macOS system PHP.

Fix: Use the wrapper script. The wrapper uses Local by Flywheel’s PHP binary rather than your system PHP. If you are not on Local, use the manual path configuration in Step 3 or the containerized entry points in Step 4.

`wp dbtk` commands not found but wp works

Likely cause: WP Debug Toolkit Pro is not installed or not active on this WordPress installation. The wp dbtk command group registers automatically when the plugin loads. If the plugin is not active, then the commands do not exist.

Fix: Check the plugin status with wp plugin list --status=active. If WPDT is not listed, activate it:

bash

wp plugin activate wpdebugtoolkit

CLI Environment Setup — Frequently Asked Questions

Do I need to install anything extra to use `wp dbtk` from the command line?

WP-CLI is the only external dependency. WP Debug Toolkit Pro must be installed and active on your WordPress site. Other than that, no additional WPDT-specific CLI installation is required as the wp dbtk command group registers automatically when the plugin loads. The agent skill and wrapper script are only needed to make WP-CLI itself work in a regular terminal session; they are environment tools, not WPDT-specific requirements.

Why do `wp dbtk` commands work in Local’s terminal but not in my VS Code terminal?

Local’s built-in site shell pre-configures the PHP binary and MySQL socket paths for that environment. A VS Code terminal, or any other external terminal session, uses your system PHP, which has no access to Local’s PHP installation or socket file. The wrapper script bridges that gap. Install it with npx skills add WP-Debug-Toolkit/wpdt-cli (Step 1) or clone it directly (Step 2) and use it as the entry point for all WP-CLI commands in any external terminal.

Can I use wp dbtk commands in a CI pipeline?

Yes. In CI environments where the container includes WP-CLI and WordPress is configured and accessible, wp dbtk commands work without modification. Add --allow-root if WordPress runs as root inside the container.