DEV Community: Susumu Takahashi

"not a valid OPENSSH private key file" — building a compat layer for seven SSH private-key formats

Susumu Takahashi — Sat, 20 Jun 2026 02:29:48 +0000

If you wire SSH into WordPress maintenance automation, you'll meet this error sooner or later:

SSHException: not a valid OPENSSH private key file

"I configured the key file — why?" is the usual reaction. Tracing several real SSH-connection-test failures, the root issue becomes clear: paramiko alone can't read SSH private keys outside the OpenSSH format.

In production, hosting providers and key-generation tools produce different formats, and paramiko's standard loader rejects many of them. Here's the design of a "seven-format compat loader" we built to handle this.

Far more SSH key formats than you'd guess

"SSH key" usually conjures up -----BEGIN OPENSSH PRIVATE KEY-----, but in practice the keys you receive fall into:

OpenSSH new format (-----BEGIN OPENSSH PRIVATE KEY-----)
PKCS#1 RSA (-----BEGIN RSA PRIVATE KEY-----)
SEC 1 EC (-----BEGIN EC PRIVATE KEY-----)
PKCS#8 plain (-----BEGIN PRIVATE KEY-----)
PKCS#8 encrypted (-----BEGIN ENCRYPTED PRIVATE KEY-----)
Legacy PEM encrypted (-----BEGIN RSA PRIVATE KEY----- + Proc-Type: 4,ENCRYPTED)
PuTTY .ppk (v2 / v3 — common from Windows users)

paramiko.from_private_key_file() handles OpenSSH and PKCS#1, but PKCS#8 and .ppk are out of scope. For instance, Sakura Internet's control-panel option to "generate and register a key pair" currently produces ECDSA + PKCS#8 — and paramiko's regex rejects it outright.

The approach — let `cryptography` pre-read it, then re-serialize as OpenSSH

Extending paramiko directly is hard, so the compat loader takes a detect → normalize → hand off to paramiko approach. We added core/ssh_key_loader.py:

def load_any_ssh_key(path: str, passphrase: str | None = None) -> paramiko.PKey:
    """
    Load one of seven SSH private-key formats and normalize to paramiko.PKey.
    Supported: OpenSSH / PKCS#1 RSA / SEC 1 EC / PKCS#8 plain /
               PKCS#8 encrypted / legacy PEM encrypted / PuTTY .ppk (v2 / v3)
    """
    raw = open(path, "rb").read()
    fmt = _detect_format(raw)
    pem_openssh = _to_openssh_pem(raw, fmt, passphrase)
    return paramiko.RSAKey.from_private_key(io.BytesIO(pem_openssh))

_detect_format() looks at the first bytes, PEM headers, and the PuTTY-specific PuTTY-User-Key-File-2/3: line to identify which of the seven formats it is. After detection, the cryptography library reads the key object and re-serializes it as an OpenSSH-compatible PEM, which then gets handed to paramiko. From paramiko's perspective, it's always "the OpenSSH format I know."

PuTTY .ppk — a hand-rolled parser, no extra dependency

PuTTY's .ppk is supported by neither paramiko nor cryptography, so it gets a dependency-free, hand-rolled parser:

v2: SHA1 + HMAC-SHA1 authentication; base64-encoded public key plus an encrypted private-key section that needs decryption
v3: Argon2id + HMAC-SHA256 (a newer KDF); different passphrase handling

The .ppk parser is about 200 lines on its own, but pulling in something like pyppk would add binary size and a separate compatibility surface to maintain. A hand-rolled parser turned out lighter operationally.

Designing the "unknown format" error

When _detect_format() matches none of the seven, the original error was a vague "format unknown" — leaving the user with no idea what to do.

Alongside the seven-format support, the error message itself was rewritten:

Could not identify the format of the key file.
Accepted formats: OpenSSH / PKCS#1 RSA / SEC 1 EC /
                  PKCS#8 / PuTTY .ppk
First bytes detected: <hex dump>
Recommended next step: regenerate an OpenSSH-format key with
  `ssh-keygen -t rsa -f new_key`, then re-register the public key
  on the server.

A consistent pattern: what arrived, what is accepted, and what to do next — three pieces in every failure case. Error messages that only say "something happened" are the biggest source of support tickets.

Takeaway — library constraints can be absorbed in a layer just in front

paramiko's narrow format support was solved by inserting a classic detect-and-normalize layer in front of it. Seven formats now look like "the same old OpenSSH key" from the app's side. The change is smaller and the regression tests are simpler than patching paramiko itself would have been.

The error-message pattern — "what arrived, what's accepted, what to do next" — is something we want to spread well beyond SSH. A library's constraints disappear from the user's view if you slip a single absorbing layer in front of it. That's the lesson worth recording from this round.

Renaming a site without losing its data — separating display name from a stable identifier

Susumu Takahashi — Thu, 18 Jun 2026 23:08:47 +0000

A client asks you to rename a site from acme-staging to the production name acme. The moment you rename it in the app, the DB backups, screenshots, and thumbnails you had been collecting all appear to disappear.

The files are still on disk, but the new directory is empty. The data hasn't carried over as "the same site." It's a trap you can fall into on day one, and we did — with our original design.

Here's how we redesigned things so renames don't orphan data.

Why the data appears to disappear — the site name was the key

The original design of WP Maintenance Manager decided file locations based on the site name.

backups/
  acme-staging/        ← DB backups for site "acme-staging"
    backup_20260101_120000.sql

screenshots/
  acme-staging/        ← Screenshots for the same site
    home_pre.png

After renaming acme-staging → acme, a new empty directory backups/acme/ gets created and starts from zero. The old directory is still there, but the app treats it as "some other site's stale data" and doesn't surface it.

Site names are natural candidates for labels, but in practice they get renamed all the time. Cleaning up client-name typos, promoting staging to production, renaming on a re-org — the reasons to rename are endless.

The fix — give every site an immutable `site_id`

Every site now carries a _id in the form site_xxxxxxxxxxxx (a UUID, 12 hex chars), and every file location now keys off that _id instead of the site name.

# core/site_id_utils.py
def generate_site_id():
    return f"site_{uuid.uuid4().hex[:12]}"

_id is assigned once and never changes. Even if the site name is renamed, the file location stays the same backups/site_a1b2c3d4e5f6/ directory — and the existing contents are still in use.

It's a classic two-layer design: the display name (site name) is separate from the internal identifier (_id).

A migration that doesn't break existing data

The hardest part was handling existing users whose data was already keyed by site name.

ensure_site_ids() is an idempotent migration:

Auto-generates and assigns _id only to sites that don't have one
Leaves sites that already have a _id untouched
Uses FileLock + tempfile + os.replace() for atomic writes, so a crash mid-write won't corrupt anything

It runs at app startup and at the entry points of site-related APIs (three paths in total). The user doesn't have to do anything — IDs are silently assigned in the background.

The file-side migration follows the same pattern. On first launch, if backups/<site_name>/ exists, rename it to backups/<site_id>/ (but if the new-format directory already exists, leave both alone). Idempotent.

Tying logs to sites — strict + compat hybrid matching

Log entries also carry a site_id now. But existing log entries don't have one — they were written before the rename.

The UI scoping feature (filter logs for a specific site) is implemented as a hybrid:

