CLI Command Reference

WP Debug Toolkit (WPDT) exposes its features through wp dbtk commands grouped into six areas: api, debug, log, query-log, viewer, and license. This reference lists every subcommand’s syntax, flags, and a working example, from enabling WP_DEBUG with wp dbtk debug on to recording database queries with wp dbtk query-log start. Run wp dbtk <command> --help for the full flag list on any command.

Overview

This reference covers every wp dbtk command grouped by functional area: REST API tools, debug constants, the error log, the Database Monitor’s query logger, the standalone Viewer App, and license management. Every command also supports --help as live inline documentation, for example, wp dbtk api edit --help.

wp dbtk api

The api command group discovers, inspects, searches, calls, and annotates any registered REST API route on your site, including WordPress core, WooCommerce, and other plugin endpoints.

Discovery and Inspection Commands

Annotation and Portability Commands

bash

# Discover every route on the site, then narrow to WooCommerce GET endpoints

wp dbtk api discover

wp dbtk api list --namespace=wc/v3 --method=GET

# Call an endpoint with query-level profiling and get JSON back for scripting

wp dbtk api call GET /wc/v3/products --profile=queries --format=json

# Annotate a destructive endpoint, then export only annotated routes for sharing

wp dbtk api edit /wp/v2/posts/123 --method=DELETE --safety=destructive --verification=verified-source

wp dbtk api export --source=wpdebugtoolkit --annotated-only > /tmp/wpdt-annotations.json

# Generate a markdown brief for an AI coding assistant working on WooCommerce

wp dbtk api bootstrap --source=woocommerce --annotated-only --max-routes=20

--profile=summary returns a minimal queries object containing only a total count, while --profile=queries and --profile=full both return a full breakdown: total, slow and duplicate counts, queries grouped by type and by component, and the five slowest queries with timing. --profile=full adds one further field, php_errors, capturing any PHP warnings, notices, or deprecations triggered during the request

wp dbtk debug

The debug command group enables, disables, and reports on the core WP_DEBUG constants, all without touching wp-config.php in an editor or needing FTP access. WPDT writes these changes using atomic writes with an automatic one-time backup created before each write. If the atomic write fails, WPDT falls back to a direct write to wp-config.php. The backup is not automatically restored on failure.

bash

# Enable debugging for a live site without showing errors on screen

wp dbtk debug on

# Enable debugging with on-screen error display, for local or staging only

wp dbtk debug on --display

# Check current constant values and the configured log path as JSON

wp dbtk debug status --format=json

Never run debug on --display on a production site, as displaying raw PHP errors to visitors can expose file paths, query structure, and other details you do not want public.

wp dbtk log

The log command group reads, filters, and clears the WordPress debug.log file from the command line.

bash

# Show fatal entries attributed to WooCommerce in the last hour 

wp dbtk log read --level=fatal --plugin=woocommerce --since=1h

# Search for deprecated notices while excluding a known noisy source

wp dbtk log read --search="+deprecated -wp_options" --format=json

# Clear the log without a confirmation prompt

wp dbtk log clear --yes

--level= accepts a comma-separated list: fatal, warning, notice, parse, and deprecated. 

--since= accepts any <number><m|h|d> value; common examples include 5m, 1h, 24h, and 7d. Second and week values are not supported. 

--limit= defaults to 100 entries.

wp dbtk query-log

The query-log command group controls WPDT’s Database Monitor. WPDT writes every recorded query to disk rather than storing it in your WordPress database, so always-on capture adds no extra database load to production sites. Query data is encrypted with libsodium or AES-256-GCM via OpenSSL when a PHP crypto backend is available, and falls back to plaintext JSON on servers where neither is installed.

bash

# Record a checkout flow for two minutes under a custom tag

wp dbtk query-log start --duration=120 --tag=checkout-test

# After the session ends, review per-page performance summaries for that tag

wp dbtk query-log read --tag=checkout-test --summary

# Check peak memory usage per page load for the same recording

wp dbtk query-log read --tag=checkout-test --memory

# Find slow, duplicate WooCommerce queries and export them as JSON

wp dbtk query-log read --component=woocommerce --slow --duplicates --format=json

start --duration= defaults to 0, which records until you run stop. Recordings without a duration still auto-stop after 3,600 seconds (one hour) as a safety ceiling, and the maximum you can set explicitly is also 3,600 seconds. The read command’s --summary and --memory flags each produce a distinct row shape: --summary returns one row per page load with query counts, slow and duplicate counts, timing, and a performance score, while --memory returns one row per page load with peak memory, current memory, memory limit, and percent used.

wp dbtk viewer

The viewer command group installs, removes, and reports on the standalone Viewer App. The Viewer App is a separate installation from the WPDT WordPress plugin, and because it runs independently of WordPress, it remains accessible even when your site displays a fatal error or a white screen.

bash

# Install the Viewer with a password of at least eight characters

wp dbtk viewer setup --password=MySecurePass123

# Confirm the install location and password protection status as JSON

wp dbtk viewer status --format=json

# Remove the Viewer without a confirmation prompt

wp dbtk viewer remove --yes

By default, viewer setup installs to https://yoursite.com/wpdebugtoolkit/. If setup fails with a licensing error, activate a license that includes the Viewer or Database Queries module with wp dbtk license activate <key>.

wp dbtk license

The license command group activates, deactivates, and reports on your WP Debug Toolkit Pro license and the modules it unlocks.

bash

# Activate a license key on a new site

wp dbtk license activate XXXX-XXXX-XXXX-XXXX

# Confirm which modules are licensed before running viewer setup

wp dbtk license status --format=json

# Deactivate the license before transferring it to another site

wp dbtk license deactivate

Frequently Asked Questions

What Output Formats Does wp dbtk Support, and How Do I Get JSON for Scripting?

Most wp dbtk commands support --format=table (the default) and --format=json. The log read and query-log read commands also support --format=csv. wp dbtk api call is the exception: --format=json is currently its only output format, since the command returns the raw response and any profiling data. For scripting, pipe JSON output to jq, for example: wp dbtk log read --since=1h --format=json | jq '.[] | .message'.

What Happens if I Run a wp dbtk Command With an Invalid Flag or Missing Required Argument?

WP-CLI reports the error and does not execute the command. For example, running wp dbtk api show with no route argument prints Usage: wp dbtk api show <route> and exits without making any changes. For an unrecognized flag, WP-CLI reports the flag as invalid before any WPDT code runs. Run wp dbtk api edit --help (or --help after any command) to see its full flag list and required arguments before running it.

Related Documentation

CLI Environment Setup – If any command in this reference returns a database connection error or “command not found,” your terminal environment needs configuration before wp dbtk commands will run.

Profiling Endpoint Performance – Goes deeper on wp dbtk api call --profile and its three profiling modes, with annotated output examples for each.

How to Use WP Debug Toolkit with AI Coding Assistants – Helps you understand how wp dbtk api bootstrap and the annotation commands fit into an AI-assisted development workflow.