CLI Command Reference

Every wp dbtk command, its options, and a quick example. Run any command with --help for inline WP-CLI documentation.

wp dbtk api

Discover, search, inspect, annotate, export, import, bootstrap, and call WordPress REST API endpoints.

wp dbtk api list

List REST routes from the schema store.

Syntax:

wp dbtk api list [--namespace=<namespace>] [--method=<method>] [--source=<source>] [--annotated-only] [--tag=<tag>] [--format=<format>]

Option	Description
–namespace=	Filter by REST namespace, e.g. wc/v3 or wp/v2
–method=	Filter by HTTP method: GET, POST, PUT, DELETE
–source=	Filter by plugin slug, e.g. woocommerce or wpdebugtoolkit
–annotated-only	Only show routes that have saved annotations
–tag=	Filter by route-level or method-level annotation tag
–format=	Output format: table (default) or json

Shows WPDT endpoints by default. Run wp dbtk api discover first to include all site routes.

Example:

wp dbtk api list --namespace=wc/v3 --method=GET
wp dbtk api list --source=rankmath --annotated-only
wp dbtk api list --tag=mutates-data

wp dbtk api discover

Scan all registered REST routes and save them to the schema store.

Syntax:

wp dbtk api discover

No options. Scans active plugins, themes, and WordPress core. Results are available immediately to list, search, and show.

Example:

wp dbtk api discover
# Success: Discovered 187 routes across 12 sources.

wp dbtk api call

Call any REST endpoint via internal dispatch. No HTTP round-trip — goes through the WordPress REST server directly.

Syntax:

wp dbtk api call <method> <route> [--params=<json>] [--profile[=<mode>]] [--format=<format>]

Argument / Option	Description
	HTTP method: GET, POST, PUT, DELETE
	REST route path, e.g. /wp/v2/posts or /wc/v3/products/42
–params=	JSON object of request parameters
–profile	Enable full profiling (timing, memory, queries, PHP errors)
–profile=full	Same as –profile
–profile=queries	Timing, memory, and query analysis only
–profile=summary	Timing, memory, and total query count only
–format=	Output format: json (only option currently)

Authentication uses the current WP-CLI user. Pass --user=<id> to the wp command to authenticate as a specific user.

Query analysis is captured through a request-scoped filter, so it works regardless of how SAVEQUERIES is defined at WP-CLI bootstrap.

Examples:

wp dbtk api call GET /wp/v2/posts --params='{"per_page":5}'
wp dbtk api call POST /wpdebugtoolkit/v1/query-logger/record --params='{"duration":60}'
wp dbtk api call GET /wc/v3/products --profile
wp dbtk api call GET /wc/v3/products --profile=queries

wp dbtk api show

Show full detail for a specific REST route: methods, parameters, auth, description, and any saved annotations.

Syntax:

wp dbtk api show <route> [--method=<method>] [--format=<format>]

Argument / Option	Description
	REST route path, e.g. /wc/v3/products
–method=	Show details for a specific HTTP method only (e.g. POST). Omit to show all methods.
–format=	Output format: table (default) or json

Example:

wp dbtk api show /wc/v3/products
wp dbtk api show /wc/v3/products --method=POST
wp dbtk api show /wpdebugtoolkit/v1/settings --format=json

wp dbtk api search

Search routes by keyword across route paths, descriptions, and parameter names.

Syntax:

wp dbtk api search <keyword> [--source=<source>] [--annotated-only] [--format=<format>]

Argument / Option	Description
	Search term
–source=	Filter results by source plugin slug
–annotated-only	Only show results with annotations
–format=	Output format: table (default) or json

Example:

wp dbtk api search "product"
wp dbtk api search "order" --source=woocommerce --annotated-only
wp dbtk api search "debug" --format=json

wp dbtk api edit

Annotate an endpoint with semantic metadata. Annotations are stored separately from the discovered schema, so they persist across discover runs and appear in list, show, search, and bootstrap output.

Annotations can be route-level (apply to all methods) or method-level (specific to one HTTP method via --method). Provide at least one annotation field per call. Pass an empty string to clear a field.

Syntax:

wp dbtk api edit <route> [--method=<method>] [--description=<text>] [--purpose=<text>] [--safety=<level>] [--auth-note=<text>] [--returns=<text>] [--example-params=<json>] [--tag=<tags>] [--verification=<state>]

Argument / Option	Description
	REST route path to annotate
–method=	HTTP method for method-level annotation (e.g. POST). Omit for route-level.
–description=	Summary description of the endpoint
–purpose=	When and why to use this endpoint
–safety=	Safety level: read-only, mutates-data, destructive, unknown
–auth-note=	Authentication/authorization notes (e.g. required role)
–returns=	Summary of what the endpoint returns
–example-params=	Example parameters as a JSON object
–tag=	Comma-separated tags
–verification=	Verification state: inferred, verified-source, verified-runtime, verified-docs

Examples:

# 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
wp dbtk api edit /wc/v3/orders --tag=orders,wc