New logs (with site_id) → match by strict equality
Old logs (without site_id) → fall back to site_name compat matching

The result: logs from before and after a rename appear together in the same scope. The user never feels like "past history disappeared."

A post-release blunder

For honesty: shortly after release, we shipped a bug. The is_valid_site_id validation function had a regex that only matched the new-generation format, and rejected some legitimate existing IDs.

# the broken version
SITE_ID_RE = re.compile(r'^site_[0-9a-f]{12}$')  # exactly 12 hex

A few longer ID formats — leftovers from the migration's earlier iterations — got rejected outright, and the symptom was "every site has disappeared." The lesson is mundane but real: fully audit existing data formats before tightening validation. Adding validation after the fact is exactly where these regressions hide.

Takeaway — separating stable identifier from display name

Separating "the name displayed to humans" from "the immutable identifier" is a classic software-design pattern, but introducing it after the product is already in production is expensive. The idempotent migration, the edit-vs-duplicate ownership split, the backward-compatible validation — drop any one of these and existing user data evaporates.

Since separating site name (display) from site_id (immutable), clients can have their site names corrected, staging promoted to production, or org-rename refactoring done — all while keeping every byte of historical data tied to the same site. Designing your file locations to trust the display name 100% on day one closes that door before you even reach for it. That's the retrospective on this one.

Beyond "Update All" — selecting plugins across sites while keeping every safety mechanism on

Susumu Takahashi — Thu, 18 Jun 2026 01:04:25 +0000

"A vulnerability in Elementor was just disclosed. Several of the sites I maintain run Elementor. I need to update only Elementor across those sites today."

If you maintain WordPress sites for multiple clients, this scenario happens several times a month. Core updates and other plugin updates can wait for the regular maintenance run, but a specific plugin needs to land urgently.

The trouble is that mainstream maintenance tools don't really offer a UI for "a targeted update across multiple sites, with safety mechanisms intact." Here's how that design problem can be solved.

The limits of an industry-standard "Update All"

Most WordPress maintenance tools have an "Update All" button on each site's dashboard.

Press it, and every plugin update fires at once
If any one of them breaks the site, the industry-standard "Safe Updates" / "Atomic Updates" feature rolls everything back
There's no granularity for "update just Elementor" or "across only this subset of sites"

The structural reasons the industry converged on this design are covered in three gaps the WordPress maintenance industry still hasn't solved — the Worker-plugin-over-HTTP-API architecture constrains how fine-grained the operations can be.

The practical result: an agency task like "update only Elementor across these sites" tends to fall back to logging into each site one by one and updating manually.

What was needed was two-axis granularity (site × plugin)

WP Maintenance Manager v1.6.2 solves this with two axes of granularity:

Site axis: see, across every managed site, which plugins are due for update
Plugin axis: pick the (site × plugin) cells with checkboxes — only those combinations are updated

Instead of an "Update All" button, you get a "update only the combinations you picked" button.

Cross-site dashboard design

Opening "Plugin Updates" from the toolbar triggers an SSH-parallel scan across every managed site, surfacing all plugins that are due for update.

Results are grouped by plugin name:

Elementor — needs update on several sites (4.0.0 → 4.0.8)
  ☐ siteA.com
  ☐ siteB.com
  ☐ siteC.com

Yoast SEO — needs update on several sites (22.0 → 22.1)
  ☐ ...

At a glance, you can see which plugins are out of date on which sites. Looking at the full list of sites, you can make decisions like "update Elementor everywhere, defer Yoast for another window."

Results are cached in the browser and surface immediately even after restarting the app. The parallel SSH scan completes quickly even with a large fleet, so it's lightweight enough to check casually.

A selective update runs with the same safety mechanisms as regular maintenance

This is the key point. When you press "Update selected plugins," the underlying execution uses exactly the same safety mechanisms as a regular maintenance run:

Database backup (taken before any update)
One-plugin-at-a-time updates with HTTP checks + automatic pinpoint rollback if something breaks (implementation deep dive)
Visual check and summary email

The only difference from a regular maintenance run is that Core / theme / translation updates are skipped. Only the plugin combinations you picked actually run.

The log history and report carry a "selective update" tag, and the names of the targeted plugins are recorded. You can trace back later: "when did we push Elementor across multiple sites last month, and to which sites?" The audit trail is preserved.

Takeaway — granularity changes how operations feel

The simplicity of "Update All" is convenient, but it doesn't fit the realistic need to move only a specific plugin across multiple sites simultaneously.

The combination of cross-site dashboard + selective update + safety mechanisms preserved is what makes "a targeted, safe, multi-site update" actually work. When a single plugin's vulnerability gets disclosed, you can update just the affected sites in one action — safely.

What used to be a binary choice between "update everything" and "do nothing" becomes surgical movement with all the safety nets still on. That shifts where the line falls between emergency response and routine maintenance.

Distributing a Python desktop app on Windows and Mac — the full release pipeline

Susumu Takahashi — Wed, 17 Jun 2026 00:27:06 +0000

WP Maintenance Manager ships from a single Python codebase to both Windows and macOS. "Python is cross-platform — write once, run anywhere," the saying goes. The reality is that the distribution pipeline is completely separate per OS, each with its own pitfalls.

PyInstaller / Inno Setup / Apple Notarization / eSigner — the release cycle is a combination of OS-specific toolchains. Here's the full picture, plus what to watch out for at each step. (The choice of internal architecture, Flask + browser UI, is covered separately in why we built a desktop app on local Flask + browser UI; this post is about distributing that architecture across two operating systems.)

The per-OS pipeline at a glance

Step	Mac	Windows
Build	PyInstaller (`--target-arch x86_64`)	PyInstaller
Distribution format	`.app` bundle → `.dmg`	folder → `.exe` installer
Installer creation	`hdiutil` / `create_dmg.sh`	Inno Setup (`.iss` script)
Code signing	`codesign` + Developer ID certificate	eSigner CSC (cloud signing)
Pre-distribution validation	Apple Notarization	SmartScreen reputation buildup
Final artifact	`WP_Maintenance_Pro_X.X.X.dmg`	`WP_Maintenance_Pro_Setup_X.X.X.exe`

Both OSes share PyInstaller, but the path diverges from there. Mac sits inside Apple's review process; Windows runs through Microsoft's reputation system. They're fundamentally different ecosystems.

Mac — PyInstaller → sign → Notarization → DMG

The Intel / Apple Silicon trap

The first trap in Mac PyInstaller builds is architecture. Running pip install + python build_app.py on an Apple Silicon Mac without thinking produces native binaries (like cffi) for arm64 only — which then don't run on Intel Macs at all.

The fix is to run the entire build through arch -x86_64:

arch -x86_64 pip3 install -r requirements.txt
arch -x86_64 python3 build_app.py

That produces an .app containing only x86_64 binaries, which runs natively on Intel Macs and through Rosetta 2 on Apple Silicon — a unified distribution.

Sign inside-out

The .app PyInstaller produces contains many Mach-O binaries internally (_cffi_backend.so from cryptography, etc.). The straightforward codesign --deep approach has known compatibility issues with Hardened Runtime, so we detect Mach-O binaries with the file command and sign them individually from the inside out:

