Repository navigation
WP-CLI in an agentic development world #6161
Description
In a world where developers increasingly use tools such as Claude Code and Gemini CLI, WP-CLI is in a prime position to evolve from a human-centric tool to a machine-interpretable interface.
I'm opening this issue to discuss how WP-CLI could be optimized for such use cases.
Related:
Some examples:
Machine-readable output
- Detect whether tool is invoked by an AI tool and optimize output messages to be more machine-readable
- Make some texts less verbose, others perhaps more so.
- Generally be mindful of tokens
- Automatically choose the most suitable, structured output formats (
--format=). - Detect common environment variables used by these tools so we know whether WP-CLI is invoked by them
- Token Economy via Diffs: When an AI asks to make some changes, return what's changed and not just "Generated" or so. For an agent, returning a unified diff of what changed allows the agent to verify its work without re-reading a file or making another request, saving massive amounts of tokens.
- Structured Error Recovery
- Where applicable, provide additional context (aka resolution hints), such as commands to fix errors, or links to documentation.
- For example, error output could be JSON objects such as
{ "error": "some_error": "message": "...", "suggested_fix": "Use xyz instead", "documentation_link": "https://..." }
- More machine-readable results when running linters and tests.
Introspection & Schema Discovery
Related to the above: Current agents hallucinate arguments because they guess based on the command name. wp help is formatted for human eyes (man pages).
- Add a JSON schema output format for
wp help.- Could even be a separate command, e.g.
wp cli schema --format=json(likewp cli cmd-dump/wp cli param-dumpbut more comprehensive) - This would dump the OpenAPI or JSON Schema definition of every available command, argument, and flag (or even env vars). An MCP server could digest this on startup to tell the AI exactly what is possible, strictly typed.
- Could even be a separate command, e.g.
MCP integration
- Originally explored in https://github.com/mcp-wp/ai-command/, there is also https://github.com/WordPress/mcp-adapter
- WP-CLI could offer a stdio MCP proxy for local WordPress, so agents don't have to go through HTTP
- Other than existing MCP proxies it wouldn't have to worry about authentication. It would just work.
- There might even be a WP-CLI-specific MCP server that runs without WordPress itself, exposing WP-CLI-specific tools or context
- When exposing WP-CLI commands as tools, input/output schema and meta information (idempotent, etc.) could be added.
Plugins and extensions
- Develop custom plugins/extensions and skills for Claude Code and Gemini CLI, leveraging the above enhancements to improve experience working with WP-CLI (providing schemas, etc.)
Documentation
- There are various aspects to this, from better inline documentation to output (see above) to providing
llms.txton the website.
Scaffolding
- Create
AGENTS.mdwhen scaffolding a new WP plugin or WP-CLI package. - Provide scaffold templates as skills.
Safety Guardrails
- Expand
--dry-runto every destructive command - Mask sensitive data in output
- Contextual Limits: limit number of returned rows by default to prevent an AI from accidentally requesting a dump of 50,000 users, which would overflow its context window (and cost $$$)
Evals
An eval suite for WP-CLI would help identify gaps and verify that any enhancements help close those gaps.
Reacted by Iqbal Hossain, Joe Johnson, Sören Wünsch, Chris Huber, Ruud Laan, Weston Ruter and Pedro de Carvalho
Activity
wp user listnot paginated by default entity-command#616 as a duplicate of this issueswissspidy commentedon Aug 10, 2026
This part is brittle as there's no universal standard for this.
swissspidy commentedon Aug 11, 2026
Some updates after thinking this through further. The scope has narrowed a lot, so I want to record what I'm ruling out and why, to save others the trouble.
A filter that helped: only ship agent-facing improvements that a human at a terminal also benefits from. Most of the original list doesn't survive it.
Ruling out:
wp cli schema—wp cli cmd-dumpalready answers "what commands exist in this install", andwp helpconveys parameter detail in a form models handle well. The increment doesn't justify a new public interface.@destructive/@readonlyannotations — the consumers would have been MCP and the schema. Without them it's metadata with no reader and no way to test its accuracy. It also can't classifywp db queryorwp eval, which are the risky ones.--dry-runeverywhere — agents don't need it; permission is gated at the harness/user level, not by the tool. It's a feature for cautious humans and should be justified as one.AGENTS.mdscaffolding — less relevant than when I opened this.What I do want to pursue:
1. A skill capturing WP-CLI conventions models don't reliably know: pagination differences between commands,
--porcelain,--format=countbefore dumping JSON, preferring real commands overwp db query,--skip-plugins/--skip-themeswhen diagnosing. Costs nothing in core, and writing it doubles as requirements discovery — whichever workarounds are most awkward to write down point at what core is actually missing.2. Evals, possibly as a public leaderboard. Two design points: grade on resulting WordPress state rather than the command string, and let the agent run a real multi-command loop so we're measuring how it recovers from our error messages. Harbor (the harness behind Terminal-Bench 2.0) looks like a plausible fit — it drives Claude Code/Codex/OpenHands directly and supports custom datasets. Run two arms: without the skill (that's the model benchmark) and with it. The delta is the interesting number — tasks the skill fixes were doc gaps, tasks it doesn't are where WP-CLI itself needs work. The task set is the durable asset here; harnesses will churn.
3. Diffs on write — smaller than I originally framed it. It's really just better output, e.g.
wp config setshowing old → new. No dry-run machinery and no diff library needed for the simple cases.Masking sensitive data (#6145) already landed and fits the filter.
Make the test runners quieter for non-interactive consumers
Cache the WP_VERSION lookups performed by the Behat runner
Add a Gherkin linter to the test suite
Move the Gherkin linter pin into package.json
Address review feedback on the Behat runner
Harden the WP_VERSION cache against typos, hangs and concurrent runs