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:

• Add reusable AGENTS.md config .github#163

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.
  • Add unified diff output to failed Behat comparisons wp-cli-tests#280

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 (like wp cli cmd-dump / wp cli param-dump but 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.

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.txt on the website.

Scaffolding

• Create AGENTS.md when scaffolding a new WP plugin or WP-CLI package.
• Provide scaffold templates as skills.

Safety Guardrails

• Expand --dry-run to every destructive command
• Mask sensitive data in output
  • Mask sensitive argument values in --prompt output #6145
• 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.