A MainWP Labs project, powered by MainWP

A CLI for managing your MainWP Dashboard from the terminal. List sites, push updates, sync data, run batch operations across dozens of sites. The command is mainwpcontrol.

Looking for the MCP Server instead? MainWP MCP Server is for conversational AI management inside Claude, Cursor, or any MCP-compatible client. MainWP Control is for automation: cron jobs, CI/CD pipelines, monitoring scripts, and batch operations. Both talk to the same Abilities API with the same safety model.

On Windows? Use Git Bash and every example below works without changes. For scheduled workflows (cron), see WSL.

You need Node.js 20+ and a MainWP Dashboard (v6+) with an Application Password.

npm install -g @mainwp/control

mainwpcontrol login

mainwpcontrol abilities list

You should see something like this:

Abilities (87 total)

  Sites
Name              Description           Type
----------------  --------------------  --------------
list-sites-v1     List MainWP sites     📖 read
    mainwpcontrol abilities run list-sites-v1
get-site-v1       Get site details      📖 read
    mainwpcontrol abilities run get-site-v1
sync-sites-v1     Sync all sites        ✏️  write
    mainwpcontrol abilities run sync-sites-v1

That's it. You're connected and you can see every operation your Dashboard supports.

abilities list shows every operation available on your Dashboard. These are called "abilities" and they cover sites, plugins, themes, updates, clients, tags, and more.

Each ability has a name (like list-sites-v1) that you pass to abilities run to execute it. The list tells you whether each one is read-only, a write operation, or destructive.

List all your sites:

mainwpcontrol abilities run list-sites-v1 --json

Check for pending updates across sites:

mainwpcontrol abilities run list-updates-v1 --json

Get details for a specific site:

mainwpcontrol abilities run get-site-v1 --input '{"site_id_or_domain": 1}' --json

Windows? This works as-is in Git Bash. In PowerShell, escape the inner quotes: '{\"site_id_or_domain\": 1}'. Or skip quoting entirely with --input-file (details).

Preview a destructive action before running it:

mainwpcontrol abilities run delete-site-v1 \
  --input '{"site_id_or_domain": "mysite.com"}' \
  --dry-run --json

Nothing changes until you explicitly pass --confirm.

Update plugins and wait for completion:

mainwpcontrol abilities run update-site-plugins-v1 \
  --input '{"site_id": 1}' \
  --wait --json

--wait blocks until the operation finishes. Useful in CI pipelines.

Pre-built keychain binaries are included for macOS, Windows, and Linux (x64 and arm64). On other platforms you may need C++ build tools during installation.

npm install -g @mainwp/control

# Interactive login (stores credentials in your OS keychain)
mainwpcontrol login

Use this when no OS keychain is available, or if keytar fails to build.

npm install -g @mainwp/control

export MAINWP_APP_PASSWORD='xxxx xxxx xxxx xxxx xxxx xxxx'

mainwpcontrol login --url https://dashboard.example.com --username admin

When the OS keychain is unavailable, credentials are not stored on disk. Keep MAINWP_APP_PASSWORD set for each run.

If keytar is installed but broken, set MAINWPCONTROL_NO_KEYTAR=1 to skip loading it.

# macOS / Linux (lasts until you close the terminal)
export MAINWP_APP_PASSWORD='xxxx xxxx xxxx xxxx xxxx xxxx'

# Windows PowerShell (lasts until you close the window)
$env:MAINWP_APP_PASSWORD = 'xxxx xxxx xxxx xxxx xxxx xxxx'

# macOS / Linux / Git Bash on Windows
mainwpcontrol abilities run get-site-v1 --input '{"site_id_or_domain": 1}' --json

# Windows PowerShell
mainwpcontrol abilities run get-site-v1 --input '{\"site_id_or_domain\": 1}' --json

mainwpcontrol abilities run get-site-v1 --input-file params.json --json

Your Dashboard exposes its operations as "abilities." You browse them, pick one, and run it. Every ability has a versioned name like list-sites-v1 that you pass to abilities run.

# List all abilities
mainwpcontrol abilities list

# Filter by category
mainwpcontrol abilities list --category sites

# Get full details and input schema for an ability
mainwpcontrol abilities info list-sites-v1

# Run an ability
mainwpcontrol abilities run list-sites-v1 --json

# Run with input parameters
mainwpcontrol abilities run get-site-v1 --input '{"site_id_or_domain": 1}' --json

# Windows PowerShell: escape inner quotes (Git Bash doesn't need this)
mainwpcontrol abilities run get-site-v1 --input '{\"site_id_or_domain\": 1}' --json

# Or use a file (works everywhere)
mainwpcontrol abilities run get-site-v1 --input-file params.json --json

Each mainwpcontrol login creates a profile, a named connection to a Dashboard, identified by hostname. If you manage multiple Dashboards, run login once per Dashboard to create a profile for each.

# List all profiles
mainwpcontrol profile list

# Switch active profile
mainwpcontrol profile use production.example.com

# Use a profile for one command without switching
mainwpcontrol abilities list --profile staging.example.com

# Delete a profile and its keychain credentials
mainwpcontrol profile delete staging.example.com

doctor checks your configuration, credentials, and Dashboard connectivity. Run it first if something isn't working.

# Check configuration and connectivity
mainwpcontrol doctor