find "${APP_BUNDLE}" -type f -exec file {} \; \
  | grep "Mach-O" | cut -d: -f1 \
  | while read bin; do
    codesign --force --options=runtime \
      --entitlements "${ENTITLEMENTS}" \
      --sign "${APP_CERT}" "${bin}"
  done

# Finally, sign the whole .app
codesign --force --options=runtime \
  --entitlements "${ENTITLEMENTS}" \
  --sign "${APP_CERT}" "${APP_BUNDLE}"

Notarize via ZIP, then build the DMG

There's an empirical rule that submitting a ZIP for notarization is faster than submitting a DMG directly. Apple's backend goes through a more complex DMG analysis path; ZIP rides a simpler scan path.

ditto -c -k --keepParent "${APP_BUNDLE}" "${ZIP_PATH}"
xcrun notarytool submit "${ZIP_PATH}" \
  --keychain-profile "wpmm-notary" --wait
xcrun stapler staple "${APP_BUNDLE}"
# Then build the DMG from the stapled .app

Notarization sometimes stalls at In Progress for days. The cause is often incomplete Apple Developer Program setup — missing Tax Forms or banking information — rather than anything technical. Contacting Apple support occasionally results in a batch of stuck submissions all flipping to Accepted at once. Surprisingly often, the blocker is contractual rather than technical.

Windows — PyInstaller → Inno Setup → eSigner CSC

The Inno Setup script

On Windows, WP_Maintenance_Pro.iss is the Inno Setup script that assembles the installer. User-mode installation (no admin required) into %APPDATA%, shortcut creation, residual-file cleanup on uninstall — all defined here:

