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 terminal in the 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 from your terminal

If you’re running wp directly from a Local by Flywheel site shell, DDEV shell, or any environment where WP-CLI is already configured, everything works out of the box. The problem arises when you’re in a regular terminal session — which is where AI coding agents (Claude Code, Cursor, Codex, etc.) always run.

These tools use PHP and MySQL binaries that aren’t in your regular terminal’s PATH:

Local by Flywheel — WP-CLI works perfectly inside Local’s site shell. But your regular terminal (and any AI agent running in it) doesn’t have access to Local’s PHP binary or MySQL socket. Running bare wp from a regular terminal fails with a database connection error.
MAMP / MAMP Pro — Similar situation. MAMP’s PHP and MySQL are accessible inside MAMP’s environment but not from a regular terminal.
Docker / DDEV / Lando — WordPress runs inside a container. From a regular terminal, you need to exec into the container or use the tool’s built-in wrapper (ddev wp, lando wp).

The wrapper script included with the agent skill bridges this gap — it detects which environment you’re in and constructs the right invocation automatically.

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 detects your environment and proxies WP-CLI commands with the correct PHP binary and database socket.

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 — external terminal setup

Inside Local’s site shell (the terminal icon next to each site in the Local app), wp works without any configuration. This section is for running commands from an external terminal — the kind AI agents use.

If you prefer not to use the wrapper script, you can invoke WP-CLI manually 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 what the wrapper script constructs 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 the environment and handles PHP/MySQL configuration.

Troubleshooting

“Error establishing a database connection” Your terminal doesn’t have access to the site’s MySQL socket. This happens when running wp from a regular terminal instead of a site shell. 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. Start it in the Local app (or start your Docker/DDEV/Lando environment), 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” Your terminal’s PHP doesn’t have MySQL support. Use the wrapper script, which uses the correct PHP binary for your environment.

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.