# Clear a field
wp dbtk api edit /wc/v3/orders --description="" --safety=""

wp dbtk api export

Export annotations for a single source as a portable JSON pack. Packs can be checked into version control, shared with a team, or imported on another site.

Syntax:

wp dbtk api export [--source=<slug>] [--namespace=<namespace>] [--template] [--annotated-only] [--format=<format>]

Option	Description
–source=	Source plugin slug to export (e.g. woocommerce). Required if –namespace is omitted.
–namespace=	REST namespace to identify the source (e.g. wc/v3). Required if –source is omitted.
–template	Export with empty semantic fields, ready to be filled in by a human or AI agent
–annotated-only	Only include routes that already have annotations
–format=	Output format: json (only option currently)

Examples:

wp dbtk api export --source=woocommerce --annotated-only > woocommerce-annotations.json
wp dbtk api export --source=rankmath --template > rankmath-template.json
wp dbtk api export --namespace=wpdebugtoolkit/v1

wp dbtk api import

Load an annotation pack into the local schema store. Supports merging into existing annotations or replacing all annotations for the pack’s source.

Syntax:

wp dbtk api import <file> [--mode=<mode>] [--dry-run]

Argument / Option	Description
	Path to the JSON pack file produced by wp dbtk api export
–mode=	merge (default) or replace-source
–dry-run	Validate and report what would change without writing

Examples:

wp dbtk api import woocommerce-annotations.json --dry-run
wp dbtk api import woocommerce-annotations.json
wp dbtk api import woocommerce-annotations.json --mode=replace-source

wp dbtk api bootstrap

Generate a compact API brief for a single plugin source, optimized for loading into a fresh AI agent session before any other API work. The Markdown format is designed to be pasted into a chat, attached to a system prompt, or piped into a file the agent reads at startup.

Syntax:

wp dbtk api bootstrap [--source=<slug>] [--namespace=<namespace>] [--annotated-only] [--max-routes=<n>] [--format=<format>]

Option	Description
–source=	Source plugin slug. Required if –namespace is omitted.
–namespace=	REST namespace to identify the source. Required if –source is omitted.
–annotated-only	Only include routes with annotations
–max-routes=	Maximum number of routes to include
–format=	Output format: markdown (default) or json

The brief includes the namespace, route counts, safety-level distribution, and per-route summaries with method-level annotations.

Examples:

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

wp dbtk debug

Manage WordPress debug settings (WP_DEBUG, WP_DEBUG_LOG, WP_DEBUG_DISPLAY).

wp dbtk debug on

Enable WordPress debugging.

Syntax:

wp dbtk debug on [--display]

Option	Description
–display	Also enable WP_DEBUG_DISPLAY (shows errors on screen)

Sets WP_DEBUG = true and WP_DEBUG_LOG = true in wp-config.php.

Example:

wp dbtk debug on
wp dbtk debug on --display

wp dbtk debug off

Disable WordPress debugging.

Syntax:

wp dbtk debug off

Sets WP_DEBUG, WP_DEBUG_LOG, and WP_DEBUG_DISPLAY all to false.

Example:

wp dbtk debug off

wp dbtk debug status

Show current debug settings.

Syntax:

wp dbtk debug status [--format=<format>]

Option	Description
–format=	Output format: table (default) or json

Shows WP_DEBUG, WP_DEBUG_LOG, WP_DEBUG_DISPLAY, SAVEQUERIES, enhanced logging status, and log path.

Example:

wp dbtk debug status
wp dbtk debug status --format=json

wp dbtk log

Manage the WordPress debug log (debug.log).

wp dbtk log clear

Clear the debug.log file.

Syntax:

wp dbtk log clear [--yes]

Option	Description
–yes	Skip confirmation prompt

Example:

wp dbtk log clear
wp dbtk log clear --yes

wp dbtk log stats

Show debug log file statistics.

Syntax:

wp dbtk log stats [--format=<format>]

Option	Description
–format=	Output format: table (default) or json

Shows path, existence, file size, and last modified time.

Example:

wp dbtk log stats

wp dbtk log read

Read and filter debug log entries.

Syntax:

wp dbtk log read [--level=<level>] [--source=<source>] [--plugin=<plugin>] [--theme=<theme>] [--since=<timespan>] [--search=<terms>] [--limit=<number>] [--format=<format>]

Option	Description
–level=	Filter by error level: fatal, error, warning, notice, parse, deprecated (comma-separated)
–source=	Filter by source: core, plugin, theme, custom
–plugin=	Filter by plugin slug
–theme=	Filter by theme slug
–since=	Time window: 1m, 5m, 15m, 30m, 1h, 6h, 24h, 7d
–search=	Search terms with +include and -exclude operators
–limit=	Maximum entries to return. Default: 100
–format=	Output format: table (default), json, or csv

Examples:

wp dbtk log read --level=error,fatal --plugin=woocommerce
wp dbtk log read --since=5m --format=json

wp dbtk query-log

Manage database query logging and recording sessions.

