wpdt-cli

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 list --annotated-only       # Only routes with saved annotations
$WP dbtk api list --tag=mutates-data     # Filter by annotation tag
$WP dbtk api search "order" # Find endpoints by keyword
$WP dbtk api search "order" --source=woocommerce --annotated-only
$WP dbtk api show /wc/v3/products  # Full detail for a specific route
$WP dbtk api show /wc/v3/products --method=POST  # Method-specific detail

Load a plugin's API into your session before doing API work

When you're about to work against a specific plugin's REST API, run bootstrap first. It produces a Markdown brief — namespace, route counts, safety distribution, per-route summaries with method annotations — that's faster and more accurate than rediscovering everything mid-conversation:

$WP dbtk api bootstrap --source=woocommerce            # Markdown brief, paste into context
$WP dbtk api bootstrap --source=rankmath --annotated-only --max-routes=20
$WP dbtk api bootstrap --source=woocommerce --format=json   # For programmatic use

If bootstrap returns "Source not found," run $WP dbtk api discover first.

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 endpoints with semantic metadata

Every time you figure out what a cryptic endpoint does — its safety, its required role, what it returns — save it. Annotations persist across discover runs and become part of every future list, show, search, and bootstrap for that route.

Use method-level annotations whenever possible (a GET is often safe while the matching POST is destructive). Always include --safety so future agent sessions know whether the endpoint is safe to call without user confirmation.

# Route-level summary (applies to all methods)
$WP dbtk api edit /elementor/v1/globals \
  --description="Fetch global design settings (colors, fonts)" \
  --safety=read-only

# Method-level annotation with full detail
$WP dbtk api edit /wc/v3/orders --method=POST \
  --description="Create a new order" \
  --safety=mutates-data \
  --auth-note="Requires shop_manager or administrator" \
  --returns="Created order object with id and status" \
  --verification=verified-runtime

# Tag for grouping; verification marks how confident you are
$WP dbtk api edit /wc/v3/orders --tag=orders,wc --verification=verified-runtime

Valid --safety values: read-only, mutates-data, destructive, unknown. Valid --verification values: inferred, verified-source, verified-runtime, verified-docs.

Share annotations across sites

Annotations are stored as a portable JSON pack. Export from one site, import on another to seed the knowledge base instantly:

# Export annotated routes for a plugin
$WP dbtk api export --source=woocommerce --annotated-only > woocommerce-annotations.json

# On another site, preview then import
$WP dbtk api import woocommerce-annotations.json --dry-run
$WP dbtk api import woocommerce-annotations.json                  # Merge with existing
$WP dbtk api import woocommerce-annotations.json --mode=replace-source  # Replace all for source

Use --template on export to generate empty fields for batch annotation:

$WP dbtk api export --source=rankmath --template > rankmath-template.json

Quick Command Reference

Command	Purpose
dbtk api list	List routes (--namespace, --method, --source, --annotated-only, --tag, --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 (--method, --format)
dbtk api search <keyword>	Search routes by keyword (--source, --annotated-only, --format)
dbtk api edit <route>	Annotate an endpoint (--method, --description, --safety, --auth-note, --returns, --tag, --verification)
dbtk api export	Export annotations as a portable pack (--source, --annotated-only, --template)
dbtk api import <file>	Import an annotation pack (--mode=merge|replace-source, --dry-run)
dbtk api bootstrap	Generate a Markdown brief for an agent session (--source, --annotated-only, --max-routes)
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.