name	wpdt-cli
description	Use when debugging WordPress performance, profiling REST endpoints, investigating slow queries, managing debug mode, or working with WP Debug Toolkit. Provides CLI commands for endpoint profiling, API discovery, query analysis, and debug configuration.

WP Debug Toolkit CLI

WP Debug Toolkit Pro adds CLI commands for debugging, profiling, and interacting with WordPress REST APIs from the terminal. The headline feature is --profile on any REST endpoint — one command gives you full query analysis, timing, memory usage, and component attribution.

Running WP-CLI

Always use the wrapper script bundled with this skill instead of bare wp:

WP="bash ${CLAUDE_SKILL_DIR}/scripts/wp"

The wrapper handles the common problem where wp isn't available in your terminal session. This happens because AI agents run in the user's regular terminal, which doesn't have access to the PHP binary and MySQL socket that tools like Local by Flywheel, MAMP, or Docker use internally. The wrapper detects the environment and constructs the correct invocation automatically.

Never run bare wp commands. They will fail unless you're inside a site shell or have WP-CLI configured system-wide.

Note for non-Claude agents: If ${CLAUDE_SKILL_DIR} doesn't resolve in your environment, use the path to this skill's directory instead (e.g., .claude/skills/wpdt-cli/scripts/wp or .cursor/skills/wpdt-cli/scripts/wp).

Key Workflows

Profile any REST endpoint

Check performance of any endpoint — yours or third-party:

$WP dbtk api call GET /wc/v3/products --params='{"per_page":5}' --profile

The profile output includes:

execution_time_ms — total time for the endpoint
memory.delta_mb / peak_mb — memory consumption
queries.total — number of database queries executed
queries.slow — queries exceeding the slow threshold (50ms)
queries.duplicates — repeated queries (N+1 problems)
queries.by_type — breakdown by SELECT, INSERT, UPDATE, DELETE
queries.by_component — which plugin/theme triggered each query
queries.slowest — the top 5 slowest queries with SQL and component
php_errors — any PHP errors/warnings captured during execution

Measure your code's impact

Before your change:

$WP dbtk api call GET /wp/v2/posts --profile > /tmp/before.json

Make your change, then:

$WP dbtk api call GET /wp/v2/posts --profile > /tmp/after.json

Compare query counts, timing, and duplicates between the two.

Check if your plugin adds overhead

Profile an endpoint and check the by_component field:

$WP dbtk api call GET /wc/v3/products --profile

The profile.queries.by_component object shows exactly how many queries each plugin contributes. If your plugin is listed with a high count, investigate those queries.

Discover all REST APIs on a site

$WP dbtk api discover      # Scan all plugins/themes/core for REST routes
$WP dbtk api list           # Show all discovered routes
$WP dbtk api list --source=woocommerce  # Filter by plugin
$WP dbtk api search "order" # Find endpoints by keyword
$WP dbtk api show /wc/v3/products  # Full detail for a specific route

Enable/disable debug mode

$WP dbtk debug on          # Enable WP_DEBUG + WP_DEBUG_LOG
$WP dbtk debug on --display # Also enable WP_DEBUG_DISPLAY
$WP dbtk debug off         # Disable all debug constants
$WP dbtk debug status      # Show current settings

Call any REST endpoint

# GET request
$WP dbtk api call GET /wp/v2/posts --params='{"per_page":2}'

# POST request
$WP dbtk api call POST /wpdebugtoolkit/v1/query-logger/record --params='{"duration":60}'

# With profiling (three modes)
$WP dbtk api call GET /wp/v2/posts --profile          # Full profile
$WP dbtk api call GET /wp/v2/posts --profile=queries   # Query data only
$WP dbtk api call GET /wp/v2/posts --profile=summary   # Just timing + counts

Record and analyze a workflow

Capture everything that happens during a sequence of actions:

# Start recording with a label (--duration is optional; omit it to record until you stop)
$WP dbtk query-log start --tag=my-test

# Do stuff — run CLI commands, browse the site, whatever
$WP post list
$WP wc product list

# Stop recording
$WP dbtk query-log stop

# Analyze what happened
$WP dbtk query-log read --tag=my-test --slow --duplicates
$WP dbtk query-log read --tag=my-test --component=woocommerce --format=json
$WP dbtk query-log read --tag=my-test --summary           # Per-page overview
$WP dbtk query-log read --tag=my-test --memory             # Memory usage per page
$WP dbtk log read --level=error,warning --plugin=woocommerce --since=5m

Compare before and after while vibecoding

When building features or fixing bugs, use tagged recordings to catch performance regressions as you go:

# Record a baseline
$WP dbtk query-log start --tag=before-fix
# User browses the site / tests the flow
$WP dbtk query-log stop
$WP dbtk query-log read --tag=before-fix --summary

