Royal MCP WP-CLI Commands — Health, Clients, Key Rotation

Before you start

• Requires Royal MCP 1.5.7 or newer. Older versions do not register the royal-mcp command. Confirm with wp plugin get royal-mcp --field=version.
• WP-CLI runs as the site, not as a logged-in user. Run the commands from the WordPress root, or pass --path=/path/to/wordpress from anywhere.
• Multisite: add --url= with the sub-site address so the checks and the client list belong to the right site.
• Standard WP-CLI flags apply. --format, --fields, --field, --user, --yes and --quiet behave exactly as they do on core commands.

wp royal-mcp connection-health

Runs the same four checks as Tools › Site Health (permalinks, discovery document, Authorization header reaching WordPress, sign-in addresses reachable) and adds the plugin's own state: version, endpoint, whether the plugin is switched on, read-only mode, which user the API key acts as, how many OAuth connections are live, and which page builders are detected.

Every row carries a status. good and info need nothing from you. recommended is worth a look. critical means no AI client can use the site until it is fixed, and the command exits with status 1 so a script can stop there.

Options

Checks reported

Example: gate a deployment

Run the check as the last step of a deploy. A critical finding fails the step, so a site never goes live with AI clients locked out.

wp royal-mcp connection-health --format=json --path=/var/www/client-site || exit 1

wp royal-mcp list-clients

Prints one row per AI client and WordPress user that currently holds a live OAuth token: the same rows as Royal MCP › Connected Clients in wp-admin. Use it to answer "who can reach this site through an AI client right now?" without opening the dashboard.

Options

Available fields

Example: export who is connected, across every site

Collect one CSV per site, then open them side by side or feed them to your reporting. The header row is included once per file.

for site in /var/www/*/; do
  wp royal-mcp list-clients --format=csv --fields=client_name,user_login,last_issued --path="$site" \
    > "clients-$(basename "$site").csv"
done

Revoking is still done from the dashboard: Royal MCP › Connected Clients has a Revoke access button on every row and a Revoke all button at the top.

wp royal-mcp rotate-api-key

Replaces the site's API key. The old key stops working immediately, the new key is printed once, and nothing readable is stored afterwards. Rotate on a schedule, after staff changes, or the moment you suspect a key has leaked.

The API key acts as a WordPress user. Pass that user with WP-CLI's own --user flag. Without it, the key stays bound to the user it is bound to now; if no user is bound yet, the command stops and asks for one.

Options

Example: rotate and store the key in one step

The key is printed once. Capture it straight into the place it will live, rather than into a terminal scrollback.

NEW_KEY=$(wp royal-mcp rotate-api-key --user=agency-bot --porcelain --yes --path=/var/www/client-site)
printf '%s' "$NEW_KEY" | your-secrets-tool put client-site/royal-mcp-api-key

Running across many sites

The three commands are built to be looped. Two patterns cover most agency setups.

Morning health sweep

Print only the sites with a problem. --quiet drops the table; the exit code is what you want.

for site in /var/www/*/; do
  wp royal-mcp connection-health --quiet --path="$site" \
    || echo "NEEDS ATTENTION: $(basename "$site")"
done

Quarterly key rotation

Rotate every site in one pass. Keep the user the same across sites so the capability review is done once.

for site in /var/www/*/; do
  wp royal-mcp rotate-api-key --user=agency-bot --porcelain --yes --path="$site" \
    | your-secrets-tool put "$(basename "$site")/royal-mcp-api-key"
done

Exit codes

Related