WP Debug Toolkit 1.2 Beta 1 is here. It expands the wp dbtk CLI introduced in 1.1.0 so any coding agent can become a WP Debug Toolkit agent without taking you out of your editor, makes query recording safer for production, improves compatibility with proxied environments and restrictive hosting platforms, and adds a handful of workflow polish items on the Overview page.

CLI: profiling, recording, and API discovery from the terminal

WP Debug Toolkit 1.1.0 introduced wp dbtk for license, debug, viewer, and basic log management. 1.2.0 expands it into a full debugging surface with 29 commands across 6 groups, REST API discovery, endpoint profiling, session-based query recording, filtered log reading, and a published agent skill so the same commands you use are also the ones your agent uses.

We’ve had the same principle since v1.0: if you’re debugging, the tools you reach for shouldn’t break your flow. With the CLI surface and the skill, your coding agent can profile a slow endpoint, record a query session before and after a change, or read filtered debug entries without you switching to a browser tab or copy-pasting screenshots back and forth. Everything returns structured JSON you can pipe, diff, or hand to an agent to parse.

You can use --profile on any endpoint call or run wp dbtk api call GET /wp/v2/posts --profile and you get execution time, memory usage, query count, duplicate detection, slow query identification, and per-plugin query attribution in one shot, all of it in natural language with your favorite coding agent, or run them yourself from the terminal. Three profiling modes let you choose the level of detail: --profile=full (the default), --profile=queries, or --profile=summary.

Query recording works from the CLI too. Start a session, go use the site in a browser, then stop and analyze:

wp dbtk query-log start --tag=my-test
# browse the site, test a flow, interact with pages...
wp dbtk query-log stop
wp dbtk query-log read --tag=my-test --summary    # per-page overview with timing, memory, and perf score
wp dbtk query-log read --tag=my-test --memory      # memory usage per page load
wp dbtk query-log read --tag=my-test --component=my-plugin --slow  # your plugin's slow queries

You can also read and filter the debug log from the terminal:

wp dbtk log read --level=error,fatal --since=1h
wp dbtk log read --plugin=my-plugin --format=json

Install the skill with npx skills add WP-Debug-Toolkit/wpdt-cli and your agent can run all of these through natural conversation and use them in vibecoding sessions, where you record before a change, record after, compare, and catch regressions without leaving your editor.

For the full list of commands, flags, and options, see the CLI Command Reference.

API discovery with persistent annotations

wp dbtk api discover scans every registered REST route on the site and writes the structural schema to disk. From there you can list, search, show, and call any endpoint.

Discovery only captures structure: parameter names and types. It won’t tell your agent whether a POST /orders endpoint is safe to call, what role it requires, or what it returns. wp dbtk api edit saves that as a durable annotation per HTTP method: safety, auth, return shape, free-text notes. Annotations live in a separate file, so rediscovery never wipes them.

Three commands turn those annotations into a portable knowledge base:

• wp dbtk api bootstrap --source=<plugin> prints a Markdown brief a fresh agent session can load before it touches anything
• wp dbtk api export --source=<plugin> packages the annotations into a JSON pack
• wp dbtk api import <pack.json> loads a pack on another site, with --mode=merge or --mode=replace-source and --dry-run for preview

On-demand query recording

Query logging in WP Debug Toolkit writes entries to a file so you can share them, read through them, and save them for later. This is by design, but in 1.1.0 the only mode was always-on: you enabled it, and it captured every database query on every page load, which could cause performance issues on high-traffic sites.

1.2.0 keeps the always-on capability for the cases where you want it (wp dbtk query-log on/off, or the developer override in the admin) and layers an on-demand recording model on top. You click Record, set a duration (up to 1 hour), and recording stops automatically when the timer expires.

The recording dialog also lets you generate a shareable URL with a secure token. You can send this to a support tech or client. They open the link, a countdown triggers the recording on their end, and the query log is captured without needing admin access — the recipient never has to log in. Tokens are single-use by default, expire on a schedule you set, and can optionally allow the recipient to download the raw log file directly.

Log entry grouping

When a site throws the same error several times, the log viewer becomes a wall of identical lines. The new Group toggle (press G) collapses duplicate entries by message content, showing a count badge and the timestamp range from first to most recent occurrence.

Proxy and CDN compatibility

Behind load balancers and CDNs, the viewer’s session IP binding could log users out between requests because the apparent client IP kept changing. 1.2.0 adds a “Disable IP Binding” toggle in the viewer’s Viewer Settings tab as well as in the Viewer’s Preferences. It also improves IP detection with support for Cloudflare (CF-Connecting-IP), Akamai (True-Client-IP), and standard forwarded headers checked in that order, validated against the trusted proxy list.

