#233: Add WP-CLI support with wp two-factor commands

[masteradhoc]

What?

Adds a wp two-factor WP-CLI namespace with six subcommands for inspecting and managing two-factor authentication on a per-user basis.

Fixes #233

Why?

The plugin ships no WP-CLI commands today. This PR adds support for it.

How?

• New file cli/class-two-factor-cli-command.php containing Two_Factor_CLI_Command extends WP_CLI_Command. Registered under WP_CLI::add_command( 'two-factor', ... ) in the plugin bootstrap behind a defined( 'WP_CLI' ) && WP_CLI guard.
• New public static helper Two_Factor_Core::clear_login_rate_limit( $user ) added to class-two-factor-core.php. Both the disable (full reset) and unlock commands call this single method rather than deleting the rate-limit meta keys at each call site.
• All commands are thin wrappers over the existing Two_Factor_Core and provider APIs — no raw SQL, no duplicated logic.

Commands:

Command	Description
wp two-factor status <user>	Read-only status; honours --format
wp two-factor disable <user> [<provider>]	Full reset or single-provider disable; --yes skips prompt
wp two-factor list-providers	Lists all registered providers
wp two-factor enable <user> <provider>	Enables a provider; refuses secret-based providers with a pointer
wp two-factor backup-codes generate <user> [--count=<n>]	(Re)generates recovery codes via the provider API
wp two-factor unlock <user>	Clears login throttle without touching 2FA config

All commands accept user by ID, login, or email. disable (full reset) asserts get_available_providers_for_user() is empty after clearing state, guarding against the fail-closed email fallback.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Sonnet 4.6
Used for: Full implementation of the CLI class, helper method, and bootstrap wiring, based on the given specification from my side. All generated code was reviewed and tested manually before submission.

Testing Instructions

Setup: Activate the Two-Factor plugin. Create a test user and enable at least one 2FA provider (TOTP or Email) via their profile page.

1. Registration

   • wp help two-factor — confirm all six subcommands are listed
   • wp help two-factor disable — confirm OPTIONS and EXAMPLES are shown

2. User resolution

   • wp two-factor status 1 — resolves by numeric ID
   • wp two-factor status <login> — resolves by login
   • wp two-factor status <email> — resolves by email
   • wp two-factor status nobody — prints Error: User not found: nobody

3. status

   • Run against a user with no 2FA → using_2fa is false
   • Run against a user with TOTP + backup codes → correct providers and code count
   • --format=json returns valid JSON

4. list-providers

   • Lists Email, TOTP, Backup Codes; Dummy absent when WP_DEBUG is off
   • --format=json works

5. disable — full reset

   • wp two-factor disable <user> → prompts for confirmation
   • wp two-factor disable <user> --yes → no prompt; status shows using_2fa: false
   • User can now log in with password only (no 2FA challenge)
   • Running again on the same user → "already disabled — no changes made"
   • Fail-closed guard: manually set _two_factor_enabled_providers in the DB to a non-existent class name, then run disable --yes — command should succeed and not leave email 2FA active

6. disable — single provider

   • wp two-factor disable <user> Two_Factor_Totp → only TOTP removed; backup codes still appear in status
   • Run same command again → "not enabled — no changes made"

7. enable

   • wp two-factor enable <user> Two_Factor_Email → success; appears in status
   • wp two-factor enable <user> Two_Factor_Totp → error referencing profile page
   • wp two-factor enable <user> Two_Factor_Backup_Codes → error pointing to backup-codes generate
   • wp two-factor enable <user> FakeClass → error "Is it a registered provider?"

8. backup-codes generate

   • wp two-factor backup-codes generate <user> → prints 10 codes
   • --count=5 → prints exactly 5 codes
   • Running again replaces the previous set

9. unlock

   • Trigger rate-limit with repeated bad login attempts, then wp two-factor unlock <user> → "Login throttle cleared"
   • On a non-rate-limited user → "was not rate-limited — no changes made"
   • After unlock: user can attempt login immediately without waiting

Screenshots or screencast

N/A — CLI only, no UI changes.

Changelog Entry

Added - WP-CLI wp two-factor commands for per-user 2FA status, disable, enable, backup-code generation, and login-throttle reset.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @mikeselander, @gurumark.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: mikeselander, gurumark.

Co-authored-by: masteradhoc <masteradhoc@git.wordpress.org>
Co-authored-by: kasparsd <kasparsd@git.wordpress.org>
Co-authored-by: sjinks <volodymyrkolesnykov@git.wordpress.org>
Co-authored-by: georgestephanis <georgestephanis@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.