# Verbose output
mainwpcontrol doctor -v

# JSON output
mainwpcontrol doctor --json

If you have an LLM API key, you can talk to your Dashboard in plain English instead of constructing commands. Good for exploration, not required for anything.

Set one of these environment variables to enable it:

# Pick one (Anthropic, OpenAI, Google, or OpenRouter)
export ANTHROPIC_API_KEY='sk-ant-...'

mainwpcontrol chat
mainwpcontrol chat "list all sites with pending updates"

See Chat Mode Configuration for all supported providers and flags.

These flags work on every command.

Extra flags for abilities run. These control input, safety checks, and batch job behavior.

Abilities are the operations your MainWP Dashboard exposes through its REST API. Each one has:

• A versioned name (e.g., list-sites-v1, delete-site-v1)
• An input schema (what parameters it accepts)
• Annotations that tell you what kind of operation it is

The annotations matter:

• Readonly: Safe to run anytime. Cannot modify data.
• Destructive: Permanently changes or deletes data. Requires --dry-run preview, then --confirm to execute.
• Idempotent: Safe to re-run. Same result on repeated calls.

Run mainwpcontrol abilities info <name> to see the full schema and annotations for any ability.

A profile is a named connection to a MainWP Dashboard. It stores the Dashboard URL and username. Your password stays in the OS keychain (or in the MAINWP_APP_PASSWORD environment variable when no keychain is available).

Running mainwpcontrol login creates a profile automatically, named after the Dashboard hostname:

# Creates profile "staging.example.com"
mainwpcontrol login --url https://staging.example.com --username admin

# Creates profile "production.example.com"
mainwpcontrol login --url https://production.example.com --username admin

The profile file at ~/.config/mainwpcontrol/profiles.json never contains passwords.

Destructive operations follow a two-step pattern: preview first, then execute.

# Step 1: Preview (nothing changes)
mainwpcontrol abilities run delete-site-v1 \
  --input '{"site_id_or_domain": "mysite.com"}' \
  --dry-run --json

# Step 2: Execute after reviewing the preview
mainwpcontrol abilities run delete-site-v1 \
  --input '{"site_id_or_domain": "mysite.com"}' \
  --confirm --force --json

--dry-run and --confirm are mutually exclusive. You cannot pass both.

In CI/scripted workflows where you've already validated the operation, pass --confirm --force directly to skip the interactive prompt.

Operations that affect many items (200+) are automatically queued as batch jobs. The command returns a job_id immediately, and you can watch progress:

mainwpcontrol jobs watch <job-id>

# With a timeout
mainwpcontrol jobs watch <job-id> --timeout 120

Or use --wait on the original command to block until completion:

mainwpcontrol abilities run sync-sites-v1 --wait --wait-timeout 300 --json

# Non-interactive login
export MAINWP_APP_PASSWORD='xxxx xxxx xxxx xxxx xxxx xxxx'
mainwpcontrol login --url https://dashboard.example.com --username admin

# Silent execution with exit codes
mainwpcontrol abilities run list-sites-v1 --json --quiet
echo "Exit code: $?"

# Pipeline branching on exit codes
if mainwpcontrol abilities run check-sites-v1 --json --quiet; then
  echo "All sites healthy"
else
  echo "Issues detected"
fi

# From a JSON file
mainwpcontrol abilities run update-site-plugins-v1 --input-file params.json --json

# From stdin
echo '{"site_id_or_domain": 1}' | mainwpcontrol abilities run get-site-v1 --input - --json

# Heredoc
mainwpcontrol abilities run get-site-v1 --input - --json <<EOF
{"site_id_or_domain": 1}
EOF

Chat requires one of these environment variables:

Additional chat flags: --provider, --model, --max-turns, --max-context-messages, --no-stream.

In non-TTY environments (pipes, CI), mainwpcontrol chat without a message argument exits with guidance instead of hanging.

# Bash
source /path/to/mainwp-control/scripts/completions/mainwpcontrol.bash

# Zsh
source /path/to/mainwp-control/scripts/completions/mainwpcontrol.zsh

Settings live at ~/.config/mainwpcontrol/settings.json:

{
  "defaultJsonOutput": true,
  "timeout": 30000,
  "debug": false,
  "llmProvider": "openai",
  "chatContextMessages": 20
}

Step-by-step guides for common automation patterns:

All settings in ~/.config/mainwpcontrol/settings.json:

npm run build      # Build the project
npm test           # Run tests (unit + e2e, no network needed)
npm run lint       # Check code style

npm run test:live runs tests against a real MainWP Dashboard, including workflow documentation validation. These require a running Dashboard and credentials:

export MAINWP_API_URL=https://your-dashboard.example.com
export MAINWP_USER=your-admin-username
export MAINWP_APP_PASSWORD='your-application-password'

npm run test:live

The live suite includes API tests (login, abilities discovery, read-only execution, safety model, exit codes) and workflow doc tests (validates that every jq expression, field name, and data pipeline documented in docs/workflows/ works against the real API).

Live tests are safe: they only run read-only operations and --dry-run previews, never mutations.

GPL-3.0-or-later

• Node.js 20 LTS or later
• MainWP Dashboard 6+ with Abilities API
• WordPress Application Password

• MainWP
• MainWP MCP Server
• Issue Tracker