WordPress maintenance mode is controlled by a single file in the WordPress root directory. Every site your agency manages can be flipped into maintenance mode from one terminal session, without logging into a single admin panel. This guide covers three scripting approaches that work across a fleet, the verification step most agencies skip, and the client communication runbook that should accompany every maintenance window you schedule.
Logging into 20 admin panels to toggle maintenance mode is not a scaling problem waiting for a bigger team; it is a systems design failure your agency can fix today.
The average maintenance window for a WordPress agency managing 10 to 30 client sites looks like this: one person logs into each site, activates a maintenance screen, waits for the all-clear, then logs back in to deactivate. At 3 to 5 minutes per site, a 20-site fleet costs an hour of senior engineer time on access and navigation alone. That hour is not billable.
The second cost is human error. When maintenance mode is triggered manually, sites get missed. A developer distracted by a message skips one. A client calls because their site is still live during a database migration. The operations failure is not the manual work itself; it is the absence of a repeatable, auditable runbook that executes identically every time.
The fix is treating maintenance mode as a fleet-level command, not a per-site task. Every site in your fleet should respond to a single script: activate, verify, work, deactivate.
WordPress maintenance mode is controlled entirely by a single file, .maintenance, placed in the WordPress root directory.
When WordPress initializes in wp-settings.php, it checks whether a .maintenance file exists in the root of the installation. If the file is present and contains a PHP variable named $upgrading set to a Unix timestamp within the last 600 seconds, WordPress serves the maintenance screen instead of the normal site. The file itself contains a single line: <?php $upgrading = [timestamp]; ?>
The maintenance screen is customizable. If a file named maintenance.php exists inside your wp-content/ directory, WordPress serves it instead of the default “Briefly unavailable for scheduled maintenance” message. A well-run agency puts a branded maintenance page here with an estimated return time and an emergency contact for urgent issues.
Two constraints your script must account for:
Maintenance mode is, at its core, a file operation. Anything that can write and delete files on your server controls it.
Every reliable fleet-wide maintenance approach reduces to one of three mechanisms: WP-CLI over SSH, direct file operations via SSH, or a WPOS site agent command.
Method 1: WP-CLI over SSH
WP-CLI’s maintenance-mode subcommand is the most operator-friendly approach for agencies with server access. It handles the timestamp refresh internally, accepts a –path flag to target a specific WordPress installation, and returns a clean status on every call. To activate across a fleet, SSH into each host and run wp maintenance-mode activate –path=’/var/www/yoursite’ –allow-root. To deactivate, replace activate with deactivate. A bash loop over a list of your site hosts and paths completes a 20-site fleet in under 30 seconds and writes a log of every command executed.
Method 2: Direct file operations via SSH
If WP-CLI is not installed on the target servers, write the .maintenance file directly. SSH into each host and run: echo ‘<?php $upgrading = $(date +%s); ?>’ > /var/www/site/.maintenance. For windows longer than 10 minutes, rerun this command every 9 minutes to refresh the timestamp. This method also lets you copy a custom maintenance.php to wp-content/ at activation time, so every site in the fleet displays a branded maintenance screen instead of the WordPress default. Deploy the template once, reference it from the activation script, and every client sees consistent branding during every window.
Method 3: WPOS site agent
If your agency runs a fleet through WPOS, maintenance mode is issued as a single command to the site agent. The agent handles the SSH connection, file write, and status verification per site, then logs the maintenance window to each site’s Playbook automatically. No shell loop required: the fleet responds as a unit and the operation is recorded without a separate documentation step.
Before starting any migration, update, or infrastructure change, confirm that every site in the maintenance window is actually serving the maintenance screen to visitors.
The verification step is where most scripted approaches fail. A site may have returned an SSH error silently. A path variable may have been wrong. A server may have been unreachable at activation time. Beginning work without verifying puts live client traffic through a half-migrated state, and that is a client relationship event, not just a technical one.
The fastest check: request each domain and read the HTTP status code. WordPress returns 503 Service Unavailable when serving the maintenance screen. Any site returning 200 OK is still fully live. Run a curl request against every domain after activation, and run the same check again after deactivation to confirm every site is back online.
Do not begin work until every site returns 503. A checklist that can be skipped is not a runbook; it is a suggestion.
For agencies operating through WPOS, the Workspace shows each site’s current status. Maintenance mode appears as a status flag in the fleet view, so you can confirm the entire fleet from one screen without running a separate request per domain.
Every maintenance window needs a paired client communication runbook that runs in parallel with the technical steps; the script and the client messages are two sides of the same operation.
Client-facing communication during a maintenance window is not a courtesy. It is the difference between a client who trusts your agency’s process and one who contacts your team at 2 AM because their site returned a 503 with no explanation.
The three-message sequence:
The summary in the close message is not optional. Agencies that send “all done” with no detail are training clients to distrust their maintenance windows. Specifics, including version numbers or a one-line description of what was migrated or restructured, build the kind of retention that carries a $5,000-plus relationship through years of work.
Wire the client messages to your maintenance script so they send automatically at the right moments. The activate step triggers the first notification. The deactivate step triggers the close. Removing human judgment from the timing removes the most common failure point in client communication during a maintenance window.
Every maintenance window your agency runs is a decision, and decisions not recorded are institutional memory that disappears with the next team turnover.
The most common knowledge gap for WordPress agencies is not technical skill. It is that the context behind past decisions dissolves when people leave. A client site migrated from shared hosting to a VPS in Q3. Why? Which server? Who approved it? What changed? If answering those questions requires hunting through chat history, your agency has a memory problem that compounds with every hire and every departure.
Maintenance windows are high-signal events. They almost always accompany a significant change: a core update, a hosting migration, a database restructure. Recording them creates a timeline that future team members can read in seconds rather than reconstruct over hours.
What to record per maintenance window:
If your agency operates on WPOS, each site carries a Decisions log in its Playbook. A maintenance window entry might read: “2026-06-14: Maintenance window (22:00 to 23:15 UTC). Updated WordPress core from 6.7.1 to 6.8.0 across 18 client sites. No anomalies. Runbook version 3.1.” Six months from now, that entry answers every question a new team member might ask about that site’s history.
For a deeper look at building the monthly cadence that generates these records systematically, see how to run a monthly WordPress maintenance routine across many client sites. For the full framework that turns isolated windows into a scalable plan, see how to build a WordPress maintenance plan that scales across many client sites.
Yes. WordPress maintenance mode is controlled by a single file (.maintenance) in the WordPress root directory. You can activate and deactivate it using WP-CLI, a bash script over SSH, or by writing and deleting the file directly on the server. No third-party software is required.
WordPress only respects the .maintenance file if the timestamp inside it is within 600 seconds (10 minutes) of the current time. For longer maintenance windows, refresh the file every 9 minutes by rewriting it with an updated timestamp, or use WP-CLI’s maintenance-mode command, which handles this automatically.
Yes. By default, WordPress allows logged-in administrators to bypass the maintenance screen and view the site normally. This is useful for verification after activation, but it means any client contacts with administrator accounts can also access the site during the window.
Create a file named maintenance.php inside your wp-content/ directory. WordPress will serve this file instead of the default maintenance message whenever the .maintenance file is active. Your custom page can include your agency branding, an estimated return time, and an emergency contact number for urgent issues.
The most reliable approach for a fleet is WP-CLI over SSH, called in a loop across all sites. WP-CLI handles the timestamp refresh automatically, so the 10-minute expiry is not a concern for longer windows. For agencies running WPOS, maintenance mode is issued as a single site agent command that activates the entire fleet and logs each window to the site’s Playbook.
200 free credits. Just describe what you need.
See It In Action