> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxicore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Enable and restrict WP-CLI access for AI agents in Maxi

> Control which WP-CLI commands AI agents can run. Read-only commands are always permitted; write groups and DB access require explicit opt-in via wp-config.php.

Maxi AI Core exposes the `maxi/run-wp-cli` ability (Pro, requires `manage_options`) so AI agents can run WP-CLI commands against your WordPress site. To keep your site safe, the ability uses a strict allowlist: read-only commands are always permitted, and write commands are blocked by default until you explicitly enable each group in `wp-config.php`.

<Note>
  `maxi/run-wp-cli` requires a Pro license and a WordPress user with the `manage_options` capability. Agents authenticated as lower-privilege users cannot call this ability.
</Note>

## Read-only commands (always permitted)

The following command prefixes — and others like them — are allowed without any configuration:

* `option get`
* `post list`
* `core version`
* `wc tool list`
* `wc log read`
* `plugin list`
* `theme list`
* `user list`
* `db size`

You do not need to define any constants to use these commands.

## Enabling write groups

Write commands are blocked by default. To enable a group, add the corresponding constant to your `wp-config.php` file above the `/* That's all, stop editing! */` line.

```php theme={null}
define( 'MAXI_AI_WP_CLI_ALLOW_CACHE_WRITES', true );    // cache, transient, cron flush
define( 'MAXI_AI_WP_CLI_ALLOW_CONTENT_WRITES', true );  // post, term, menu writes
define( 'MAXI_AI_WP_CLI_ALLOW_USER_WRITES', true );      // user create/update
define( 'MAXI_AI_WP_CLI_ALLOW_OPTION_WRITES', true );    // option add/update/delete
define( 'MAXI_AI_WP_CLI_ALLOW_DB_READS', true );         // SELECT-only db query + db export
```

Only define the constants for the write groups your agents actually need. Each group is independent — enabling one does not affect the others.

<Tip>
  Assign agents to dedicated WordPress users with `manage_options` only when the agent genuinely needs write access. A read-only agent should use a more restricted WordPress role.
</Tip>

## DB query access

When you enable `MAXI_AI_WP_CLI_ALLOW_DB_READS`, agents can run `db query` with SELECT statements and `db export` to back up the database. Non-SELECT queries (INSERT, UPDATE, DELETE, DROP) are rejected even with this constant set.

### DB query blocklist

The DB query blocklist adds a second safety layer on top of the SELECT-only restriction. On first use, the plugin automatically seeds the blocklist with defaults. To find out which ones, ask the agent.

Every `db query` call is checked twice against this list:

1. **Pre-execution** — if the SQL text contains a blocked term (for example, `SELECT secret_key FROM wp_options`), the query is rejected before it runs.
2. **Post-execution** — if the query output contains a blocked term (for example, a `SELECT *` result that includes a `user_pass` column), the output is rejected and not returned to the agent.

Both rejection types are recorded in the audit log under category `wp_cli`.

You can manage the blocklist via the `maxi/manage-db-query-blocklist` ability:

```json theme={null}
{ "action": "list" }
```

```json theme={null}
{ "action": "add", "term": "secret_key" }
```

```json theme={null}
{ "action": "remove", "term": "session_tokens" }
```

<Warning>
  If you clear the blocklist manually, the default terms are not re-added automatically — your choice is preserved. Only remove terms from the blocklist when you have a deliberate reason to do so.
</Warning>

## Hard-banned commands

Certain commands are always rejected, regardless of which constants you define. No constant can enable them:

* Commands containing shell metacharacters — the ability accepts WP-CLI command text only, not shell command text.
* Destructive or sensitive commands such as `db drop`, `eval`, `config set`, and `user delete`.

Rejections are audit-logged under category `wp_cli` with the reason, the matched prefix, and the raw command.

## Example ability call

```json theme={null}
{
  "ability": "maxi/run-wp-cli",
  "command": "option get siteurl"
}
```

The `command` value is a WP-CLI command string without the leading `wp`. Shell metacharacters are rejected before execution — only WP-CLI command text is accepted, not shell commands.

## Security recommendations

<AccordionGroup>
  <Accordion title="Enable only the groups you need">
    Each write group grants access to a meaningful set of commands. Enable `MAXI_AI_WP_CLI_ALLOW_OPTION_WRITES` only if your agent workflow genuinely requires adding or changing site options. The same principle applies to every group.
  </Accordion>

  <Accordion title="Use dedicated WordPress users for agents">
    Assign each AI agent its own WordPress user. If an agent does not need write access, assign it a role without `manage_options`. The `maxi/run-wp-cli` ability is blocked for those agents at the capability level.
  </Accordion>

  <Accordion title="Review the audit log">
    All WP-CLI calls — including blocked and rejected ones — are recorded in the audit log. Query them with `maxi/get-audit-events` using `category: "wp_cli"` to review what commands your agents have attempted.
  </Accordion>

  <Accordion title="Test on staging first">
    WP-CLI write commands execute immediately. There is no dry-run mode. Test any new write group on a staging site before enabling it in production.
  </Accordion>
</AccordionGroup>