How To Enable  WP-CLI Maintenance Mode: Easy Guide

If you’re dealing with some major development and maintenance on your website, WP-CLI maintenance mode commands can come to the rescue. It will temporarily tell your visitors that your site is under maintenance. 

You can use WP-CLI commands to help you enable and disable maintenance mode. It hides your site from visitors, preventing them from seeing broken pages or incomplete changes. 

This guide walks you through every WP-CLI maintenance mode command you need. We’ll go over everything from basic activation to troubleshooting when things go wrong. 

TL;DR: To put your WordPress site in maintenance mode, use the following command:

 wp maintenance-mode activate 

We also recommend that you use a staging site to test your maintenance before you put your website in maintenance mode. 

Prerequisites

Before you can use WP-CLI maintenance mode commands, you need three things set up on your server. Don’t worry if this sounds technical—these are one-time setup steps that most WordPress users can handle with a little guidance.

• SSH Access: You’ll need a basic understanding of SSH and the credentials to connect to your server through it. 
• WP-CLI Installed: WP-CLI needs to be installed on your server before you can use maintenance mode commands. Test if it’s already available by running wp –info in your terminal. 

Activating WP-CLI Maintenance Mode

WordPress maintenance tasks like updates and debugging are made much easier with WP-CLi maintenance mode. You can work on your site without visitors seeing broken content. Here’s how to activate maintenance mode: 

1. Connect to your server (SSH): Open Terminal and run
   

ssh username@your-server-ip

Replace username and your-server-ip with your own credentials.

2. Go to your WordPress install directory
   

You’re trying to navigate to your root folder. In our case, it’s the public_html folder and this was the folder for it: 

cd ~/public_html    

3. Enable maintenance mode: The easiest way to do this is to use the following code:

wp maintenance-mode activate

4. Confirm it’s on: Use the following code to do so: 

wp maintenance-mode status

You’ll see this confirmation message: “Maintenance mode activated.” Once activated, your site immediately starts showing the maintenance message to all visitors. 

📝 Important Note 📝

WordPress automatically deactivates maintenance mode after 10 minutes, even if you don’t manually turn it off. This built-in safety feature prevents your site from staying in maintenance mode indefinitely if you forget to deactivate it. However, if your work takes longer than 10 minutes, you’ll need to reactivate maintenance mode or consider using a dedicated maintenance mode plugin for extended periods.

Deactivating Maintenance Mode

Once you’ve finished your WordPress updates, development work, or troubleshooting, you need to deactivate WP-CLI maintenance mode to restore normal access for your visitors. This is also the go-to solution when your site gets stuck showing the maintenance message unexpectedly.

1. Connect to your server (SSH): Open Terminal and run

ssh username@your-server-ip

Replace username and your-server-ip with your own credentials.

2. Go to your WordPress install directory: Navigate to your WordPress root folder. In our case, it’s the public_html folder:

cd ~/public_html

3. Disable maintenance mode: Use the following command:

wp maintenance-mode deactivate

4. Confirm it’s off: Run this command:

wp maintenance-mode status

You’ll see the message: “Maintenance mode deactivated.” Your site will immediately be live and visible to visitors again.

Troubleshooting Maintenance Mode Issues

Even with simple WP-CLI commands, maintenance mode doesn’t always work as expected. Whether your site is stuck displaying the maintenance message or won’t activate maintenance mode at all, these troubleshooting steps will help you identify and fix the most common problems.

Fixing Stuck Maintenance Mode

If your site is still stuck in maintenance mode, run wp maintenance-mode deactivate again from your WordPress root directory. Sometimes network hiccups or server delays prevent the first command from completing properly.

Still stuck? The .maintenance file is likely corrupted or has incorrect permissions. You’ll need to manually delete this file using FTP or your hosting provider’s file manager. 

Maintenance Mode Not Activating

When the activate command runs but your site doesn’t show the maintenance message, you’re likely in the wrong directory. Run pwd (print working directory) to see your current location. The output should show your WordPress root path, typically something like /home/username/public_html or /var/www/html. If you’re in a subfolder like /wp-content or /themes, use the cd command to navigate back to the WordPress root.

Alternatives to WP-CLI

