diagnostic-wpcli-profile

Diagnostic Skill: WP-CLI Profile Integration

You use the wp-cli/profile-command package to measure actual PHP execution time for each WordPress load stage and identify the slowest hooks in the bootstrap stage. This is the most direct way to find which plugins are responsible for slow page loads.

Overview

wp-cli/profile-command is a separately-installable WP-CLI package (not part of WP-CLI core). It instruments the WordPress request lifecycle and measures real execution time, not estimates. It reveals:

• Stage timing — How long each of the three WordPress load stages takes: bootstrap, main_query, and template. These are pipeline stages, not hook names.
  • bootstrap — Covers WordPress initialization: loading plugins, running plugins_loaded, init, wp_loaded, and all plugin init callbacks. This is where most performance problems live.
  • main_query — The primary WP_Query that determines what content to show.
  • template — Theme template loading and rendering.
• Hook timing — Within the bootstrap stage, which specific hooks and callbacks are slowest.

Two stages of gating: WP-CLI must be available first, then wp-cli/profile-command must be installed. Each gate has its own behavior.

Offer before install: This skill NEVER auto-installs wp-cli/profile-command. It asks the user first and respects the answer. This is a locked decision — unexpected package installs on production servers are unacceptable.

Prerequisites

Before running checks, you need:

• Site connection profile from sites.json (loaded by CoWork or /diagnose)
• WP_CLI_PREFIX set by the /diagnose command's Source-Type Routing section
• WP_CLI_AVAILABLE=true (Stage 1 gate)
• wp-cli/profile-command installed on the server (Stage 2 gate — checked at runtime)

---

Stage 1 Gate: WP-CLI Availability

Check WP_CLI_AVAILABLE first. If false, emit two separate skip findings (one per check that would have run) and stop:

if [ "$WP_CLI_AVAILABLE" != "true" ]; then
  echo '[
    {
      "id": "PERF-PROF-STAGE-SKIP",
      "severity": "Info",
      "category": "Performance",
      "title": "Stage profiling skipped — WP-CLI not available",
      "summary": "Stage profiling requires WP-CLI and wp-cli/profile-command to run.",
      "detail": "WP_CLI_AVAILABLE is false for this source type. Cannot check for wp-cli/profile-command without WP-CLI. Stage profiling measures bootstrap, main_query, and template timing — the three pipeline stages of a WordPress page load.",
      "location": "wp profile stage",
      "fix": "Install WP-CLI on the server to enable performance profiling."
    },
    {
      "id": "PERF-PROF-HOOK-SKIP",
      "severity": "Info",
      "category": "Performance",
      "title": "Hook timing skipped — WP-CLI not available",
      "summary": "Hook timing requires WP-CLI and wp-cli/profile-command to run.",
      "detail": "WP_CLI_AVAILABLE is false. Cannot run wp profile stage bootstrap for hook timing. Hook timing identifies the top 5 slowest callbacks in the bootstrap stage, showing which plugins are consuming the most time during WordPress initialization.",
      "location": "wp profile hook",
      "fix": "Install WP-CLI on the server to enable hook timing analysis."
    }
  ]'
  exit 0
fi