# WP-CLI commands

Every wp bettershield command in BetterShield 1.1.0, with its options and an example: audit, findings, hardening, activity, recovery, files and settings.

BetterShield adds eleven `wp bettershield` commands to WP-CLI. They use the same code as the dashboard, and changes are logged as coming through WP-CLI.

> **Note:** A command that changes the site needs `--user=<login>`, naming an account that can manage BetterShield; the change is recorded against it. Reading needs no user, and `recover` never asks for one.

The eleven commands:

- [`audit`](#wp-bettershield-audit): the score, grade and open findings.
- [`findings`](#wp-bettershield-findings): findings from the last audit.
- [`harden`](#wp-bettershield-harden): list, preview, apply or undo a hardening fix.
- [`activity`](#wp-bettershield-activity): the activity log.
- [`agents`](#wp-bettershield-agents): every ability call on the site.
- [`verify_log`](#wp-bettershield-verify_log): the activity log against its daily seals.
- [`recover`](#wp-bettershield-recover): safe mode, from the terminal.
- [`integrity`](#wp-bettershield-integrity): core and plugin files against the published copies.
- [`settings`](#wp-bettershield-settings): export or import BetterShield's settings.
- [`vulnerabilities`](#wp-bettershield-vulnerabilities): the vulnerability check's state. No data source is connected in 1.1.0.
- [`diagnostics`](#wp-bettershield-diagnostics): a block for reporting a problem.

## Audit and findings

### `wp bettershield audit`

Runs the read-only audit and prints the score, grade and open findings by severity.

| Option | What it does | Default |
|---|---|---|
| `--format=<format>` | `summary` or `json`. | `summary` |
| `--fail-under=<score>` | Exit non-zero when the score is below this whole number, 0 to 100. | None |
| `--fail-on=<severity>` | Exit non-zero when an open finding is at this severity or worse: `critical`, `high`, `medium` or `low`. | None |

```
wp bettershield audit --fail-under=80 --fail-on=high
```

### `wp bettershield findings`

Lists findings from the last audit, with the ID of the fix where there is one.

| Option | What it does | Default |
|---|---|---|
| `--status=<status>` | `open`, `snoozed`, `suppressed`, `fixed` or `all`. | `open` |
| `--format=<format>` | `table`, `json`, `csv` or `count`. | `table` |

```
wp bettershield findings --status=snoozed
```

## Hardening

### `wp bettershield harden`

Lists the hardening fixes, or previews, applies or undoes one.

| Option | What it does | Default |
|---|---|---|
| `[<item>]` | The fix's ID. Leave it out to list every fix with its ID and state. | List |
| `--dry-run` | Describe what applying would do, changing nothing. | None |
| `--undo` | Revert the fix. | None |
| `--force` | Apply a sign-in fix even though the recovery check failed. Recorded in the activity log. | None |
| `--<field>=<value>` | An option the fix takes, such as `--slug=<address>` for `login_url`. | None |
| `--format=<format>` | For the list: `table`, `json` or `csv`. | `table` |

```
wp bettershield harden login_url --slug=side-door --user=admin
wp bettershield harden xmlrpc --undo --user=admin
```

## Activity

### `wp bettershield activity`

Shows the activity log, newest first.

| Option | What it does | Default |
|---|---|---|
| `--limit=<number>` | How many entries, at most 500. | 40 |
| `--area=<area>` | `access`, `exposure`, `server`, `configuration`, `extensions` or `plugin`. | All |
| `--search=<text>` | Match who did it, what it was done to, or the event name. | None |
| `--actor=<token>` | `user:<id>`, `type:system` or `type:anonymous`. | None |
| `--from=<date>`, `--to=<date>` | Day range as YYYY-MM-DD, in the site's time zone. | None |
| `--sites=<ids>` | Multisite only: comma-separated site IDs, or `all`. | This site |
| `--format=<format>` | `table`, `json` or `csv`. CSV exports every matching row. | `table` |

```
wp bettershield activity --from=2026-08-01 --to=2026-08-15 --format=csv > august.csv
```

### `wp bettershield agents`

Shows every ability call on the site, from any plugin, newest first. Needs WordPress 7.1.

| Option | What it does | Default |
|---|---|---|
| `--limit=<number>` | How many entries, at most 200. Not used for CSV. | 40 |
| `--outcome=<outcome>` | `completed`, `permission_denied`, `input_invalid`, `input_not_normalizable`, `output_invalid`, `short_circuited`, `failed` or `unknown`. | All |
| `--ability=<name>` | One ability, by exact name. | None |
| `--namespace=<prefix>` | The ability name's namespace prefix. | None |
| `--entry-path=<path>` | How the call came in: `rest`, `wp-cli`, `php`, or `mcp` for an assistant. | None |
| `--format=<format>` | `table`, `json` or `csv` (every matching row). | `table` |

```
wp bettershield agents --outcome=permission_denied
```

### `wp bettershield verify_log`

Checks the activity log against its daily seals and exits non-zero if a sealed day was altered, removed or could not be read. Seals are written once a day, for finished days.

```
wp bettershield verify_log
```

## Recovery

### `wp bettershield recover`

Turns on safe mode: every protection pauses and the standard sign-in page answers again. No setting is lost.

| Option | What it does | Default |
|---|---|---|
| `--hours=<hours>` | How long, 1 to 24. | 1 |
| `--end` | End safe mode now and re-arm every protection. | None |
| `--new-link` | Also issue a fresh recovery link and print it once. The previous link stops working. | None |

```
wp bettershield recover --hours=4 --new-link
```

## Files

### `wp bettershield integrity`

Compares core and directory-plugin files against the published copies. The first argument is the action.

| Action | What it does | Needs a user |
|---|---|---|
| `status` (default) | When the check last ran, and the files that differ. | No |
| `scan` | Runs the check now. | No |
| `restore --id=<change>` | Puts the published copy back. The current file goes to quarantine, and an undo token is printed. | Yes |
| `suppress --id=<change>` | Marks a change expected, with an undo token. | Yes |
| `unsuppress --id=<change>` | Reports a marked change again. | Yes |
| `undo --token=<undo>` | Reverses a restore or a marking. | Yes |
| `recheck --slug=<folder>` | Compares a plugin's open changes against its published version again. | Yes |
| `expect --slug=<folder> --version=<version>` | Shows a plugin's or theme's group of changes (`--type=theme` for a theme). Add `--yes` to mark them expected together. | With `--yes` |

Other options: `--format=table` or `json`; `--fail-on-changes` exits non-zero when any file differs; `--strict` with it also fails when something could not be checked.

```
wp bettershield integrity restore --id=12 --user=admin
```

## Settings

### `wp bettershield settings`

Exports BetterShield's settings as JSON, or imports a settings document. An import only shows its plan until you add `--apply`.

| Option | What it does | Default |
|---|---|---|
| `<action>` | `export` or `import`. | None |
| `[<file>]` or `--file=<path>` | The document to write or read. With neither, export prints to the terminal. | None |
| `--apply` | For import, make the changes. | Plan only |

```
wp bettershield settings export posture.json
wp bettershield settings import posture.json --apply --user=admin
```

## Other commands

### `wp bettershield vulnerabilities`

Shows the vulnerability check's state; `check` runs it now. In 1.1.0 no data source is connected, so it reports that nothing was checked.

| Option | What it does | Default |
|---|---|---|
| `[<action>]` | `status` or `check`. | `status` |
| `--format=<format>` | `table` or `json`. | `table` |
| `--fail-on=<severity>` | Exit non-zero when an installed component is named by an advisory at this severity or worse. | None |
| `--strict` | With `--fail-on`, also exit non-zero when nothing could be checked. | None |

```
wp bettershield vulnerabilities
```

### `wp bettershield diagnostics`

Prints a block for reporting a problem: how BetterShield is set up, with nothing that identifies the site or anyone on it.

```
wp bettershield diagnostics
```

## Related

- [Score and findings](/docs/score-and-findings/)
- [Hardening](/docs/hardening/)
- [Locked out](/docs/locked-out/)
- [Connect an AI assistant](/docs/connect-an-ai-assistant/)
- [Support](/support/)