WP-CLI is installed on your server (verify with wp --version)
SSH access to your server
A WP Umbrella account & a workspace API key (find this in your WP Umbrella dashboard under Workspaces > API Keys)
WordPress is already installed at each target site
SSH into your server, navigate to the WordPress directory for the site you want to attach, and run:
wp plugin install wp-health --activate && wp wp-umbrella attach --api-key=YOUR_API_KEY_HEREThe command chains 2 operations together using &&:
wp plugin install wp-health --activate downloads & activates the WP Umbrella plugin. Its WordPress.org slug is wp-health for legacy reasons, even though the product is marketed as WP Umbrella.
wp wp-umbrella attach --api-key=... connects the site to your WP Umbrella workspace.
A successful first-time install looks like this:
Installing WP Umbrella: Update Backup Restore & Monitoring (2.24.2)
Downloading installation package from https://downloads.wordpress.org/plugin/wp-health.v2.24.2.zip...
Unpacking the package...
Installing the plugin...
Plugin installed successfully.
Activating 'wp-health'...
Success: Installed 1 of 1 plugins.
Using workspace "Your Workspace" (id=...).
Success: Site attached to project 123456.If the plugin was already installed or the site was previously attached, you may see lines like:
Warning: Plugin 'wp-health' is already active.
Success: Site re-attached to existing project 119289.These are not errors. The script will complete normally.
cPanel stores user accounts under /home/, /home2/, /home3/, etc., depending on the disk layout. Each user account can host the main domain plus addon domains, each with its own WordPress install. To locate every WordPress directory on the server:
find /home* -name "wp-config.php" -not -path "*/wp-content/*" 2>/dev/nullThe -not -path "*/wp-content/*" filter excludes nested wp-config.php files left behind by backup plugins or staging copies.
Save the following as wp-umbrella-bulk.sh in your root home directory:
#!/bin/bash
# WP Umbrella bulk installer for cPanel/WHM servers
# Run as root: sudo ./wp-umbrella-bulk.sh
API_KEY="YOUR_API_KEY_HERE"
LOG_FILE="/root/wp-umbrella-install-$(date +%Y%m%d-%H%M%S).log"
echo "Starting bulk install. Log: $LOG_FILE"
for wp_config in $(find /home* -name "wp-config.php" -not -path "*/wp-content/*" 2>/dev/null); do
site_dir=$(dirname "$wp_config")
site_owner=$(stat -c '%U' "$wp_config")
echo "----------------------------------------" | tee -a "$LOG_FILE"
echo "Site: $site_dir" | tee -a "$LOG_FILE"
echo "Owner: $site_owner" | tee -a "$LOG_FILE"
echo "----------------------------------------" | tee -a "$LOG_FILE"
sudo -u "$site_owner" -i -- wp plugin install wp-health --activate --path="$site_dir" 2>&1 | tee -a "$LOG_FILE" \
&& sudo -u "$site_owner" -i -- wp wp-umbrella attach --api-key="$API_KEY" --path="$site_dir" 2>&1 | tee -a "$LOG_FILE"
done
echo "Done. Review $LOG_FILE for results."chmod +x wp-umbrella-bulk.sh
sudo ./wp-umbrella-bulk.shAfter the script finishes, check your WP Umbrella dashboard. All newly attached sites will appear under your workspace. You can also count successful attachments from the log:
grep -c "Success: Site" /root/wp-umbrella-install-*.logAlways run as the site owner, not root. WordPress files are owned by the cPanel user. Running WP-CLI as root will trigger permission warnings and may create files with the wrong ownership. The script handles this by using sudo -u to switch to each site's owner.
The -i flag in sudo loads the user's login shell environment. This matters on cPanel because PHP binaries and wp may be aliased per user, particularly with MultiPHP.
Throttle for large servers: On servers with 500+ sites, add an sleep 1 inside the loop to avoid hammering the WordPress.org download endpoint and your own database.
wp: command not found WP-CLI is not installed or not in the PATH. Install from https://wp-cli.org and ensure it lives at /usr/local/bin/wp.
Error establishing a database connection The script is not in the WordPress directory. Make sure --path= points to the folder containing wp-config.php.
Plugin 'wp-health' is already active Not an error. The && chain continues to the attach step regardless.
Permission errors during install. You are running as the wrong user. On cPanel, always switch to the site owner sudo -u before running WP-CLI.
API key invalid or workspace not found. Double-check the key in your WP Umbrella dashboard. Keys are workspace-specific, so confirm you are using the key for the workspace you want sites attached to.