# Make the code change, then record again
$WP dbtk query-log start --tag=after-fix
# User tests the same flow
$WP dbtk query-log stop
$WP dbtk query-log read --tag=after-fix --summary

# Compare: did query count drop? Any new slow queries? Memory change?
$WP dbtk query-log read --tag=before-fix --memory
$WP dbtk query-log read --tag=after-fix --memory

This is a good habit to build into any vibecoding workflow — record before, record after, compare.

Read query logs with filters

$WP dbtk query-log read --tag=my-recording      # By recording session
$WP dbtk query-log read --component=woocommerce  # By plugin
$WP dbtk query-log read --type=SELECT --slow     # Slow SELECTs only
$WP dbtk query-log read --duplicates             # N+1 patterns
$WP dbtk query-log read --search="+wp_posts -wp_options"  # SQL text search
$WP dbtk query-log read --since=5m --format=json # Last 5 minutes as JSON

Read debug logs with filters

$WP dbtk log read --level=error,fatal            # Errors and fatals only
$WP dbtk log read --plugin=woocommerce           # From a specific plugin
$WP dbtk log read --source=theme --since=1h      # Theme errors in last hour
$WP dbtk log read --search="+undefined -deprecated" --format=json

Manage query logging

$WP dbtk query-log on      # Enable query logging
$WP dbtk query-log stats   # Show log statistics
$WP dbtk query-log clear   # Clear the log
$WP dbtk query-log off     # Disable query logging

Annotate third-party endpoints

When you figure out what a cryptic endpoint does, save it:

$WP dbtk api edit /elementor/v1/globals --description="Fetch global design settings (colors, fonts)"

Annotations persist across discovery runs.

Quick Command Reference

Command	Purpose
`dbtk api list`	List routes (--namespace, --method, --source, --format)
`dbtk api discover`	Scan all registered REST routes
`dbtk api call <METHOD> <route>`	Call any endpoint (--params, --profile, --format)
`dbtk api show <route>`	Show full detail for a route
`dbtk api search <keyword>`	Search routes by keyword
`dbtk api edit <route>`	Annotate an endpoint (--description)
`dbtk debug on/off/status`	Control WP_DEBUG, WP_DEBUG_LOG, WP_DEBUG_DISPLAY
`dbtk log clear/stats`	Manage debug.log file
`dbtk log read`	Read debug.log with filters (--level, --plugin, --since, --search)
`dbtk query-log on/off/clear/stats`	Control database query logging
`dbtk query-log start/stop/status`	Control recording sessions (--tag, optional --duration)
`dbtk query-log read`	Read query logs with filters (--tag, --component, --slow, --duplicates, --summary, --memory)
`dbtk viewer setup/remove/status`	Manage standalone log viewer
`dbtk license activate/deactivate/status`	License management

Detailed References

For complete wp dbtk api command documentation, see references/api-commands.md
For debug, log, query-log, viewer, and license commands, see references/debug-commands.md
For profiling workflows with real output examples, see references/profiling-guide.md

Requirements

WP Debug Toolkit Pro plugin must be installed and active on the WordPress site
The site must be running (start it in Local by Flywheel, DDEV, Docker, etc. before running commands)
Query logging features require a Pro license (basic profiling works for all users)

Troubleshooting

Run the probe command to see what environment was detected:

bash ${CLAUDE_SKILL_DIR}/scripts/wp --probe

Common issues:

"MySQL socket not found" — The site isn't running. Start it in your local development tool.
"Could not find WordPress root" — Run from within a WordPress installation directory.
"Command not found: dbtk" — WP Debug Toolkit plugin isn't installed or activated.
"Error establishing a database connection" — Don't use bare wp. Use the wrapper script.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WP Debug Toolkit CLI

Running WP-CLI

Key Workflows

Profile any REST endpoint

Measure your code's impact

Check if your plugin adds overhead

Discover all REST APIs on a site

Enable/disable debug mode

Call any REST endpoint

Record and analyze a workflow

Compare before and after while vibecoding

Read query logs with filters

Read debug logs with filters

Manage query logging

Annotate third-party endpoints

Quick Command Reference

Detailed References

Requirements

Troubleshooting

FilesExpand file tree

SKILL.md

Latest commit

History

SKILL.md

File metadata and controls

WP Debug Toolkit CLI

Running WP-CLI

Key Workflows

Profile any REST endpoint

Measure your code's impact

Check if your plugin adds overhead

Discover all REST APIs on a site

Enable/disable debug mode

Call any REST endpoint

Record and analyze a workflow

Compare before and after while vibecoding

Read query logs with filters

Read debug logs with filters

Manage query logging

Annotate third-party endpoints

Quick Command Reference

Detailed References

Requirements

Troubleshooting