How To Install & Activate WP Umbrella Using WP CLI

Prerequisites

• 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

Installing on a Single 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_HERE

What the command does

The command chains 2 operations together using &&:

1. 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.

2. wp wp-umbrella attach --api-key=... connects the site to your WP Umbrella workspace.

Expected output

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.

Installing on Multiple Sites (In Bulk)

Step 1: Find all WordPress installations

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/null

The -not -path "*/wp-content/*" filter excludes nested wp-config.php files left behind by backup plugins or staging copies.

Step 2: Run the bulk installation script

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."

Step 3: Make it executable & run

chmod +x wp-umbrella-bulk.sh
sudo ./wp-umbrella-bulk.sh

Step 4: Verify results

After 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-*.log

Important Notes for cPanel Servers

Always 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.

Troubleshooting

1. 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.

2. Error establishing a database connection The script is not in the WordPress directory. Make sure --path= points to the folder containing wp-config.php.

3. Plugin 'wp-health' is already active Not an error. The && chain continues to the attach step regardless.

4. 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.

5. 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.