From 1348aba41db8d3aeefa60ae50c5c152bb1d17d17 Mon Sep 17 00:00:00 2001 From: Dennis Dornon Date: Tue, 24 Mar 2026 18:58:46 -0400 Subject: [PATCH] add Windows/PowerShell guidance and skip links to docs Add PowerShell quoting examples alongside bash in README and workflow docs. Recommend --input-file as the cross-platform approach. Add skip-ahead links for users who already have MainWP Control set up. --- README.md | 42 +++++++++++++++++++ docs/workflows/daily-health-check.md | 9 ++++ docs/workflows/input-from-file.md | 12 ++++++ docs/workflows/monitoring-integration.md | 11 +++++ docs/workflows/monthly-batch-updates.md | 4 ++ .../plugin-deployment-verification.md | 10 +++++ 6 files changed, 88 insertions(+) diff --git a/README.md b/README.md index a4b6fa4..e639252 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,20 @@ mainwpcontrol abilities run list-updates-v1 --json mainwpcontrol abilities run get-site-v1 --input '{"site_id": 1}' --json ``` +On Windows PowerShell, escape the inner quotes: + +```powershell +mainwpcontrol abilities run get-site-v1 --input '{\"site_id\": 1}' --json +``` + +To skip quoting issues entirely, use a JSON file (works on every platform): + +```bash +mainwpcontrol abilities run get-site-v1 --input-file params.json --json +``` + +See [Input from File](docs/workflows/input-from-file.md) for more on this approach. + **Preview a destructive action before running it:** ```bash @@ -165,6 +179,28 @@ When you run a command, the output appears in your terminal. A few things to kno - **`--json`** tells `mainwpcontrol` to output structured JSON (useful for scripting and piping to other tools) - **Exit codes** indicate success (`0`) or failure (`1` through `5`). You won't see them directly, but scripts and CI use them to decide what happens next. Run `echo $?` (macOS/Linux) or `echo $LASTEXITCODE` (PowerShell) after a command to check. +### JSON quoting on the command line + +When you pass JSON with `--input`, quoting depends on your shell: + +```bash +# macOS / Linux / Git Bash on Windows +mainwpcontrol abilities run get-site-v1 --input '{"site_id": 1}' --json + +# Windows PowerShell +mainwpcontrol abilities run get-site-v1 --input '{\"site_id\": 1}' --json +``` + +Windows strips the inner double quotes unless you escape them with backslashes. If this gets annoying (and it will, with longer JSON), put your parameters in a file and use `--input-file`: + +```bash +mainwpcontrol abilities run get-site-v1 --input-file params.json --json +``` + +This works the same on every platform. See [Input from File](docs/workflows/input-from-file.md) for details. + +**Git Bash on Windows** (comes with Git for Windows) handles quoting the same way macOS and Linux do. If you use Git Bash, all the examples in this documentation work without changes. + --- @@ -190,6 +226,12 @@ mainwpcontrol abilities run list-sites-v1 --json # Run with input parameters mainwpcontrol abilities run get-site-v1 --input '{"site_id": 1}' --json + +# Windows PowerShell: escape inner quotes +mainwpcontrol abilities run get-site-v1 --input '{\"site_id\": 1}' --json + +# Or use a file (works everywhere) +mainwpcontrol abilities run get-site-v1 --input-file params.json --json ``` ### Profiles diff --git a/docs/workflows/daily-health-check.md b/docs/workflows/daily-health-check.md index 65e3b6f..da80d50 100644 --- a/docs/workflows/daily-health-check.md +++ b/docs/workflows/daily-health-check.md @@ -16,6 +16,15 @@ By the end of this guide you will have: - **Slack notifications** when any site is disconnected or unreachable - **A cron job** that runs this check automatically every day +> **Windows users:** This guide builds a bash script and schedules it with cron, both native to macOS and Linux. The `mainwpcontrol` commands themselves work fine on Windows, but the scripting and scheduling around them don't translate directly. +> +> Your best options: +> - **Git Bash** (comes with Git for Windows) lets you follow this guide for manual runs. +> - **GitHub Actions** handles the scheduling for you and runs on Linux in the cloud. See the [Monthly Batch Updates](monthly-batch-updates.md) guide (Option B) for a template you can adapt. +> - **WSL** works for following this guide as-is, but WSL isn't always running in the background, so cron jobs may not fire reliably unless you configure it to auto-start. + +**Already using MainWP Control?** If `mainwpcontrol doctor` shows "System is ready", skip to [Step 4: Create a Slack Incoming Webhook](#step-4-create-a-slack-incoming-webhook). + --- ## Prerequisites diff --git a/docs/workflows/input-from-file.md b/docs/workflows/input-from-file.md index 8f203ce..68b3a54 100644 --- a/docs/workflows/input-from-file.md +++ b/docs/workflows/input-from-file.md @@ -17,10 +17,20 @@ MainWP Control is a command-line tool for managing your MainWP Dashboard and all ## Why Use File Input? +> **Windows users:** `--input-file` and `--input -` (stdin) work the same on every platform. Inline `--input '...'` has quoting differences on Windows that make it error-prone for anything beyond simple values. If you're on Windows, `--input-file` is the path of least resistance. +> +> **Git Bash users:** If you use Git Bash (comes with Git for Windows), all the bash examples in this guide work without changes. + +**Already using MainWP Control?** If `mainwpcontrol doctor` shows "System is ready", skip to [Step 4: Create a JSON Parameters File](#step-4-create-a-json-parameters-file). + Some MainWP Control abilities need more than a flag. For example, updating specific plugins on a specific site requires a JSON object with a site ID and a list of plugin slugs. Typing this as an `--input` flag works for simple cases: ```bash +# macOS / Linux / Git Bash mainwpcontrol abilities run get-site-v1 --input '{"site_id_or_domain": 5}' --json + +# Windows PowerShell (escape inner quotes with backslashes) +mainwpcontrol abilities run get-site-v1 --input '{\"site_id_or_domain\": 5}' --json ``` But when parameters get complex (nested objects, arrays, multiple fields), inline JSON becomes hard to read and easy to get wrong. A misplaced quote or missing comma can cause confusing errors. @@ -352,6 +362,8 @@ Expected output is the same as before: the site details as JSON. ## Step 7: Use a Heredoc for Inline Multi-line JSON +> **Windows note:** Heredocs are a bash/zsh feature and do not work in PowerShell or cmd.exe. On Windows, use `--input-file` instead. It gives you the same benefit (readable multi-line JSON in a separate file) without any platform-specific syntax. + ### What is a heredoc? A heredoc (short for "here document") is a way to write multi-line text directly inside a shell command, without creating a separate file. It is especially useful for JSON because JSON is often easier to read when spread across multiple lines. diff --git a/docs/workflows/monitoring-integration.md b/docs/workflows/monitoring-integration.md index 03346a2..e54c9e9 100644 --- a/docs/workflows/monitoring-integration.md +++ b/docs/workflows/monitoring-integration.md @@ -16,6 +16,17 @@ By the end of this guide you will have: - **One-liners** that send these metrics to StatsD/Datadog - **A monitoring script** that combines multiple metrics, handles errors, and runs on a schedule +> **Windows users:** This guide builds a bash script that uses `jq`, `nc` (netcat), and cron. None of these are available natively on Windows. +> +> Your best options: +> - **Git Bash** (comes with Git for Windows) lets you run the individual `mainwpcontrol` commands, but you'll still need to install `jq` and `nc` separately. +> - **GitHub Actions** handles everything in the cloud on Linux. See the [Monthly Batch Updates](monthly-batch-updates.md) guide (Option B) for the pattern, and adapt the metric-sending steps for your monitoring tool's API. +> - **WSL** lets you follow this guide as-is, but cron jobs inside WSL may not fire reliably unless you configure WSL to auto-start. +> +> The `mainwpcontrol` commands themselves work fine on Windows. It's the surrounding tools and scheduling that differ. + +**Already using MainWP Control?** If `mainwpcontrol doctor` shows "System is ready", skip to [Step 4: Understand the Metrics You Can Extract](#step-4-understand-the-metrics-you-can-extract). + --- ## Prerequisites diff --git a/docs/workflows/monthly-batch-updates.md b/docs/workflows/monthly-batch-updates.md index a86c108..3d64360 100644 --- a/docs/workflows/monthly-batch-updates.md +++ b/docs/workflows/monthly-batch-updates.md @@ -9,6 +9,8 @@ This guide covers two ways to automate monthly updates for every WordPress site Both options follow the same pattern: preview what will change, apply the updates, and verify the result. You only need to pick one, but the guide builds the concepts incrementally so Option B builds on what you learn in Option A. +**Already using MainWP Control?** If `mainwpcontrol doctor` shows "System is ready", skip to [Understanding the Safety Model](#understanding-the-safety-model). + --- ## What You'll Set Up @@ -167,6 +169,8 @@ The typical flow in any script is: --- +> **Windows users:** Option A builds a bash script with cron, which needs macOS or Linux. If you're on Windows, skip to **Option B: GitHub Actions**. It runs on Linux in the cloud and works regardless of your local OS. + ## Option A: Scripted Updates This section builds a bash script step by step. Each step introduces one concept, shows the command, and explains the output. At the end, everything is combined into a complete script. diff --git a/docs/workflows/plugin-deployment-verification.md b/docs/workflows/plugin-deployment-verification.md index 9f08a9b..d2de059 100644 --- a/docs/workflows/plugin-deployment-verification.md +++ b/docs/workflows/plugin-deployment-verification.md @@ -6,6 +6,8 @@ When you manage dozens (or hundreds) of WordPress sites through MainWP, it is ea You do not need prior experience with command-line tools, GitHub Actions, or scripting. Every concept is explained the first time it appears. +**Already using MainWP Control?** If `mainwpcontrol doctor` shows "System is ready", skip to [Step 4: Add Secrets to Your GitHub Repository](#step-4-add-secrets-to-your-github-repository). + --- ## What You'll Set Up @@ -91,6 +93,14 @@ Expected output: You should see `@mainwp/control/` followed by a version number. If you see `command not found`, make sure Node.js 20+ is installed and try opening a new terminal window. +> **Windows PowerShell note:** When running `mainwpcontrol` locally with `--input`, you need to escape the inner double quotes: +> +> ```powershell +> mainwpcontrol abilities run get-site-plugins-v1 --input '{\"site_id_or_domain\": 1}' --json +> ``` +> +> The GitHub Actions workflow runs on Linux, so this quoting issue only affects local testing. You can also use `--input-file params.json` to avoid it entirely. + --- ## Step 3: Authenticate (Local Verification)