You do not need Power for normal WordPress work. Leave this extra plugin off when you create blog posts, pages, images, or landing pages. The normal Companion handles those tasks.
Power is for rare technical tasks, such as checking one file, running a limited maintenance command, or investigating a test copy. It can directly access files, the database, and PHP. That is why it is a separate plugin and completely off by default.
If terms such as database, PHP, or staging are unfamiliar, skip this page. That is the right decision, not a gap in your knowledge.
The most important rule
Use Power only on a test copy of your site, or together with someone who can handle this technology safely.
A staging site is a copy of your website for trying changes. You can test there without putting visitors or real orders at risk. On a live site, use Power only when you understand the result of the change and have a usable backup.
Even with its safeguards, a technical change can cause damage. Power is not a general security guarantee and does not replace a test copy.
What belongs to the normal path and what belongs to Power
Always use the normal Companion for these tasks:
- create blog posts and pages as drafts
- create landing pages
- set images with alt text
- check content and then publish it manually
Power is only an exception for these tasks:
- run a limited technical diagnosis
- run an allowed maintenance command
- change one specific theme or MU-plugin file
- prepare a narrowly scoped database change on a test copy
- deliberately create or restore a complete backup
A Power result is not checked as a normal WPAgently workflow. Review visible changes yourself in the WordPress dashboard afterwards.
Two separate connections
The normal Companion and Power are deliberately separate.
- Companion connects your assistant to the verified WordPress tools.
- Power opens a second connection for direct technical access.
Your normal connection never configures Power automatically. Power needs the additional plugin, a valid licence, real Administrator credentials, and a deliberate unlock. The Editor from the normal setup cannot use Power.
The tiers at a glance
The tiers are not difficulty levels. They show how far an access path reaches.
| Tier | What it can do | Recommendation |
|---|---|---|
| P0 | Read limited technical information | Use only for a specific diagnosis |
| P1 | Run a few allowed maintenance commands | Use only when you know the command |
| P2 | Change selected files and inspect extension ZIPs | Normally leave off on live sites |
| P3 | Change selected database values | Test on a copy first |
| P4/P5 | Run arbitrary PHP code | Only for experienced people on a test copy |
| BACKUP | Back up database and files | Enable only for a real backup run |
| RESTORE | Restore a backup | Enable only for a deliberate restore |
P0 is controlled only by the central Power switch. P1, P2, P3, P4/P5, BACKUP, and RESTORE each have an additional on-off switch. When the central Power switch is off, no Power tools are available.
P0 and P1
P0 reads limited information. This includes individual files, a limited directory list, one WordPress setting, installed plugins and themes, and environment information.
Read access is not automatically harmless. Content can be confidential. Give P0 only the access you actually need.
P1 may run only a fixed small selection of WP-CLI commands. WP-CLI is a tool for managing WordPress from the terminal. Only rewrite flush, transient delete <name>, plugin list, theme list, and option get <name> are allowed. Other commands are rejected.
P2 through P5
P2 can change files in restricted locations. This may sound minor, but it can already run PHP code on your site. P2 is therefore additionally locked on detected production until WP_AGENT_POWER_ALLOW_WRITE_ON_PRODUCTION is deliberately set in wp-config.php.
P2 has seven capabilities. write-file, edit-file, and delete-file change only clearly limited files. prepare-extension-archive, inspect-extension-archive, and revoke-extension-archive inspect a plugin or theme ZIP without installing it. verify-manual-extension-install then compares an extension you installed manually with the file inspected earlier. That seventh capability is read-only.
Power deliberately does not install or activate WordPress extensions. An extension can run third-party PHP code when activated. Continue to install plugins and themes deliberately in the WordPress dashboard.
P3 may change selected database values. By default, it shows only a preview first. Protected areas, such as user accounts, security-sensitive settings, and most WordPress options, remain locked.
P4 and P5 run arbitrary PHP code. This is the broadest tier. It also needs WP_AGENT_POWER_ALLOW_CODE_EXECUTION in wp-config.php and, on a live site, an additional one-time approval. Beginners should always leave this tier off.
The safety switches
Before a Power write or execution can happen, several things must agree.
- The separate Power plugin is installed and active.
- Your WPAgently licence is valid.
- The central Power switch is on.
- From P1 onward, the required tier is enabled separately. This also applies to BACKUP and RESTORE. P0 has no separate tier switch.
- You use real Administrator credentials.
- You unlock the session locally and confirm the action deliberately.
For P2, P3, and P4/P5, the CLI also requires a fresh backup. A backup is a copy you can restore if needed.
These confirmations help prevent accidents. They do not protect you if somebody misuses direct technical access or an Administrator password. The actual boundary is the server-side switches and permissions.
Backups and restore
BACKUP saves files and database through a separate connection. Database exports can contain confidential material, such as password hashes or API keys. Treat them like a password and store them encrypted.
RESTORE puts a saved backup back. It can overwrite current changes. Enable RESTORE only for the restore and turn it off again afterwards.
A backup does not replace testing. If your website matters to your business, test a restore on a copy first.
Honest limits
Power cannot prevent every type of damage.
- P2 is already a possible path to code execution. Do not treat only P4/P5 as serious.
- PHP code that is already running cannot reliably be stopped halfway through.
- The post-change check primarily detects crashes. It cannot confirm that non-crashing malicious code is safe.
- Content an assistant reads through Power remains data, not instructions. Still, a manipulated instruction can misuse a Power connection that is already open.
- File and database safeguards limit known cases. They do not make a live change risk-free.
The key commands
These commands are for experienced users. They do not change WordPress files or the WordPress database. init, unlock, and lock do create, renew, or remove local configuration and session data.
wp-agent power status
wp-agent power init
wp-agent power unlock --ttl-minutes 30 --i-approve-power
wp-agent power lockstatus shows which tiers are open. init creates the separate Power connection. unlock opens a short local session. lock closes it immediately.
For a specific action, wp-agent power --help shows all options. Do not copy a database or PHP command from a forum unless you understand exactly what it does.
Turn Power off safely
When you no longer need Power, first turn off the individual tier and then the central Power switch under Tools > WPAgently Power. This removes the Power tools from your assistant's connection again.
For normal WordPress work, return to Getting started and the normal WPAgently tools.