Allow file writes or running PHP

By the end of this page the Write files group, the Run PHP group, or both are switched on, and you know how to switch them off again.

Both groups reach past the theme. Write files creates, overwrites and deletes files anywhere in wp-content, with no backup. Run PHP executes code with WordPress loaded. Theme work does not need either one. The Theme files group edits a theme with backups and undo, and needs no constant.

What each group needs

Write files needs all of these:

the constant BTMCP_ALLOW_FILE_WRITE in wp-config.php
DISALLOW_FILE_EDIT and DISALLOW_FILE_MODS not set
an account with the manage_options and unfiltered_html capabilities, which must be a Super Admin on a multisite network

Run PHP needs all of these:

the constant BTMCP_ALLOW_PHP in wp-config.php
DISALLOW_FILE_EDIT not set
an account with the manage_options and unfiltered_html capabilities, which must be a Super Admin on a multisite network

1. Add the constant

Open wp-config.php on the server and add the line you need above the line that says /* That's all, stop editing! Happy publishing. */:

define( 'BTMCP_ALLOW_FILE_WRITE', true );

define( 'BTMCP_ALLOW_PHP', true );

The value must be the boolean true. 1 or 'true' do not count.

2. Switch the group on

Go to Settings → Block Theme MCP, Settings tab, Tool groups.
Under Beyond the theme, tick Write files or Run PHP.
Click Save Changes.

Before the constant is in place the checkbox is disabled, and the reason is printed under it. For Write files:

File writing requires BTMCP_ALLOW_FILE_WRITE to be defined as true in wp-config.php, DISALLOW_FILE_MODS and DISALLOW_FILE_EDIT must not be enabled, and your account needs the manage_options and unfiltered_html capabilities (Super Admin on multisite).

For Run PHP:

Running PHP requires BTMCP_ALLOW_PHP to be defined as true in wp-config.php, DISALLOW_FILE_EDIT must not be enabled, and your account needs the manage_options and unfiltered_html capabilities (Super Admin on multisite).

If the settings were saved while a group was blocked, the group is stored as off. Adding the constant afterwards does not switch it on by itself. Tick it and save again.

Check that it worked

On the Tools tab, the group’s pill reads On. Ask the agent to call btm.site-info: the result lists the group among the ones that are on. With a file group on, it also lists the folders the file tools may use.

What the file tools can do

btm.files-write creates a file or replaces it completely. Parent folders must exist. btm.files-mkdir creates them.
btm.files-delete and btm.files-delete-directory delete for good. A folder that is not empty needs recursive: true.
Paths are absolute and must be inside wp-content.
One write is at most 2 MB.

Three things are refused even with the group on:

Writing a file the server may execute, such as .php or .htaccess, unless Run PHP is allowed on the site as well. The message is “Writing a file the web server may execute (PHP, .htaccess, .user.ini) requires the PHP tool group to be allowed.”
Anything inside wp-content/block-theme-mcp/, where the plugin keeps theme backups and change sets.
Any path on a server where paths do not start with /. The file tools need Linux or macOS.

To let an agent look at files without changing them, switch on Read files instead. It needs no constant.

What the PHP tool can do

btm.php-execute runs the code it is given, with WordPress, the plugins and the theme loaded. It returns the output, any PHP warnings and errors, and an exit code. Output over 1 MB is cut, and the run has 30 seconds.

Code that calls exit or die, or runs out of memory or time, ends the request, and the agent gets no result.

Switch it off again

Untick the group on the Settings tab and click Save Changes.
Remove the constant from wp-config.php.

Either step alone is enough to stop the tools. Do both when the work is finished.