WPExecutor — Complete Guide

Requirements

• WordPress 6.0 or later.
• PHP 7.4 or later.
• An Administrator account on a single-site installation, or Network Super Admin on Multisite.
• Either an OpenAI API key or a supported ChatGPT/Codex connection for AI features.

Install the Free version

In WordPress open Plugins → Add Plugin → Upload Plugin, select the WPExecutor ZIP, install it and activate it. The Free version contains the core assistant, controlled execution tools, History and restore support.

Initial setup

1. Open WP Executor → Settings.
2. Choose OpenAI API or ChatGPT account.
3. Review Security, Assistant & Actions, Recovery & Repairs and Database settings.
4. Open the assistant and describe the result you want in normal language.

OpenAI API

Select OpenAI API as the AI provider and enter your API key in WP Executor Settings. API usage and billing belong to the OpenAI account associated with that key.

ChatGPT / Codex

Select the ChatGPT provider and start the built-in authorization flow. Authentication takes place on OpenAI’s website; WPExecutor does not ask you to type your ChatGPT password into WordPress. A separate API key is not required for this connection.

Models and analysis rounds

The selected model is used for the OpenAI API provider. ChatGPT mode can use its own model override when configured. The default maximum analysis depth is 6 rounds and the accepted setting range is 1–10.

When Ask to continue at round limit is enabled, the assistant can ask whether it should continue with another analysis batch instead of silently stopping at the configured limit.

Data sent to the AI provider

When you submit an AI task, WPExecutor may send the prompt and the relevant WordPress context needed for that task. Depending on the enabled tools and the request, this can include page context, bounded file or log excerpts, configuration information and bounded database results.

Who can use WPExecutor

On a normal WordPress site, WPExecutor is available to Administrators. On Multisite, access is restricted to Network Super Admins. You can allow all eligible administrators or select specific administrator accounts.

Controlled execution instead of shell access

The assistant does not receive arbitrary shell access. It works through registered WordPress tools whose inputs are checked by local policies before an operation is executed.

Sensitive information

Protected files, credentials, private keys, certificates, database exports and other restricted data are blocked by the relevant file and data policies. Database value redaction is enabled by default.

Server-side assistant tools

Enable server-side assistant tools is the master switch for the controlled backend tool layer. If it is disabled, the assistant cannot use those registered server-side capabilities.

Auto Actions

Read operations can run when their capability is enabled. A server-side write also requires its specific write permission and Auto Actions for the current assistant session. If Auto Actions is off, a write tool is not authorized to execute.

File reads

The assistant can request bounded excerpts using head, tail, grep or explicit line ranges. This is intended for targeted diagnostics rather than sending entire projects to the AI provider.

Guarded source writes

When file writes are enabled and the session authorizes writes, WPExecutor can replace one bounded contiguous line range in an approved editable file. The write path includes local validation, backup handling, PHP syntax validation where applicable and History integration.

wp-config.php

WPExecutor does not treat wp-config.php as a general editable source file. It exposes a restricted debug configuration profile and can write only whitelisted boolean debug constants when Allow wp-config debug writes is enabled.

Repair controls

Enable guarded repairs and Editable project roots define the repair boundary used by recovery-oriented workflows. The default editable root is WP_CONTENT_DIR.

Database reads

When enabled, the assistant can list tables, inspect table schemas and run bounded read-only queries against the active WordPress database. The default maximum diagnostic result is 100 rows and the configurable upper limit is 500.

Structured writes

Supported database changes use structured insert, update or delete operations with exact matching, before-state verification and rollback information. The default maximum structured change is 100 rows and the configurable upper limit is 1000.

Advanced SQL writes

The Advanced SQL write setting is a separate permission and remains disabled by default. Enable only the database capability required for the current task.

Multisite: full database snapshot and full database restore operations are disabled on Multisite so a site-level recovery action cannot roll back or delete tables belonging to other sites in the network.

Plugin installation

The assistant can install plugins from the official WordPress.org plugin repository when a task requires additional functionality and the operation is permitted.

Guarded updates

Installed plugins with WordPress-recognized updates can be updated when guarded plugin updates are enabled. Before each update WPExecutor creates a protected snapshot of the current plugin files.

Database snapshots before plugin updates are enabled by default when the database is within the configured snapshot size limit. The default limit is 128 MB and the configurable range is 16–2048 MB.

Exact-version repair / reinstall