[Setup]
AppId={{B3A7F2C1-4E8D-4A9F-B2C3-D5E6F7A8B9C0}
DefaultDirName={userappdata}\{#MyAppName}
PrivilegesRequired=lowest

PrivilegesRequired=lowest installs in user mode so people without admin rights — common in corporate environments — can still install the app. The visible drop in support tickets just from avoiding the UAC dialog is noticeable.

Cloud signing with eSigner CSC

Windows code signing traditionally requires a physical USB token holding the certificate. eSigner CSC (SSL.com's cloud signing service) lets you sign from automation scripts without any token plugged in:

& "C:\esigner\CodeSignTool.bat" sign `
  -input_file_path "WP_Maintenance_Pro_Setup.exe" `
  -output_dir_path "signed/" `
  -credential_id "${CRED_ID}" `
  -username "${USERNAME}" -password "${PASSWORD}" `
  -totp_secret "${TOTP_SECRET}"

OV/EV certificate grade differences, and SmartScreen reputation buildup (you get "Unknown publisher" warnings until enough installs accumulate) are each topics of their own — but for "just getting it signed and shipping," eSigner CSC automation is the practical path.

The cross-cutting challenge — version synchronization and reproducibility

The recurring headache on every release is version number synchronization. version.py, MyAppVersion in WP_Maintenance_Pro.iss, server/wpmm-web/version.json, the LP download links — four or more files all need to match per release. If one drifts, you get bugs like "the new version is live, but the in-app update check doesn't notice."

release.py exists as a single-shot updater, but as files get added over time the script needs to be kept in sync. A release checklist remains essential.

Reflection — "the same Python," distributed completely differently

"Cross-platform" sounds simple, but distribution-side work splits cleanly per OS. Binary building can be unified through PyInstaller, but installers, code signing, and OS-side validation all live in separate ecosystems — you have to follow each one's conventions.

That said, once the pipeline is built, new releases come out in about 30 minutes — python build_app.py + bash sign_and_notarize.sh + Inno Setup F9 and you're done. High initial setup cost, but easy to spin afterward — that's the lived experience of two-OS distribution.

Why we built a desktop app on local Flask + browser UI instead of PyQt or Electron

Susumu Takahashi — Tue, 16 Jun 2026 00:39:16 +0000

When you double-click WP Maintenance Manager, it opens a browser tab — and the entire UI lives inside that tab. No native window is created. It's an unusual structure for a first-time user, and the natural question is: "why a browser?"

That choice was an intentional design decision when building a Python desktop application. Here's the comparison that led to it, and the side effects of the choice.

Four realistic options

For a WordPress maintenance automation tool, four implementation styles were practical:

Approach	UI	Distribution size	Dev cost	Per-OS extra work
Native (Swift / WPF)	OS-native windows	Small–medium	High (separate impl per OS)	Heavy
PyQt / PySide	Qt widgets	Medium (~80 MB)	Medium	Light
Electron	Chromium-embedded web UI	Large (~150 MB+)	Medium	Light
Local Flask + system browser	System browser tab	Small (~50 MB)	Medium	Light

PyQt was a serious early candidate. A Python-only stack is appealing, but widget styling drifts subtly between OSes, Qt's layout system demands constant attention, and resolving Qt plugins under PyInstaller is fiddly. Dev velocity was not where it needed to be.

Electron is the industry-standard choice for cross-platform UI, with the big benefit that HTML/CSS-based UIs are quick to write. But the distribution is well over 100 MB, and memory consumption is heavy. For a tool that often runs in the background, that overhead is too much to justify.

Why local Flask + browser won

The final structure was Flask (Python's lightweight web framework) + the system browser for UI. The decision rested on three axes:

1. The backend had to be Python anyway

SSH connections via fabric / paramiko, browser automation via playwright, encryption via cryptography — every library at the core of WordPress maintenance lives in the Python ecosystem. Writing the backend in another language wasn't really an option. If Python is already required on the backend, putting the UI in Python too keeps distribution simple.

2. HTML/CSS/JS makes UI iteration fast

Flask renders templates/index.html, and the UI is built with Tailwind CSS and vanilla JS. Anyone with web-development experience can ship features quickly. Learning a new native widget vocabulary every time slows iteration far more than this approach does.

3. Distribution is about 1/3 the size of Electron

By not bundling Chromium, the PyInstaller artifact lands around 50 MB. The same Python codebase and the same templates/ directory power both the macOS .app and the Windows .exe. Almost no per-OS extra work — that was the biggest practical win.

The side effects of using a browser

This structure comes with a tax. The browser tab is the UI. If the user closes that tab, the app is still running, but there's no way to reach it. Double-clicking the app again to reopen it doesn't help, because macOS LaunchServices sees "this app is already running" and just refocuses it, without opening a new browser tab.

Fixing this required a heartbeat-based liveness check combined with a self-clobbering lockfile. (Details in when a macOS desktop app refuses to restart.)

There are other side effects too: a fixed port is occupied (so port-collision detection is needed), browser private mode breaks the login session, and so on. None of these would have existed with a native window.

Reflection — structure choice is requirement-dependent

"Local Flask + browser UI" is not a universal best choice. For apps that lean heavily on native UI components (notification center, menu-bar residency, keychain integration), or where startup happens frequently in offline-only contexts, PyQt or Native make more sense.

But under the constraints WordPress maintenance automation actually had — backend-heavy, dashboard-style UI, small distribution, mandatory two-OS support — Flask + browser was the right balance. We optimized for dev velocity and distribution size, accepting other trade-offs.

The side effects need separate, careful handling. Even so, the structure has more than paid for itself across the lifetime of the project.

Pinpoint rollback — building per-plugin revert with WP-CLI

Susumu Takahashi — Sun, 14 Jun 2026 23:35:48 +0000

You batch-update 20 plugins, and one breaks the site. Most WordPress maintenance tools play it safe and roll back all 20 updates (variations on "Safe Updates" or "Atomic Updates"). It's a reasonable default.

But running in production, you start running into cases where you want only the broken one reverted, and the other 19 to keep their updates. Here's how that design is built on top of WP-CLI.

The command that makes it possible — `wp plugin install --version=X --force`

WP-CLI has a powerful command for "install a plugin at a specific version, overwriting whatever's currently there":

wp plugin install <plugin-slug> --version=1.2.3 --force --skip-plugins --skip-themes

What each flag does:

--version=1.2.3 — Specifies the older version to install (any version published on WP.org works)
--force — Overwrites if the plugin is already installed
--skip-plugins --skip-themes — Skips plugin/theme loading at WP-CLI startup, so WP-CLI itself doesn't crash even when a broken plugin is present (covered in a separate post)

That one line is enough to roll back a single plugin to a known-good version. The remaining design question is when and under what conditions to invoke it.

Combining with HTTP checks

Step-by-step updates with HTTP status checks between each:

Pre-update:    GET / → 200
↓
wp plugin update <plugin-slug> --skip-plugins --skip-themes
↓
Post-update:   GET / → 500   ← broken!
↓
wp plugin install <plugin-slug> --version=<previous> --force --skip-plugins --skip-themes
↓
Post-rollback: GET / → 200   ← recovered
↓
proceed to the next plugin

By switching the update granularity from "everything at once" to "one at a time + HTTP check", you get clear visibility into which plugin caused the breakage.

Identifying the rollback target

The plugin you just updated is the prime suspect — by construction. This isn't possible with bulk updates: if multiple plugins are updated together and HTTP returns 500, you can't tell which one is responsible.

The advantage of one-at-a-time updates is that the moment the HTTP status changes, the plugin updated immediately before becomes the confirmed rollback target. No risk of accidentally reverting an unrelated plugin.

The previous version comes from a pre-update snapshot:

# Capture before updates start
wp plugin list --format=json --skip-plugins --skip-themes > /tmp/plugins_before.json

# Look up the previous version of the failed plugin
prev_version=$(jq -r '.[] | select(.name=="<slug>") | .version' /tmp/plugins_before.json)

That gives you the version string to feed back into wp plugin install --version=<prev>. Roll back, verify, proceed to the next plugin.

Verifying recovery — always re-check HTTP after a rollback

After rolling back, take the HTTP status again:

✅ Back to 200 → skip the update for this plugin, continue to the next
❌ Still 500 → the rollback didn't recover the site (the broken state is in the DB schema or other files, not just the plugin's PHP) → escalate to heavier recovery (full DB rollback, cache flush, theme fallback, etc.)

The lesson: don't assume rolling back the plugin always fixes things. --force overwriting only replaces files; DB-side inconsistencies need separate detection.

Takeaway — "roll back all" vs "roll back one"

The industry-mainstream "roll back everything" design is simpler to implement and errs on the safe side — and there are good reasons it's the default. On the other hand, the "roll back only the one that broke" design has these operational advantages:

The culprit is recorded directly in the log
Successful updates to other plugins are preserved
At the next maintenance run, only the rolled-back plugin needs retrying

A trade-off: more implementation complexity, in exchange for higher operational transparency and continuity.

The small WP-CLI command --version=X --force is what makes this possible. For anyone considering maintenance automation on shared hosts where SSH + WP-CLI is available, this flag combo is worth committing to memory.

For the structural reasons the industry as a whole hasn't adopted per-plugin rollback, see also three gaps the WordPress maintenance industry still hasn't solved.

Three gaps the WordPress maintenance industry still hasn't solved — from a survey of four major tools

Susumu Takahashi — Sat, 13 Jun 2026 03:45:43 +0000

WordPress maintenance automation has a long-running market, especially outside Japan. ManageWP, MainWP, WP Umbrella, InfiniteWP — each has more than a decade of history behind it.

While building our comparison pages, we surveyed all four side by side. An interesting pattern emerged: three things none of the four tools offer.

Each is a gap the industry has long treated as "not feasible," and there are structural reasons why. Here's a look at those three unsolved areas — and why they remain unsolved.

Gap 1 — Per-plugin updates with HTTP checks between each one

In most maintenance tools, plugin updates run in bulk. After the batch, the tool takes a sitewide screenshot diff or HTTP status check, and if anything is broken, "Safe Updates" or "Atomic Updates" features roll everything back at once.

Why isn't "one at a time with an HTTP check between each" the standard? The main reason is API design constraints. WordPress's built-in wp_ajax_update-plugin and Worker-plugin APIs (like ManageWP Worker) are designed around batch processing. Doing an HTTP probe from an external host after every single update would add significant per-update overhead. The industry has settled on "bulk update → bulk check" as the natural granularity.

The side effect: identifying which plugin caused the breakage often falls to the operator's manual investigation.

Gap 2 — Pinpoint rollback (only the one that broke)

The industry-standard "Safe Updates" feature is fundamentally a "roll back everything" design. If 20 plugins are batched together and one breaks the site, all 20 updates revert. It's a safety-first choice — but operationally, it means the 19 that finished cleanly are also lost.

Why isn't pinpoint rollback (revert only the one that broke) the standard? The root cause is state-management complexity. To pinpoint rollback, you need to keep the pre-update files of each plugin individually. Storage, transfer cost, and dependency consistency checks become impractical over a Worker-plugin HTTP API. "One whole-site snapshot, restore once" is far simpler to implement and operate, which is where the industry converged.

WP-CLI-based approaches change the math here — but as the next section explains, WP-CLI itself isn't the industry mainstream, which limits how widely this alternative spreads.

Gap 3 — Reaching client sites without installing an extra plugin

This is the most structural gap. All four tools require a Worker / Child plugin installed on each client site. ManageWP Worker, MainWP Child, Umbrella, InfiniteWP Client — the names differ, but every tool ships a "gateway plugin" that lives on each managed site.

Why has the industry adopted this? It's about connectivity and compatibility guarantees. Shared hosts are extremely varied — SSH availability, WP-CLI presence, and firewall configuration all differ. A WordPress-internal gateway plugin lets the tool reach every site through a uniform HTTP API. It's the pragmatic industry solution.

But it comes with side effects:

The client site permanently hosts a "maintenance-vendor management plugin"
If that plugin develops a vulnerability, every client is affected
Clients eventually ask "what is this plugin?" — which needs an explanation
If the plugin gets deleted (e.g., on contract termination), the site disappears from the tool's management view

Whether to accept these trade-offs, or to choose a different connection model entirely, ends up being a quietly important axis when selecting a maintenance tool.

Takeaway — should the industry's premises be questioned?

What these three unsolved gaps share is that they're areas the industry has long agreed are "good enough as is." The combination of "bulk update + whole-site rollback + Worker plugin" is technically and commercially stable. The fact that four major tools have run on this same structure for over a decade speaks to the design's maturity.

That said, alternative approaches that question those industry premises do exist. Using SSH + WP-CLI sidesteps the API overhead, making step-by-step updates and pinpoint rollback practical, and removing the need for a Worker plugin. The trade-off: the target narrows to shared hosts where SSH is available, and the operator needs some familiarity with SSH fundamentals.

It's not a question of which is "right" — it's that the operating style and constraint mix lead to different fits. Whether you pick the industry-mainstream "Worker + bulk + whole-site rollback" model or step outside it, awareness of these three unsolved areas gives you a clearer frame for asking what actually matters to your own maintenance operation.

After a core rollback, halt the rest — a safety design we arrived at the hard way

Susumu Takahashi — Fri, 12 Jun 2026 00:23:25 +0000

In WordPress maintenance automation, you inevitably run into points where you have to decide: keep going, or stop right here? One that took us a long time to get right was this: when a WordPress core update goes wrong and gets rolled back, should the remaining plugin updates continue, or stop?

We eventually switched to the "stop" design, but we started with "keep going" — and several traps surfaced only after running it in production. Here's how the redesign happened.

Three cases to separate

The outcome of a core update, viewed through a rollback lens, falls into three patterns:

Case 1: Core rollback succeeded, site recovered — the site is healthy again after the RB
Case 2: Core rollback succeeded, but site did not recover — the RB ran, but the site is still broken
Case 3: Core rollback itself failed — the RB couldn't even complete

Case 1 is clearly "keep going," and Cases 2/3 are clearly "abnormal." But what to do next isn't as simple as that framing suggests.

The old design — disable the HTTP check and continue

The original design kept maintenance running through Cases 2 and 3:

_skip_http_check = True   # disable HTTP check after a core anomaly, keep going
# remaining plugin / theme / translation updates still run

The reasoning was: "Once core is broken, of course a plugin update will return 5xx — so disable the HTTP check, and we won't mistakenly roll back unrelated plugins."

In practice, this did reduce false-positive rollbacks. But as the tool ran in real environments, two problems emerged.

Two problems that surfaced

Problem (a): broken state plus piled updates = untraceable

If 20 plugins are updated while core is still broken, the log records "20 updates succeeded." The site is still broken, but the log reads as healthy.

The next day, when the agency tries to trace "where did it break?" — there's no way to tell whether core was the cause, one of the later updates was, or some combination of them. A safety mechanism intended to reduce noise was actually inflating investigation cost.

Problem (b): genuine plugin failures became invisible

Setting _skip_http_check = True disables the HTTP check uniformly — including for plugin-side bugs that have nothing to do with core (memory leaks, dependency conflicts, PHP version incompatibility).

What was supposed to be "skip the HTTP check while core is broken" was actually "make all anomalies in this window invisible." That's equivalent to intentionally disabling a safety device.

The new design — halt in Cases 2 and 3

Based on these problems, Cases 2 and 3 now stop all subsequent plugin / theme / translation updates entirely.

if _halt_remaining:  # set to True in Case 2 / 3
    # record step_rollbacks first, then early return
    return

The key is that this isn't just "stop and walk away":

step_rollbacks records are kept — the full record of what happened stays in the log
The outer visual_check / browser_automation / email notification still run — final HTTP confirmation and the alert to the agency are still guaranteed
Reports are still generated after the early return — the message "stopped after core rollback" appears in the client-facing report too

Case 1 (RB succeeded + recovery confirmed) continues as before. The site is healthy again, so the precondition for safely running the remaining plugin updates with HTTP checks is intact.

The trade-off we accepted

This change means "if core breaks today, all subsequent updates for the day stop." A scheduled batch of 20 plugin updates gets deferred to the next maintenance run if a single core rollback happens. In the short term, that feels inconvenient.

But in real operation:

The agency receives a clear signal: "fix core before retrying"
The next maintenance job resumes from a healthy state
The log carries an unambiguous "halted after core rollback" trace

These three together — at the cost of skipping that day's plugin updates — give operationally far more traceable behavior than the silently-continues-while-broken alternative.

Takeaway — safety devices need to be left on

Designs that "disable the check during abnormal conditions" can look clever but tend to make anomalies invisible. Stopping the moment something abnormal is detected, and handing the decision back to the agency, generally gives more predictable behavior across the workflow.

When a maintenance-automation design choice is hard to settle, a useful heuristic is: don't try to fix it automatically — communicate it clearly to a human. Surprisingly often, that's what saves the operation.

InfiniteWP's Strengths and Who It Fits — An Honest Review from a Competing Tool Builder

Susumu Takahashi — Thu, 11 Jun 2026 00:22:25 +0000

Among WordPress maintenance tools, InfiniteWP is one of the most established names. Released by Revmakx in 2011, the tool has been operated continuously for over a decade. It enjoys deep loyalty from agencies that have invested years building operational know-how around it.

We at WP Maintenance Manager take a different approach, and our comparison pages outline where the two diverge. But before talking about differences, the strengths of InfiniteWP deserve to be stated honestly.

Here are the five points where InfiniteWP fits an agency particularly well.

1. Over a decade of operational track record

InfiniteWP's biggest structural advantage is trust built across more than a decade of continuous operation.

Released in 2011 — one of the oldest tools in the space
A large base of long-time English-speaking users with shared operational patterns
Well-defined upgrade paths from older versions
Backward compatibility with existing workflows and scripts has been maintained for years

For agencies already invested in InfiniteWP, switching tools means more than "migration work" — it means rebuilding the operational know-how accumulated over years. Continuing to use a tool with proven track record is, in itself, a strength that long-running platforms have.

The temporal depth that newer tools simply cannot replicate is a meaningful selection reason for conservative industries — those reluctant to substantially change established workflows.

2. Self-hosted — full control of the dashboard

InfiniteWP is self-hosted by default, letting you place the dashboard on your own server (a cloud-hosted version is available separately).

Host on infrastructure you own
Complete data ownership
No dependency on external SaaS
Arbitrary customization possible

When the constraint is "client data must not sit in a third-party SaaS" or "our security policy doesn't permit SaaS," InfiniteWP's self-hosted architecture is a direct answer. If your team has experience operating PHP / WordPress infrastructure, the operational overhead is manageable.

The cloud-hosted version is also available, so "start in the cloud, move to self-hosted as you grow" is achievable within the same tool — a flexibility most competitors don't match.

3. Modular — pick only the add-ons you need

InfiniteWP uses a modular add-on model.

Core features (updates, backups, basic management) are free
Add only the extensions your operation actually needs
Per-add-on licensing
You don't pay for features you don't use

Instead of "bundle me everything because I want feature X," you can selectively pick only what you actually use. This precision aligns well with operating philosophies that aim to keep tools minimal and waste-free.

For large-scale operations managing many sites, the per-add-on model makes it easier to optimize total tool cost by including only what's necessary.

4. Browser-based access despite self-hosting

Even though it's self-hosted, the dashboard is a WordPress plugin-based UI, so it remains accessible through any browser.

Same operation from phone, tablet, or multiple PCs
Access from client sites or during travel
Shared use across multiple developers

The "I don't want to be tied to a specific PC" advantage of cloud tools — while staying on a self-hosted architecture. A reasonable middle ground for teams that want both data sovereignty and access flexibility.

5. Annual licensing — predictable budgeting

InfiniteWP's add-on pricing uses annual licensing (starting at $147/year, cloud-hosted version at $597/year).

Single-fiscal-year expenditure
Easy to classify as "annual operational cost" in accounting
No monthly subscription micromanagement
High predictability for budget planning

For organizations suffering from "subscription fatigue" — or operating under strict annual budgeting cultures — the annual licensing model is itself a procurement-friendly trait.

In cases where parent-company accounting rules require "contracts that complete within a fiscal year" (such as financial subsidiaries or public-sector affiliated entities), annual licensing can become a hard selection criterion.

What kind of agency InfiniteWP fits

Putting it together, InfiniteWP fits a team with these traits:

Has used InfiniteWP for years (continuity of operational know-how)
Wants to control the dashboard via self-hosting
Wants to pick only the features (add-ons) actually needed
Annual licensing fits the accounting / budgeting culture
Wants browser-based access flexibility

If three or more of these apply, InfiniteWP belongs on your shortlist.

How we're different

WP Maintenance Manager takes a different shape.

Where InfiniteWP is a self-hosted dashboard built as a WordPress plugin, WP Maintenance Manager is a desktop application (Mac & Windows) using SSH + WP-CLI to reach client sites.

That trade-off gives up InfiniteWP's "access from anywhere" and "incremental expansion via add-ons" flexibility. In exchange:

No dashboard server to operate (it runs on your local PC — no separate WordPress install to maintain)
No Client plugin on client sites (SSH-native, so no Worker / Client plugin is needed)
Pinpoint rollback — if a single plugin update breaks the site, only that one is reverted while the rest of the maintenance continues (standard, not an add-on)

Pricing models also differ. InfiniteWP uses annual licensing; WP Maintenance Manager uses a monthly model. Annual licensing favors long-term budget planning; monthly pricing favors short-term trials and easy scaling.

This isn't "which is better." It's which operating style each fits. Self-hosted, modular, annual-license operations → InfiniteWP. SSH-based, PC-centric, dashboard-overhead-averse operations → WP Maintenance Manager. That's the natural split.

For a more detailed comparison

A 12-item objective spec table, pricing model breakdown, parallel-trial steps, and decision-frame analysis are on our comparison page:

→ WP Maintenance Manager vs InfiniteWP — Objective Spec Comparison

Use it not as a single-tool review, but as input for deciding which fits your operating style.

Summary

InfiniteWP is a remarkably strong tool for agencies that prioritize long-running operations, self-hosting, and annual licensing. Over a decade of stable operation, a flexible self-hosted architecture, and a modular add-on catalog give it qualities newer tools simply cannot replicate.

Every maintenance tool has the operating style it fits. InfiniteWP — established, self-hosted, annually licensed — deserves to top the shortlist for teams that value operational continuity and budget predictability. WP Maintenance Manager's desktop + SSH approach fits a different operating style.

The best path is to evaluate several candidates against the operating style of your own team.

WP Umbrella's Strengths and Who It Fits — An Honest Review from a Competing Tool Builder

Susumu Takahashi — Tue, 09 Jun 2026 13:38:36 +0000

Among WordPress maintenance tools, WP Umbrella has built strong traction with EU-based agencies. Launched in 2020 from France, this relatively young SaaS tool has rapidly grown its user base by anchoring its identity around three pillars: strict GDPR operations, EU data residency, and continuous uptime monitoring — all wrapped in a notably modern interface.

We at WP Maintenance Manager take a different approach, and our comparison pages outline where the two diverge. But before talking about differences, the strengths of WP Umbrella deserve to be stated honestly.

Here are the five points where WP Umbrella fits an agency particularly well.

1. EU data residency and strict GDPR compliance

WP Umbrella's biggest structural advantage is that the servers, the data, and the operating company are all within the EU.

Operating company: based in France
Data centers: within the EU
Legal framework: full GDPR compliance
Architected to be outside the reach of the U.S. CLOUD Act

For European companies, public-sector organizations, and educational institutions, "we cannot place client data with a U.S.-based SaaS" is not a rare constraint. Beyond simply offering GDPR-compliant settings, WP Umbrella is structurally built so EU data residency is guaranteed.

For organizations operating under EU regulations, this isn't a preference — it's a compliance prerequisite that maps directly onto procurement decisions.

2. Continuous uptime monitoring as a core feature

WP Umbrella positions uptime monitoring as a central piece of value, not as an add-on. It comes standard with every plan.

Site checks at 1-minute intervals
Immediate email and Slack notifications on downtime
Continuous performance (response time) tracking
HTTPS certificate expiration monitoring

This stands in contrast to the "check during maintenance" approach common in other tools. With WP Umbrella, 24×7×365 continuous monitoring is the default assumption. For agencies running e-commerce sites, booking systems, or contact forms — anything where downtime equates to lost transactions — that continuous coverage is direct value.

3. Daily file-level backups

WP Umbrella performs daily backups of both database and files. Many maintenance tools default to "daily DB, weekly files." Standard daily full backups (DB + files) are notable in this space.

Daily full (DB + files) backups across all plans
30 days of retention
Incremental diffs to reduce transfer overhead
One-click restore

Knowing — at daily granularity — when each file was uploaded and by which client is particularly valuable for media-heavy sites or content-driven operations.

4. Modern, anywhere-accessible SaaS UI

Being SaaS, WP Umbrella is browser-based and accessible from anywhere on any device.

Same operational feel on phone, tablet, or laptop
Built for shared editing and collaborative operations
No dashboard startup cost (just log in)

The UI is widely praised as one of the most polished in the maintenance-tool category. The modern, Linear- or Notion-inspired interface resonates particularly well with creative-leaning agencies that care about tool aesthetics.

If the dashboard is going to be part of daily work, UI quality translates directly into productivity.

5. Simple, predictable pricing

WP Umbrella uses flat per-site pricing, starting at €1.99 per site per month.

All features included; no separate add-on charges
Pricing scales by site count (not by team members)
No granular per-feature billing
Easy to trial and scale up or down

For teams that want to avoid the complexity of "X add-on for feature Y, plan upgrade for team size Z," the simplicity of WP Umbrella's pricing is decision-making clarity in itself.

For small-to-mid agencies managing roughly 30–100 sites, the monthly rate also falls into a reasonable range.

What kind of agency WP Umbrella fits

Putting it together, WP Umbrella fits a team with these traits:

Handles client data inside the EU (GDPR-strict operations required)
24×7 uptime monitoring is part of the SLA
Daily file-level backups are required
Prefers a SaaS model accessible from anywhere
Values a polished, modern UI
Prefers a simple per-site pricing model

If three or more of these apply, WP Umbrella belongs on your shortlist.

How we're different

WP Maintenance Manager takes a different shape.

Where WP Umbrella is an EU-based cloud SaaS, WP Maintenance Manager is a desktop application (Mac & Windows) using SSH + WP-CLI to reach client sites.

That trade-off gives up WP Umbrella's "continuous uptime monitoring" and "access from anywhere" advantages. In exchange:

No additional plugin installed on client sites (SSH-native, so no Worker / Child plugin is needed)
Client data stays encrypted on your own PC (no client information passes through the cloud)
Pinpoint rollback — if a single plugin update breaks the site, only that one is reverted while the rest of the maintenance continues

This isn't "which is better." It's which operating style each fits. EU data residency, 24×7 monitoring, SaaS access → WP Umbrella. SSH-based, PC-centric, self-held data → WP Maintenance Manager. That's the natural split.

For a more detailed comparison

A 12-item objective spec table, pricing model breakdown, parallel-trial steps, and decision-frame analysis are on our comparison page:

→ WP Maintenance Manager vs WP Umbrella — Objective Spec Comparison

Use it not as a single-tool review, but as input for deciding which fits your operating style.

Summary

WP Umbrella is a remarkably strong tool for agencies that prioritize EU data residency, continuous uptime monitoring, and a polished interface. A structurally GDPR-compliant design, daily file-level backups, and simple per-site pricing give it a distinctive position among SaaS maintenance tools.

Every maintenance tool has the operating style it fits. WP Umbrella, with EU residency and continuous monitoring as core strengths, deserves to top the shortlist for teams running strict GDPR operations or 24×7 SLAs. WP Maintenance Manager's desktop + SSH approach fits a different operating style.

The best path is to evaluate several candidates against the operating style of your own team.

MainWP's Strengths and Who It Fits — An Honest Review from a Competing Tool Builder

Susumu Takahashi — Mon, 08 Jun 2026 01:59:27 +0000

Among WordPress maintenance tools, MainWP stands out as the leader for agencies with a strong open-source bias. Founded in 2013, fully GPL-licensed, and architected so that the dashboard itself runs on your own WordPress installation, MainWP holds a distinctive position in the market — one shaped by the trust that comes from readable code and self-hosted data ownership.

We at WP Maintenance Manager take a different approach, and our comparison pages outline where the two diverge. But before talking about differences, the strengths of MainWP deserve to be stated honestly.

Here are the five points where MainWP fits an agency particularly well.

1. Fully open source (GPL) — you can read the code

MainWP's biggest structural advantage is that its core is fully GPL-licensed open source.

Source code is published on GitHub
You can fork and customize it yourself
Security audits can be conducted in-house or by third parties
The risk of vendor lock-in is structurally low

For industries where "we can't contract for tools whose internals are a black box" is a real constraint (finance, healthcare, public sector), and for organizations whose engineers actually read source to audit, MainWP's transparency becomes a direct selection reason.

With closed-source SaaS, "we don't know what's happening inside" is unavoidable. With MainWP, the verification you need is verification you can do yourself. That's a structural strength no closed competitor can match.

2. Self-hosted — you keep complete control of the dashboard

MainWP's other defining trait is that the dashboard itself runs as a WordPress plugin installed on your own WordPress site. There's no need to entrust data to an outside SaaS.

The dashboard lives on infrastructure you own
Client site info and credentials don't pass through a third party
Data sovereignty stays entirely with you
You're insulated from third-party outages, acquisitions, and shutdowns

When the constraint is "client data must not sit in a third-party SaaS" or "our security policy doesn't permit SaaS," MainWP's self-hosted architecture is the direct answer. If your team has any experience running its own infrastructure, the operational overhead is manageable.

3. Lifetime licensing is available

For organizations tired of subscription sprawl, MainWP's Pro Lifetime license at $599 (or Pro at $29/month) is a meaningful option.

Pay once, use forever (Lifetime tier)
Easier to capitalize on the books
No monthly billing to manage
Long-term budget becomes predictable

For organizations whose budget policies prefer "expenses that complete within a fiscal year" or "fewer subscriptions overall," simply having the buy-once option is a differentiator. Over a 5–10 year horizon, total cost favors lifetime models for long-running operations.

4. Browser-based dashboard — accessible from anywhere

Despite the self-hosted architecture, the dashboard is browser-based, so you keep the "access from anywhere" benefit:

From phone or tablet
From a client site or while traveling
For multiple developers working together

For "I don't want to be tied to a specific PC" needs, MainWP delivers. Self-hosted on the data side, cloud-like on the UI side — the design balances ownership with convenience.

5. Modular — pick only the extensions you need

MainWP is modular: features are delivered as discrete extensions. Core capabilities (updates, backups, basic monitoring) are free, and you add only the extensions your operation actually needs through the Pro tier.

Need staging? → Staging Extension
Need detailed reports? → Pro Reports Extension
Need security scanning? → WordFence Extension

Instead of "everything bundled for a monthly fee," you configure exactly what your operation requires. The same product accommodates a minimal setup and a fully equipped one, which is a flexibility most all-in-one tools don't offer.

What kind of agency MainWP fits

Putting it together, MainWP fits a team with these traits:

Open source matters as a policy
You want to manage the dashboard on your own infrastructure
Lifetime licensing or long-horizon budgeting is preferred
Security requirements rule out SaaS
You want to pick only the features you need (avoid forced bundles)

If three or more of these apply, MainWP belongs on your shortlist.

How we're different

WP Maintenance Manager takes a different shape.

Where MainWP is a self-hosted dashboard built as a WordPress plugin, WP Maintenance Manager is a desktop application (Mac & Windows) using SSH + WP-CLI to reach client sites.

That trade-off gives up MainWP's "access from anywhere" and built-in multi-user collaboration. In exchange:

No dashboard server to operate (it runs on your local PC — no separate WordPress install to maintain)
No Child plugin on client sites (SSH-native, so no Worker / Child plugin is needed)
Pinpoint rollback — if a single plugin update breaks the site, only that one is reverted while the rest of the maintenance continues

This isn't "which is better." It's which operating style each fits. Open source, self-hosted, team-oriented operations → MainWP. SSH-based, PC-centric, dashboard-overhead-averse operations → WP Maintenance Manager. That's the natural split.

For a more detailed comparison

A 12-item objective spec table, pricing model breakdown, parallel-trial steps, and decision-frame analysis are on our comparison page:

→ WP Maintenance Manager vs MainWP — Objective Spec Comparison

Use it not as a single-tool review, but as input for deciding which fits your operating style.

Summary

MainWP is a remarkably strong tool for agencies that prioritize open source, self-hosting, and lifetime licensing. A decade of track record, GPL transparency, and a stable community give it qualities no SaaS-only competitor can replicate.

Every maintenance tool has the operating style it fits. MainWP, with its emphasis on transparency and ownership, deserves to top the shortlist for teams that need data sovereignty and source-readable code. WP Maintenance Manager's desktop + SSH approach fits a different operating style.

The best path is to evaluate several candidates against the operating style of your own team.

'Command not found' — and what's really blocking WP-CLI

Susumu Takahashi — Sat, 06 Jun 2026 05:13:30 +0000

"I downloaded wp-cli.phar, uploaded it to ~/bin/wp, SSH'd in, and ran wp. Got -bash: wp: command not found. The file is right there. Why?"

If you've set up WP-CLI on a shared host using a browser-based file manager, you may have hit exactly this. The file exists, permissions are 755, size is 6.8 MB (matches the official PHAR). And yet it refuses to run. The "command not found" message can hide an entirely different problem underneath.

The file is there, but nothing runs

After SSHing in, you can confirm the file exists:

$ ls -la ~/bin/wp
-rwxr-xr-x 1 c1234567 c1234567 7142777 May  8 10:00 /home/c1234567/bin/wp

$ wp --info
-bash: wp: command not found

You might suspect ~/bin isn't on PATH (the environment variable that lets you run a command by name alone). But calling it by absolute path gives a different, more telling error:

$ ~/bin/wp --info
-bash: /home/c1234567/bin/wp: cannot execute binary file

"Cannot execute binary file" — at this point, something is wrong with the file itself, not just the shell setup.

The real cause — a PHAR `broken signature`

WP-CLI ships as a single PHAR file (wp-cli.phar) — a PHP archive format that bundles all of WP-CLI's code into one self-contained executable. PHARs carry a SHA1 signature inside, and PHP verifies that signature when loading the archive. If the bytes don't match what was signed at build time, loading is refused.

Running wp through php directly surfaces the error that was hidden until now:

$ php ~/bin/wp --info
Fatal error: Uncaught PharException: phar "/home/c1234567/bin/wp"
SHA1 signature could not be verified: broken signature in
/home/c1234567/bin/wp:3

That's the smoking gun. If a single byte of the PHAR has been altered, the archive refuses to load. Which means the PHAR that arrived on the server is not the same one that left the build server — something between download and upload changed it.

Why the browser file manager corrupts it

The typical workflow looked like this:

Download wp-cli.phar from the WP-CLI website on a Mac
Rename it to wp in Finder (drop the .phar extension)
Use the host's browser-based file manager to drag-and-drop the file into ~/bin/

Step 3 is the trap. In the file manager, a file named wp (with no extension) is shown as a text file icon, and the file properties dialog labels it "Plain Text." Without an extension, MIME detection (the mechanism a file manager uses to guess what kind of file it is) falls back to a text guess, and the upload path applies subtle byte transformations along the way — line-ending conversion, character-encoding normalization, or similar — which corrupt the binary.

We tested the same procedure across different accounts and time windows. Each upload produced a different MD5 hash (a short fingerprint string used to confirm two files have identical contents) of corruption. It's not deterministic damage; it's some kind of transformation happening in flight.

The fix — never go through the Mac

The reliable path is to SSH into the server first, then download with curl directly on the server. Neither Finder nor the file manager touches the file.

ssh -i ~/.ssh/<your-private-key.pem> -p 8022 <ssh-user>@<host> '
  mkdir -p ~/bin && cd ~/bin &&
  [ -f wp ] && mv wp wp.broken_backup_$(date +%s);
  curl -sO https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar &&
  mv wp-cli.phar wp && chmod 755 wp &&
  ~/bin/wp --info
'

This idempotent one-liner moves any existing wp to a timestamped backup before pulling a fresh PHAR. The final wp --info is the proof that it works. The whole thing takes about 30 seconds.

Takeaway — binaries go through SSH/SFTP only

Browser file managers are convenient, but they treat unfamiliar files as text by default, and transformations along the upload path can quietly corrupt binary content. WP-CLI is fortunate: the PHAR's SHA1 self-check means corruption fails loud and early. Binaries without internal integrity checks (other executables, archives, image metadata) could carry the same corruption silently into production.

There's a corollary: hash comparison alone is not enough to declare a PHAR healthy. We observed cases where two PHARs share an identical MD5 but one still fails with broken signature on first execute. The final "this works" verdict has to come from wp --info's exit status (the number a command returns to indicate success or failure — 0 means success) and its output — not from a hash.

For the broader picture of how different shared hosts ship (or don't ship) WP-CLI, see also a four-host investigation of WP-CLI architectures.

DEV Community: Susumu Takahashi

"not a valid OPENSSH private key file" — building a compat layer for seven SSH private-key formats

Far more SSH key formats than you'd guess

The approach — let cryptography pre-read it, then re-serialize as OpenSSH

PuTTY .ppk — a hand-rolled parser, no extra dependency

Designing the "unknown format" error

Takeaway — library constraints can be absorbed in a layer just in front

Renaming a site without losing its data — separating display name from a stable identifier

Why the data appears to disappear — the site name was the key

The fix — give every site an immutable site_id

A migration that doesn't break existing data

Tying logs to sites — strict + compat hybrid matching

A post-release blunder

Takeaway — separating stable identifier from display name

Beyond "Update All" — selecting plugins across sites while keeping every safety mechanism on

The limits of an industry-standard "Update All"

What was needed was two-axis granularity (site × plugin)

Cross-site dashboard design

A selective update runs with the same safety mechanisms as regular maintenance

Takeaway — granularity changes how operations feel

Distributing a Python desktop app on Windows and Mac — the full release pipeline

The per-OS pipeline at a glance

Mac — PyInstaller → sign → Notarization → DMG

The Intel / Apple Silicon trap

Sign inside-out

Notarize via ZIP, then build the DMG

Windows — PyInstaller → Inno Setup → eSigner CSC

The Inno Setup script

Cloud signing with eSigner CSC

The cross-cutting challenge — version synchronization and reproducibility

Reflection — "the same Python," distributed completely differently

Why we built a desktop app on local Flask + browser UI instead of PyQt or Electron

Four realistic options

Why local Flask + browser won

1. The backend had to be Python anyway

2. HTML/CSS/JS makes UI iteration fast

3. Distribution is about 1/3 the size of Electron

The side effects of using a browser

Reflection — structure choice is requirement-dependent

Pinpoint rollback — building per-plugin revert with WP-CLI

The command that makes it possible — wp plugin install --version=X --force

Combining with HTTP checks

Identifying the rollback target

Verifying recovery — always re-check HTTP after a rollback

Takeaway — "roll back all" vs "roll back one"

Three gaps the WordPress maintenance industry still hasn't solved — from a survey of four major tools

Gap 1 — Per-plugin updates with HTTP checks between each one

Gap 2 — Pinpoint rollback (only the one that broke)

Gap 3 — Reaching client sites without installing an extra plugin

Takeaway — should the industry's premises be questioned?

After a core rollback, halt the rest — a safety design we arrived at the hard way

Three cases to separate

The old design — disable the HTTP check and continue

Two problems that surfaced

Problem (a): broken state plus piled updates = untraceable

Problem (b): genuine plugin failures became invisible

The new design — halt in Cases 2 and 3

The trade-off we accepted

Takeaway — safety devices need to be left on

InfiniteWP's Strengths and Who It Fits — An Honest Review from a Competing Tool Builder

1. Over a decade of operational track record

2. Self-hosted — full control of the dashboard

3. Modular — pick only the add-ons you need

4. Browser-based access despite self-hosting

5. Annual licensing — predictable budgeting

What kind of agency InfiniteWP fits

How we're different

For a more detailed comparison

Summary

WP Umbrella's Strengths and Who It Fits — An Honest Review from a Competing Tool Builder

1. EU data residency and strict GDPR compliance

2. Continuous uptime monitoring as a core feature

3. Daily file-level backups

4. Modern, anywhere-accessible SaaS UI

5. Simple, predictable pricing

What kind of agency WP Umbrella fits

How we're different

For a more detailed comparison

Summary

MainWP's Strengths and Who It Fits — An Honest Review from a Competing Tool Builder

The approach — let `cryptography` pre-read it, then re-serialize as OpenSSH

The fix — give every site an immutable `site_id`

The command that makes it possible — `wp plugin install --version=X --force`

The real cause — a PHAR `broken signature`