While WP-CLI maintenance mode commands are perfect for quick, automated tasks, they’re not always the best solution for every situation. If you need more control over the maintenance experience or longer maintenance periods, these alternatives might better suit your needs.

Maintenance Mode Plugins

WordPress maintenance  plugins offer significantly more flexibility than the basic WP-CLI maintenance mode. Consider using a dedicated maintenance mode plugin if you need custom landing pages that match your brand, complete with your logo, colors, and messaging. Popular options include SeedProd, WP Maintenance Mode, and Coming Soon Pro, which let you create professional-looking “under construction” pages.

Manual .htaccess Method

Advanced users can redirect all traffic using custom code in their .htaccess file, located in the WordPress root directory. This method involves adding redirect rules that send visitors to a custom maintenance page while allowing you to access the site normally. 

⚠️ Expert advice: Take a full backup before you make these changes to your live site. 

Add the following code to your .htaccess file: 

# Enable Maintenance Mode
RewriteEngine On
# Allow your IP address (replace with your actual IP)
RewriteCond %{REMOTE_ADDR} !^123\.45\.67\.89$
# Allow maintenance page itself
RewriteCond %{REQUEST_URI} !/maintenance.html$
# Redirect everyone else to maintenance.html
RewriteRule ^.*$ /maintenance.html [R=302,L]

Best Practices for Maintenance Mode

Following these maintenance mode best practices will help you avoid common pitfalls and ensure a smooth experience for both you and your visitors. These guidelines can save you from frustrated users, lost revenue, and technical headaches down the road.

• Test in a staging environment first to avoid live-site errors. Create a staging site (a copy of your live site) where you can safely test commands, practice your workflow, and identify potential issues before they affect real visitors. Many hosting providers offer one-click staging environments, or you can use plugins like BlogVault. 
• Schedule maintenance during low-traffic hours. Check your Google Analytics or hosting dashboard to identify when your site gets the least traffic. Performing maintenance during peak hours means more visitors will encounter the maintenance message, potentially leading to lost sales, reduced engagement, and frustrated users.
• Always deactivate maintenance mode immediately after completion. Don’t rely on the 10-minute auto-deactivation timer.  Forgetting to deactivate maintenance mode is one of the most common mistakes, and it can result in visitors seeing the maintenance message long after your work is complete.

Final Thoughts

WP-CLI maintenance mode commands are an excellent tool for developers and site administrators. It gives you quick, reliable control over their WordPress sites. The commands are perfect for automated deployment scripts, emergency troubleshooting, and brief maintenance tasks.

We recommend using maintenance mode together with a test site. A test site lets you troubleshoot and fix issues in a safe environment without affecting your live site. This way, your live site spends less time in maintenance mode, and you can confidently apply only the tested changes to production. You can find solutions for most update or compatibility problems before they ever impact real visitors.

FAQs

How to enable WP maintenance mode? 

To enable WordPress maintenance mode using WP-CLI, connect to your server via SSH, navigate to your WordPress root directory, and run wp maintenance-mode activate. Your site will immediately display the maintenance message to visitors. The mode automatically deactivates after 10 minutes, or you can manually deactivate it with wp maintenance-mode deactivate.

How to run WP CLI commands? 

First, ensure you have SSH access to your server and WP-CLI installed. Connect to your server using Terminal (Mac/Linux) or PuTTY (Windows), then navigate to your WordPress root directory using the cd command. Once you’re in the correct folder (where you can see wp-config.php), you can run any WP-CLI command starting with wp. Test your setup with wp –info to verify everything is working properly.

How to activate maintenance mode? 

Use the command wp maintenance-mode activate from your WordPress root directory. This creates a .maintenance file that triggers WordPress to show the “Briefly unavailable for scheduled maintenance” message. The activation is instant and affects all visitors except logged-in administrators. Remember that maintenance mode automatically turns off after 10 minutes.

How to fix WordPress maintenance mode? 

If your site is stuck in maintenance mode, first try running wp maintenance-mode deactivate from your WordPress root directory. If that doesn’t work, manually delete the .maintenance file from your WordPress root folder using FTP or your hosting provider’s file manager. This file is located in the same directory as wp-config.php and removing it immediately restores normal site access.