How to toggle WordPress maintenance mode with WP-CLI

WordPress maintenance mode temporarily replaces public requests with the built-in scheduled-maintenance response while shell work is underway. WP-CLI can switch that state on before a short update or cutover and switch it off again after the site has been checked.

The wp maintenance-mode command writes the same .maintenance marker that WordPress uses during automatic updates. WordPress treats that marker as active only while its timestamp is less than ten minutes old, so the built-in mode fits short visitor-facing pauses rather than long redesigns or migrations.

Use an account that owns the WordPress files or can write the document root. A successful toggle should show active status in WP-CLI, a public 503 Service Unavailable response while enabled, and 200 OK again after deactivation.

1. Change into the exact WordPress document root.

   $ cd /var/www/example.com/public_html

   Use the directory that contains wp-config.php. A --path=/var/www/example.com/public_html global option can target the same path when the shell must stay elsewhere.

2. Confirm that WP-CLI is loading the expected site.

   $ wp option get home
   https://www.example.com

   On multisite, --url=https://site.example.com can help WP-CLI bootstrap the intended network, but the .maintenance marker belongs to the shared WordPress root and can affect every site in that network.
   Related: How to use WP-CLI safely on a production WordPress site

3. Activate maintenance mode.

   $ wp maintenance-mode activate
   Enabling Maintenance mode...
   Success: Activated Maintenance mode.

   The command must be able to write .maintenance in the WordPress root. If the shell output says activated but status stays inactive, run WP-CLI as the site file owner or fix document-root write permission before continuing.

4. Verify that WP-CLI sees maintenance mode as active.

   $ wp maintenance-mode status
   Maintenance mode is active.

5. Check the public maintenance response.

   $ curl -I -sS https://www.example.com/
   HTTP/1.1 503 Service Unavailable
   ##### snipped #####
   Retry-After: 600
   Cache-Control: no-cache, must-revalidate, max-age=0, no-store, private
   Content-Type: text/html; charset=UTF-8

   A 503 response with Retry-After tells crawlers and monitors that downtime is temporary.
   Tool: HTTP Header Checker

6. Run the planned update, backup, or cutover while maintenance mode is active.

   WordPress ignores a .maintenance timestamp after ten minutes. Use this built-in mode for short update or cutover windows; use a server-level or plugin maintenance page for longer downtime.

7. Deactivate maintenance mode.

   $ wp maintenance-mode deactivate
   Disabling Maintenance mode...
   Success: Deactivated Maintenance mode.

8. Verify that WP-CLI sees maintenance mode as inactive.

   $ wp maintenance-mode status
   Maintenance mode is not active.

9. Check that the public site returns a normal response again.

   $ curl -I -sS https://www.example.com/
   HTTP/1.1 200 OK
   ##### snipped #####
   Content-Type: text/html; charset=UTF-8