When local evidence shows that an already-installed WordPress.org plugin has a missing or corrupted code file, WPExecutor can restore the identified file or reinstall the plugin from the official package for the exact currently installed version.

What History contains

• Saved diagnostic runs.
• Applied file and supported database modifications.
• Plugin update records and their protected snapshots.
• Restore points when a supported rollback is still available.

Plugin update restore modes

For guarded plugin updates, History can restore the previous plugin files. When a complete pre-update database snapshot is available, it can also offer a full pre-update restore that returns both the plugin files and the saved WordPress database state.

A restore is not a replacement for an independent site backup. Later changes to the same targets can also make an older restore unsafe or unavailable.

When visual actions are useful

Visual navigation is useful when the task belongs to a plugin or settings screen that has no dedicated backend tool. The assistant can reason about the current screen, select a visible control and continue through a multi-step admin workflow.

Backend tools vs browser actions

WPExecutor can combine both approaches. It may use controlled backend tools for files, configuration, database or plugin maintenance, and use wp-admin interaction for interface-specific steps.

Pro emergency mode intentionally bypasses the normal plugin/theme environment, so ordinary wp-admin browser actions are disabled there. Emergency recovery uses the available backend inspection and repair tools instead.

Annual Pro subscription

A Pro purchase includes access to the Pro build and Pro updates for one year. Renew the annual subscription to continue receiving new Pro updates after that update period.

The Free version remains the base product and can be used without purchasing Pro.

Emergency wp-admin rescue

Rescue Admin is designed for supported fatal-error scenarios where a normal wp-admin request cannot complete. The packaged MU-plugin can redirect a fatal admin request into an isolated recovery request that skips ordinary plugins and the active theme for that request, authenticates with WordPress core and opens the WPExecutor emergency assistant.

The Rescue Admin control requires an existing writable WordPress mu-plugins directory. WPExecutor does not automatically create that target directory.

WP-CLI assistant

Run the same controlled assistant from the command line. Read tools may execute automatically; guarded writes require the relevant WPExecutor permission and --yes for that CLI run.

wp wpexecutor assistant "Show the current WordPress debug settings"
wp wpexecutor assistant "Enable WP_DEBUG and WP_DEBUG_LOG" --yes
wp wpexecutor assistant "Update all installed plugins that have updates" --yes

Diagnosis

The Pro diagnosis command performs bounded multi-round investigation. Use --save-run when the completed diagnosis should become the input for a later repair proposal.

wp wpexecutor diagnose "A checkout save returns a 500 error."
wp wpexecutor diagnose "White screen after update" --format=json
wp wpexecutor diagnose "A checkout save returns a 500 error." --save-run

Repair workflow

A saved completed diagnosis can be turned into a locally validated repair proposal. Pro exposes separate propose, show, apply and rollback steps so the repair lifecycle remains explicit.

wp wpexecutor repair propose <run-id>
wp wpexecutor repair show <repair-id>
wp wpexecutor repair apply <repair-id> --yes
wp wpexecutor repair rollback <repair-id> --yes

CLI output

Assistant and diagnosis commands support table or JSON output where documented. The assistant also accepts a model override and a --max-rounds value in the range 1–10.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, THE DEVELOPER, WTEAM, AUTHORS AND CONTRIBUTORS ARE NOT LIABLE FOR ERRORS, DECISIONS OR ACTIONS PRODUCED OR PERFORMED BY ARTIFICIAL INTELLIGENCE, OR FOR DAMAGE ARISING FROM INCORRECT USER INSTRUCTIONS, PERMISSIONS OR DECISIONS, INCLUDING DATA LOSS, FILE OR DATABASE CORRUPTION, WEBSITE FAILURE, DOWNTIME, SECURITY INCIDENTS, PLUGIN OR THEME CONFLICTS, LOSS OF REVENUE, LOSS OF BUSINESS OR OTHER DIRECT OR INDIRECT DAMAGE.

By enabling or authorizing AI-assisted actions, you acknowledge that these actions involve inherent risk and that you remain responsible for the operation and recovery of the WordPress website on which WPExecutor is used. Nothing in this notice excludes or limits liability that cannot legally be excluded or limited under applicable law.

Recommended operating practice

• Grant only the permissions required for the current task.
• Keep independent, current backups.
• Use staging for high-impact changes where practical.
• Review History and verification results after important actions.
• Do not treat AI output as a substitute for professional review where a change is security-critical, legally sensitive or business-critical.