WP-CLI Recovery and Maintenance

Last verified: 2026-08-27

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, retained file-integrity snapshots, and encrypted redacted diffs in bounded restartable 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.

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.