wp dbtk query-log on

Install the db.php drop-in and enable always-on query capture.

Syntax:

wp dbtk query-log on

Example:

wp dbtk query-log on

wp dbtk query-log off

Disable always-on query capture and remove the db.php drop-in.

Syntax:

wp dbtk query-log off

Example:

wp dbtk query-log off

wp dbtk query-log clear

Clear query log files.

Syntax:

wp dbtk query-log clear [--all] [--yes]

Option	Description
–all	Clear all rotated query log files, not just the current one
–yes	Skip confirmation prompt

Example:

wp dbtk query-log clear
wp dbtk query-log clear --all --yes

wp dbtk query-log stats

Show query logging statistics.

Syntax:

wp dbtk query-log stats [--format=<format>]

Option	Description
–format=	Output format: table (default) or json

Shows enabled status, slow query threshold, log path, log size, and total entries.

Example:

wp dbtk query-log stats
wp dbtk query-log stats --format=json

wp dbtk query-log start

Start a query recording session. All database queries are captured until the recording is stopped or the duration expires.

Syntax:

wp dbtk query-log start [--duration=<seconds>] [--tag=<label>]

Option	Description
–duration=	Recording duration in seconds. Default: 0 (until stopped). Maximum: 3600 (1 hour)
–tag=	Label for the recording session

If no duration is specified, the recording runs until explicitly stopped with wp dbtk query-log stop. Recordings auto-stop after 1 hour as a safety ceiling.

Examples:

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

wp dbtk query-log stop

Stop the active query recording session.

Syntax:

wp dbtk query-log stop

Example:

wp dbtk query-log stop

wp dbtk query-log status

Show the current recording session state.

Syntax:

wp dbtk query-log status

Shows whether a recording is active or inactive, and the remaining time if a duration was set.

Example:

wp dbtk query-log status

wp dbtk query-log read

Read and filter query log entries.

Syntax:

wp dbtk query-log read [--tag=<label>] [--component=<component>] [--type=<type>] [--slow] [--duplicates] [--errors] [--summary] [--memory] [--since=<timespan>] [--search=<terms>] [--limit=<number>] [--format=<format>]

Option	Description
–tag=	Filter by recording session tag
–component=	Filter by component (plugin slug, theme, or core)
–type=	Filter by SQL statement type: SELECT, INSERT, UPDATE, DELETE
–slow	Show only slow queries
–duplicates	Show only duplicate/N+1 queries
–errors	Show only queries that produced errors
–summary	Show per-page summary instead of individual queries. Each row shows URL, query count, slow queries, duplicate groups, generation time, peak memory, memory %, and performance score
–memory	Show only memory usage per page load. Each row shows URL, peak MB, current MB, limit MB, % used, and a high-memory flag
–since=	Time window: 1m, 5m, 15m, 30m, 1h, 6h, 24h, 7d
–search=	Search terms with +include and -exclude operators
–limit=	Maximum entries to return. Default: 100
–format=	Output format: table (default), json, or csv

Examples:

wp dbtk query-log read --tag=my-recording --slow
wp dbtk query-log read --component=woocommerce --type=SELECT --format=json
wp dbtk query-log read --tag=my-recording --summary
wp dbtk query-log read --tag=my-recording --memory

wp dbtk viewer

Manage the standalone log viewer.

wp dbtk viewer setup

Install the standalone log viewer into the web root.

Syntax:

wp dbtk viewer setup --password=<password>

Option	Description
–password=	Password for viewer authentication (required, minimum 8 characters)

Requires an active license with the Viewer or Query Monitor module. The viewer is installed at https://yoursite.com/wpdebugtoolkit/ by default.

Example:

wp dbtk viewer setup --password=MySecurePass123

wp dbtk viewer remove

Remove the standalone log viewer.

Syntax:

wp dbtk viewer remove [--yes]

Option	Description
–yes	Skip confirmation prompt

Example:

wp dbtk viewer remove
wp dbtk viewer remove --yes

wp dbtk viewer status

Show viewer installation status.

Syntax:

wp dbtk viewer status [--format=<format>]

Option	Description
–format=	Output format: table (default) or json

Shows whether the viewer is installed, the URL directory, password protection status, and full URL.

Example:

wp dbtk viewer status

wp dbtk license

Manage the WP Debug Toolkit Pro license.

wp dbtk license activate

Activate a license key.

Syntax:

wp dbtk license activate <key>

Argument	Description
	The license key to activate

Example:

wp dbtk license activate XXXX-XXXX-XXXX-XXXX
# Success: License activated. Tier: Pro. Modules: viewer, query, email.

wp dbtk license deactivate

Deactivate the current license.

Syntax:

wp dbtk license deactivate

Example:

wp dbtk license deactivate

wp dbtk license status

Show current license status.

Syntax:

wp dbtk license status [--format=<format>]

Option	Description
–format=	Output format: table (default) or json

Shows status, tier, plan name, expiry date, and licensed modules.

Example:

wp dbtk license status
wp dbtk license status --format=json