Flywheel hosting support

Flywheel locks wp-config.php at the platform level, not just file permissions, but infrastructure-level enforcement. That means the plugin can’t toggle debug constants like WP_DEBUG automatically. On Flywheel, you enable debugging through the Flywheel dashboard (Advanced tab) instead.

Everything else works normally: the standalone viewer, error log reading, database monitoring, email notifications, crash recovery, log cleanup, and most WP-CLI commands. The plugin detects Flywheel by checking for platform-specific markers and routes the viewer installation to the correct writable directory at /www/ instead of the misleading DOCUMENT_ROOT.

wp-config.php writability diagnostics

A new Site Health check tests whether wp-config.php is writable and, if not, whether temporary permission elevation would work. The check briefly elevates permissions, tests writability, and immediately restores the original permissions. This gives you a clear answer about whether the plugin can manage debug constants on your host, and if it can’t, the error message tells you why.

Security hardening

1.2.0 includes a round of security hardening covering input validation, API response sanitization, CSRF binding, data exposure prevention, and clean resource removal on deactivation and uninstall.

---

Full changelog

Added

• Time-limited query recording with shareable URLs and automatic stop — record queries on demand instead of leaving capture always on
• Group duplicate log entries toggle with count badges in the viewer
• Performance warnings on Overview page when debug mode or query logging is enabled
• Proxy and CDN support — disable IP binding toggle for proxied environments, with Cloudflare and Akamai header detection
• Manage session IP binding from the WordPress admin Viewer Settings tab
• View and clear rate-limited IPs from the WordPress admin Viewer Settings tab
• Flywheel hosting compatibility
• wp-config.php writability diagnostics in Site Health with safe temporary permission elevation
• wp dbtk api command group — discover, list, show, search, call, edit, export, import, and bootstrap REST API endpoints from the terminal
• Semantic annotation layer for wp dbtk api edit — method-level descriptions, safety classification, auth notes, return-shape notes, tags, and verification markers; persisted across discovery rescans
• wp dbtk api export / import for portable annotation packs with merge and replace-source modes
• wp dbtk api bootstrap — generate a Markdown brief of a plugin’s endpoints for fresh agent sessions
• wp dbtk query-log start/stop/status/read commands for recording control and query analysis from the terminal
• wp dbtk log read command for filtered debug log reading from the terminal
• --summary and --memory flags for wp dbtk query-log read — view per-page performance overview and memory usage from recordings
• --profile flag on wp dbtk api call with full, queries, and summary modes
• CLI documentation suite — setup guide, usage guide, command reference, AI assistant guide, REST endpoint profiling guide
• Q keyboard shortcut to open the query recording dialog, with a shortcut badge on the Record button
• Reinstall Viewer action on the Overview page — regenerates viewer files without re-prompting for password; bound to the I shortcut when the viewer is installed
• “Always Logging” warning pill with tooltip on the Database Queries card when SAVEQUERIES or enhanced logging is persistently enabled

Changed

• Lazy-load services — deferred to point-of-use instead of eager init on every request
• Cache health check results for 5 minutes with auto-invalidation on settings change
• Faster admin page loads — cache license API responses and pass initial settings inline to eliminate redundant API calls
• Settings now work on hosts with restrictive file permissions via automatic permission elevation and restore
• Actionable error messages for admin users when settings fail to save
• Replace SAVEQUERIES with filter-based query capture for safer API endpoint profiling

Security

• Harden standalone viewer — add execution guard, expand blocked files list, and add directory listing protection
• Tighten wp-config backup file permissions to 0600
• Strengthen encryption key generation in viewer manager
• Improve HTTPS detection on local domains (.local, Docker)
• Comprehensive security hardening: input validation and sanitization, API response hardening, session and CSRF improvements, data exposure prevention, and cleaner deactivation/uninstall lifecycle

Fixed

• PHP 8.4 deprecation warning for E_STRICT constant in notifications mu-plugin
• Session IP binding failures behind load balancers and CDNs
• Viewer install no longer blocked by read-only wp-config.php
• Graceful degradation when wp-config.php is not writable
• Settings page showing the wrong status for debug, query logging, and other toggles
• File path detection showing empty in Settings when initial page data is used
• Viewer session authentication failing on local HTTP environments
• Viewer password status showing the wrong value on the Settings page
• Viewer settings modal not closing after a successful save
• Viewer theme out of sync between the sidebar toggle and the Settings modal
• Viewer sidebar “Keyboard Shortcuts” button now opens the shortcuts reference
• License activation state not syncing across admin sections without a page reload
• wp dbtk query-log stop no longer disables global query logging when ending a recording session; stats labels clarified to distinguish session totals from log totals