WP-CLI Recovery and Maintenance

WP-CLI commands run from a trusted server operator context. They do not use browser nonces because they are not browser requests. Use them only from an account and server session authorized to administer the WordPress install.

Disable a custom login path when administrators cannot reach the login form:

wp awthy login-path disable

You can also define AWTHY_DISABLE_LOGIN_PATH in wp-config.php for recovery.

IP access recovery

Disable IP access rules when a rule blocks legitimate login or admin access:

wp awthy ip disable

Review the rule set before enabling enforcement again.

Incident unlock

Clear an active incident lockdown from the server:

wp awthy incident unlock

Use this only after confirming the incident response state and preserving any audit evidence needed for review.

User reset

Reset second-factor access for a user when the support workflow has verified ownership:

wp awthy reset-user <user-id> --reason=support_recovery

Do not use this as a shortcut around account ownership checks.

Key rotation

Rotate the Awthy encryption key only through the supported command:

wp awthy rotate-key --dry-run
wp awthy rotate-key

Run the dry run first. The command rotates authenticator secrets and supported threat-scan cursors in bounded batches. Do not remove AWTHY_ENCRYPTION_KEY_PREVIOUS until a dry run reports no stale encrypted rows in any category. Do not replace AWTHY_ENCRYPTION_KEY manually while encrypted data exists unless you are following the rotation procedure.

Audit commands

Read and export display-safe audit rows:

wp awthy audit list --search="failed login" --severity=warning
wp awthy audit export --format=json --file=awthy-audit.json

Audit exports should still follow the same safe-data boundaries as browser downloads.

File-integrity commands

Inspect a redacted file-integrity diff by change UUID:

wp awthy file-integrity diff <change-uuid> --format=json

Use JSON only when you deliberately need the redacted diff body. Table output omits it.

Complete backup capture

Full file capture uses the bundled Linux native reader. It does not require configuring remediation write access.

Queue a manual backup, then advance its existing durable work in bounded steps:

wp awthy recovery capture start
wp awthy recovery capture continue
wp awthy recovery capture status JOB_ID --format=json

Keep the ID returned by start. Repeat continue and inspect that same job's status; do not start a new capture after an interruption. Manual continuation works when recurring managed recovery is off and does not enable recurring backups. no_file_work means no file job was claimed; a pending database child can still advance. Verify the required file and database scopes in the Hub summary before treating the backup as complete or using it for a production restore.

Managed site recovery

Managed recovery is started by an account owner in the Hub recovery page. The destination install must pass its local mode-specific preflight before the owner creates a grant:

wp awthy recovery restore preflight replace

Use repair instead when restoring over an existing site. After the Hub grant and signed plan are ready, run the durable job with the exact identities supplied by the Hub:

infra/recovery-restore-supervisor.sh <JOB_UUID> <PLAN_SHA256> \
  --config-grant-id=<GRANT_UUID> --mode=replace --path=/var/www/html

The supervisor repeats only the exit-75 fresh-boot handoff, up to four boots, and preserves the same job, plan, grant, and mode. Other failures remain visible and are not silently retried. Replace requires a clean claimed destination; repair carries only reviewed portable values, rotates WordPress sessions and salts, and leaves unresolved integrations for the listed reconnect action. Do not paste grant IDs, plan contents, capsule values, or recovery links into support records. The browser and durable journal never contain capsule plaintext.

Use the display-safe result labels consistently: Complete means fresh-boot validation and cleanup passed; Partial — action needed means a named value or integration needs manual work; Needs attention means the authorization, integrity, expiry, preflight, or cleanup boundary failed.

Offline full-backup restore

Use the archive's bundled RESTORE.md and restore/awthy-restore launcher with an isolated, empty target and database. Follow Restore a WordPress site for the full workflow. Do not use a generic extraction or database-import command in place of package verification.

Confirm the result

After a login-path, IP-rule, or factor reset, test the affected login from a separate browser session before closing your server session. Re-enable the intended protection only after fixing the cause.

Example: if a new IP rule locks out an administrator, disable enforcement through the trusted server session, correct the rule in WordPress, and verify access before turning enforcement back on.

If a command fails, retain its safe error message and stop before trying broader changes. For site recovery, leave the target isolated and follow the displayed rollback or cleanup action before rerunning.