DEV Community: Susumu Takahashi

Code signing basics — what Apple Notarization and Windows Authenticode actually certify

Susumu Takahashi — Wed, 09 Sep 2026 23:59:51 +0000

When you build a desktop app for distribution, macOS may greet users with "cannot be opened because the developer cannot be verified," and Windows SmartScreen may show "Windows protected your PC" for an unrecognized publisher. Signing and notarizing an app is how you avoid these warnings, but what exactly does that signature prove — and what does it not prove? The distinction is easy to get wrong. Here's a breakdown of two systems that look similar on the surface but play different roles: Apple's Notarization and Windows' Authenticode.

Note: Code signing is the umbrella term for attaching a cryptographic signature to an executable so that its author's identity and the integrity of its contents (whether it's been tampered with since signing) can be verified. The OS checks this signature before deciding whether to allow execution or show a warning.

What a signature proves — and what it doesn't

The key thing to understand is that code signing certifies two things: identity and integrity. It does not certify safety.

Identity: this executable was produced by the developer or organization named in the certificate
Integrity: the file's contents have not been altered by even a single byte since it was signed

A signed app carries no guarantee that it's free of bugs or vulnerabilities. Signing is a mechanical way to verify "who made this, and has anyone tampered with it since" — it is not a review of whether the software itself is good. Keeping this distinction in mind makes it easier to understand what Notarization and SmartScreen reputation actually add on top.

Apple's model: signing and Notarization are separate layers

macOS Gatekeeper actually checks two independent pieces of information.

Code signing (codesign): the developer uses the private key tied to an Apple-issued Developer ID certificate to embed a signature locally. That signature includes a hash of the entire app, so any modification after signing breaks verification.
Notarization: the signed app is uploaded to Apple's servers, where it's scanned automatically for known malicious patterns. If it passes, Apple issues a "notarization ticket," which gets stapled to the app itself — allowing Gatekeeper to verify it offline, even with no network connection.

In other words, Notarization is not a replacement for signing — it's an additional layer where Apple independently checks an already-signed app and attaches proof of that check to the app itself. Gatekeeper only allows a silent launch when both a valid signature and a valid notarization ticket are present.

Bundle signing order: inside out

A macOS .app bundle often contains more than just the main executable — frameworks and helper tools are commonly bundled as separate Mach-O binaries inside it. The signature over the whole bundle is computed from a hash that includes everything inside it, which means the inner binaries need to be signed individually first, and the outer .app bundle signed afterward.

Reverse that order and the outer signature ends up computed against binaries that were still unsigned at the time — verification will flag a content mismatch. Think of it as: finalize everything inside the box first, then seal the outer lid.

Windows' model: Authenticode and the certificate chain

Windows' Authenticode differs from Apple's Developer ID in how certificates get issued. Apple is the sole issuer of Developer ID certificates, while Windows code-signing certificates are issued by third-party Certificate Authorities (CAs), and the OS trusts them by tracing an unbroken chain up to a trusted root certificate — meaning "this publisher was identity-verified by a CA the system already trusts."

Certificates broadly fall into two tiers: OV (Organization Validation, confirming the organization exists) and EV (Extended Validation, a stricter identity check). EV certificates once carried an advantage of gaining SmartScreen trust immediately, but that distinction has shifted over time — it's no longer accurate to simply say "EV means instant trust, OV means extra scrutiny."

Without a timestamp, an expired certificate drags past signatures down with it

Another detail worth knowing is timestamping — embedding proof from a Timestamp Authority (TSA) at signing time. Skip it, and the moment the signing certificate expires, every binary ever signed with it (including older versions you shipped long ago) can be treated as having an invalid signature.

Add a timestamp, and a third party has recorded the fact that "this signature was made while the certificate was still valid" — so verification of that signed binary remains valid even after the certificate itself expires. macOS's codesign has a --timestamp flag, and Windows signing tools have equivalent timestamp-server options. As a rule, distributed binaries should be signed with a timestamp.

SmartScreen reputation is a separate axis from the signature itself

An Authenticode signature only certifies who made the file and whether it's intact — nothing more. Windows SmartScreen layers something else on top: a reputation score for the publisher's certificate, built up from download volume and how long it's been in use.

That means a correctly and validly signed app can still trigger a SmartScreen warning if the certificate is newly issued and hasn't accumulated any track record yet. This isn't a broken signature — it's simply "trust as a publisher" that hasn't built up yet, and it tends to fade as downloads accumulate over time. A signature-verification failure and a reputation-driven warning are different problems with different causes, and worth telling apart clearly.

Summary

Term	What it certifies	Note
Code signing (codesign / Authenticode)	Identity (who made it) and integrity (unaltered)	Does not certify that the contents are "safe"
Apple Notarization	Passed Apple's automated scan	A separate layer from signing; the stapled ticket enables offline verification
Bundle signing order	—	Sign inner binaries first, then the outer bundle
Certificate chain (Windows)	CA-verified publisher identity	Trust flows from a chain up to a trusted root
Timestamp	When the signature was made	Keeps past signatures valid after the certificate expires
SmartScreen reputation	Accumulated track record as a publisher	A separate axis from whether the signature is valid

Rather than "it's signed, so it's safe," it's more accurate to think of it as: signing is a mechanical way to verify identity and integrity, and reputation systems like SmartScreen run alongside it as a separate track-record check. Framing it that way makes the warnings you run into during distribution much easier to reason about.

Running Flask's dev server as a desktop app's backend — what actually matters

Susumu Takahashi — Wed, 09 Sep 2026 00:56:48 +0000

Start a Flask app and the terminal prints a familiar line: "WARNING: This is a development server. Do not use it in a production deployment." Yet plenty of desktop apps bundle that same local Flask server as their actual runtime and keep it running on the user's machine for the life of the session. That looks like ignoring the warning outright, but the underlying assumptions have actually changed. This article works through what has to change for that warning to become safe to set aside — and what you still have to handle yourself, or it turns into a real bug.

Note: WSGI (Web Server Gateway Interface) is the standard interface between a Python web application and the server that runs it. Flask itself builds the WSGI application; the part that actually accepts and serves HTTP requests is a separate, swappable component. By default, development uses a lightweight built-in server (Werkzeug), while production deployments normally swap in a dedicated production WSGI server such as Gunicorn.

The warning is about an unpredictable crowd of clients

What that warning is really about is a public-facing web service: handling concurrent traffic from an unknown number of clients, minimal built-in hardening, and no multi-worker process model for load distribution. In short, "not strong enough to serve the open internet."

Using Flask as a desktop app's backend changes that premise entirely. The server binds only to 127.0.0.1 (loopback) and is unreachable from any external network. The only client hitting it is a single browser tab running on the same machine — not an unpredictable crowd, but one tab the user opened themselves. Under that condition, most of the dev server's weaknesses simply stop applying.

The flip side matters just as much: accidentally binding to 0.0.0.0 makes the server reachable from any other device on the same LAN, and that premise collapses. When Flask is running as a desktop app's backend, binding strictly to loopback has to be an explicit, deliberate choice.

Turn off the auto-reloader — it breeds a second process

Flask's development server has a reloader that watches source files and automatically restarts the process when they change. It's convenient during development, but under the hood it runs as two processes: a parent that watches for file changes, and a child that actually handles requests.

Leaving that enabled in a packaged desktop app causes real problems. The port number claimed at startup, and the "an instance is already running" marker file written to prevent double-launches, are both normally designed around the assumption that exactly one process is running at a time. Once the reloader spawns a parent/child pair, that assumption breaks, opening the door to duplicate port claims and confused process tracking.

# Prioritize the guarantee of a single process over reload convenience
app.run(port=port, use_reloader=False, threaded=True)

Setting use_reloader=False explicitly guarantees the app always starts as a single process. Since a desktop app's source code never changes while it's running, the reloader's whole reason for existing doesn't really apply here anyway.

Set `threaded=True` explicitly — or concurrent access will stall

Unless told otherwise, Flask's development server handles requests one at a time, in sequence. But once the UI lives in a browser, it's completely normal for multiple requests to be in flight simultaneously. Picture a long-running request streaming maintenance progress alongside a short heartbeat request sent every few dozen seconds to confirm the browser tab is still alive — while the server is busy serving the long request, the short one just sits in a queue.

# Without threaded=True, a short request can get stuck behind
# a long-running one instead of being served concurrently
app.run(port=port, use_reloader=False, threaded=True)

Setting threaded=True makes each request get handled on its own thread, sidestepping that queuing problem.

Concurrent threads mean you now have to guard shared state

Once threaded=True lets multiple requests run at the same time, a different problem shows up: multiple request handlers can now read and write the same global variable concurrently.

Say there's a global variable tracking "is a maintenance job currently running." If one request is in the middle of a two-step "check whether one is running, and if not, start a new one" sequence, and another thread reads and writes that same variable at the same moment, both can conclude "nothing is running" and each kick off a job — a classic check-and-set race condition.

from threading import Lock

_maint_lock = Lock()
_maint_process = None

def start_maintenance():
    with _maint_lock:
        if _maint_process is not None:
            return False  # already running
        # start the new process while still holding the lock
        ...
        return True

The fix is straightforward: protect the shared variable with a threading.Lock so the "check, then write" sequence becomes one indivisible operation. It's worth noting this operates at a different layer than cross-platform file locking with fcntl/msvcrt, which guards against races between separate processes. This is about races between separate threads inside the same process — and once you choose threaded=True, guarding against that becomes mandatory, not optional.

You own port allocation and duplicate-instance detection

In a production application server, controlling multiple instances and negotiating ports is usually somebody else's job — a process manager like systemd, or a container orchestrator. A Flask backend embedded in a desktop app has no such external supervisor, so you have to build that logic yourself.

Hardcoding a fixed port makes a simple failure very likely: launch the app twice, and the second attempt can't bind because the first process is still holding the port. Instead, scan for a free port at startup and write the chosen port number and process ID to a marker file, so the next launch can check whether an instance is already running.

import socket

def find_free_port(start=5002, end=5100):
    for port in range(start, end):
        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
            try:
                s.bind(('127.0.0.1', port))
                return port
            except OSError:
                continue
    raise OSError(f"No free port found in range {start}-{end}")

When an existing instance is detected, rather than just failing with an error, it's worth reopening a browser tab pointed at that instance's port and quietly exiting. From the user's point of view, clicking the app icon a second time just brings the original screen back — which is the behavior people expect.

The server has no way of knowing a browser tab was closed

With a native windowed app, the OS notifies the app the instant the user closes its window. But when a browser tab is the UI, closing that tab gives the backend Flask process no signal whatsoever. Without any countermeasure, the backend process just keeps running in the background even after the user closes the tab.

A periodic "heartbeat" request from the browser fills that gap.

_last_heartbeat_time = 0.0

@app.route('/api/heartbeat', methods=['POST'])
def api_heartbeat():
    global _last_heartbeat_time
    _last_heartbeat_time = time.time()
    return ('', 204)

The browser hits this endpoint every few dozen seconds, and a background thread on the server periodically checks how long it's been since the last heartbeat arrived. Once the tab closes, the heartbeats stop, and after a set period of silence the server treats that as "the user closed the tab" and shuts itself down. Guarding against shutting down mid-maintenance-job, and excluding the initial warm-up window while the browser is still connecting, both matter for avoiding false positives in real use.

Summary

Setting / mechanism	Purpose
Bind to `127.0.0.1` only	Blocks reachability from any external network
`use_reloader=False`	Guarantees a single running process
`threaded=True`	Keeps a long request from stalling short ones
Guard shared state with `threading.Lock`	Prevents check-and-set races between threads
Scan for a free port + record the running instance	Detects and avoids duplicate launches
Heartbeat monitoring + timeout self-shutdown	Indirectly detects that the tab was closed

Flask's development server isn't something to avoid outright — it's easier to work with once you understand exactly what assumptions that warning is built on, and confine its use to environments where those assumptions genuinely hold. Loopback-only binding, a single process, thread safety, duplicate-launch detection, and liveness checks: handle each of these deliberately, and the dev server becomes a stable enough foundation to run a desktop app's backend on.

The design decision behind choosing a Flask-plus-browser structure in the first place is covered separately in why we built a desktop app on local Flask + browser UI. This article picks up from there, covering the operational details worth handling once that structure has already been chosen.

Atomic writes — how tempfile + os.replace prevent corrupted JSON

Susumu Takahashi — Tue, 08 Sep 2026 00:19:18 +0000

What happens if the power cuts out while a process is writing to a config file? Or if antivirus software on Windows briefly locks a file mid-write? If you naively overwrite a file with open(path, 'w'), whatever partial content existed at the moment of interruption is what remains on disk. For JSON, that usually means broken syntax — json.load() throws on the next startup, and the entire configuration is effectively lost. This article walks through a standard technique for preventing that: writing to a temporary file first, then swapping it in atomically.

Note: "Atomic" here means an operation either completes entirely or doesn't happen at all — there's no partial, observable in-between state. It's the same sense of the word used for database transactions.

Why direct overwrites are dangerous

open(path, 'w') effectively truncates the file first and then writes the new content. If the process is interrupted during that window, the file is left empty or holding incomplete content.

# Dangerous: a crash mid-write leaves a corrupted file behind
with open('config.json', 'w') as f:
    json.dump(data, f)  # what if this gets interrupted?

The causes vary: a kill -9, a power outage, antivirus software briefly blocking file access on Windows, or a backup tool grabbing the file mid-write. This rarely reproduces during local development, but in a long-running production environment, it will eventually happen with near certainty.

The fix: write to a temp file, then swap it in

The core idea is simple. Never touch the target file directly. Write the complete new content to a temporary file first, confirm that write fully succeeded, and only then replace the target file with that temp file.

import json
import os
import tempfile

def atomic_write_json(filepath, data):
    dirpath = os.path.dirname(os.path.abspath(filepath)) or '.'
    fd, tmp_path = tempfile.mkstemp(dir=dirpath, suffix='.json.tmp')
    try:
        with os.fdopen(fd, 'w', encoding='utf-8') as f:
            json.dump(data, f, indent=4, ensure_ascii=False)
        os.replace(tmp_path, filepath)
    except Exception:
        os.unlink(tmp_path)
        raise

tempfile.mkstemp() generates a collision-free temporary filename and returns its file descriptor. The dir=dirpath argument matters here: placing the temp file in the same directory as the target file ensures the following os.replace() call stays within a single filesystem.

Why `os.replace()` is atomic

The core of this pattern is the final os.replace(tmp_path, filepath) call. Python's official documentation states that os.replace() "will be an atomic operation on Unix" and behaves atomically on Windows as well, as long as both paths are on the same filesystem.

On POSIX systems (Linux/macOS), this maps to the rename(2) system call. At the kernel level, swapping a directory entry is a single indivisible operation. There is no intermediate state to observe — from the outside, the file is either in its pre-swap or post-swap state, never something in between.

On Windows, Python 3.3+ implements this so that overwriting an existing file is handled atomically (roughly equivalent to calling MoveFileEx with the MOVEFILE_REPLACE_EXISTING flag).

Thanks to this property, if the process dies in the middle of json.dump(), only the unnamed temp file is affected — the real config file remains untouched in whatever valid state it was in before.

Forcing persistence to disk with `os.fsync()`

Even with an atomic os.replace(), there's a subtler risk: the content written by json.dump() might still be sitting in the OS page cache rather than physically on disk when power is lost. In that case the rename itself could complete, but the renamed file's contents might not reflect what was actually written. os.fsync() addresses this.

with open(tmp_path, 'w', encoding='utf-8') as f:
    json.dump(data, f, ensure_ascii=False, indent=2)
    f.flush()
    try:
        os.fsync(f.fileno())
    except OSError:
        pass
os.replace(tmp_path, filepath)

f.flush() only pushes Python's internal buffer out to the OS — it may still sit in OS-level cache. os.fsync() goes a step further and asks the OS to wait until the data is actually written to physical disk. Combining both steps ensures the temp file's content is durably on disk by the time os.replace() runs.

Cleaning up after a failed write

If the write to the temp file itself fails partway through (disk full, permission error, etc.), os.replace() is never reached, so the target file is unaffected. But the half-written temp file is left behind on disk. Left unattended, these accumulate as clutter, so it's worth deleting them explicitly on failure.

except Exception:
    try:
        os.unlink(tmp_path)
    except OSError:
        pass
    raise

The nested try accounts for the possibility that os.unlink() itself fails (already deleted, no permission, etc.). Re-raising the original exception (raise) ensures the caller still learns that the write failed.

Guarding against leftover `.tmp` files

Since os.replace() consumes the temp filename and swaps it into the target name on success, .tmp files normally don't linger under regular operation. But in an extreme edge case — the process gets kill -9'd in the narrow window right after the temp file is fully written but right before os.replace() is called — a stray .tmp file could theoretically be left behind.

This leftover doesn't threaten data integrity (the real file stays intact), so it's not urgent. But left unchecked over a long-running install, it quietly wastes disk space. A simple startup routine that scans the config directory for .tmp files older than some threshold (say, one hour) and deletes them closes this gap.

import time

def cleanup_stale_tmp_files(directory, stale_seconds=3600):
    now = time.time()
    for name in os.listdir(directory):
        if not name.endswith('.tmp'):
            continue
        path = os.path.join(directory, name)
        if now - os.path.getmtime(path) > stale_seconds:
            os.remove(path)

Summary

Step	Purpose
`tempfile.mkstemp(dir=same directory as target)`	Keeps the eventual swap within one filesystem
Write to temp file + `flush()` + `fsync()`	Guarantees content is durably on disk
`os.replace(temp, target)`	Makes the swap itself indivisible
Delete the temp file on failure	Avoids leaving half-written garbage behind
Sweep stale `.tmp` files on startup	Covers the extreme edge-case leftover

Replacing "write directly to the target file" with "write completely to a temp file, then atomically rename it" eliminates the observable in-between state entirely — and with it, the whole class of bugs where a config file ends up corrupted. The implementation overhead is modest, so it's worth adopting from the start for any file you read and write frequently, like config or cache files.

This shares a family resemblance with another kind of pitfall that stays invisible during Mac development and only surfaces in real-world operation: cross-platform file locking in Python, which handles mutual exclusion between multiple processes. Atomic writes and file locking are actually complementary — in an environment where multiple processes might write concurrently, it's worth combining both.

Cross-platform file locking in Python — fcntl vs msvcrt from scratch

Susumu Takahashi — Mon, 07 Sep 2026 02:41:31 +0000

What happens when a GUI app and a separate background process both try to write to the same configuration file at the same time? If the timing is bad, one write clobbers the other, and in the worst case the file ends up corrupted. File locking is the standard answer to this "concurrent writes from multiple processes" problem. Trying to implement it in pure Python across both Unix-like systems and Windows runs straight into a wall: the two platforms expose completely different APIs. This article walks through that difference from the ground up.

Note: "lock" here means inter-process locking — coordinating multiple separate processes on the same machine. That's different from locking between threads inside a single process (threading.Lock), which is a separate topic.

Why avoid a third-party library

Well-established packages like filelock exist and work fine. But there are situations where adding a dependency is a real cost — packaging a desktop app with PyInstaller or similar, for instance, where every extra dependency adds build complexity and distribution size. Using only the standard library's fcntl (Unix-like) and msvcrt (Windows) modules, you can implement inter-process locking with zero additional dependencies.

Unix-like systems: `fcntl.flock` is an advisory lock

The most important property of fcntl.flock() on Unix-like systems (Linux/macOS) is that it's an advisory lock. The OS kernel tracks the lock state, but it does not forcibly stop a process that ignores the lock and writes anyway. The lock only works if every participating process cooperates and follows the same acquisition protocol.

import fcntl

fd = open('target.lock', 'w')
try:
    # LOCK_EX: exclusive lock / LOCK_NB: non-blocking (fail immediately instead of waiting)
    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
except OSError:
    # another process already holds the lock
    pass

Calling flock() without LOCK_NB blocks in place until the lock becomes available. If a GUI app calls this unguarded on its main thread, the interface can appear to freeze. Most implementations instead try non-blocking acquisition, and if it fails, wait briefly and retry — a polling approach.

Windows: `msvcrt.locking` locks an explicit byte range

Windows has no fcntl module. The equivalent is msvcrt.locking(), which locks an explicit byte range within a file.

import msvcrt

fd = open('target.lock', 'r+b')
try:
    # LK_NBLCK: attempt a non-blocking lock (over 1 byte)
    msvcrt.locking(fd.fileno(), msvcrt.LK_NBLCK, 1)
except OSError:
    # another process already holds the lock
    pass

Where fcntl.flock() locks the whole file, msvcrt.locking() operates on a specified number of bytes from the current position. When the lock target is a purpose-built sidecar file, as described below, locking just 1 byte is enough — there's no need to manage complex byte-range bookkeeping.

The core abstraction: branch on `sys.platform`

Wrapping both APIs into a single class comes down to a simple branch on sys.platform.

import sys

if sys.platform == 'win32':
    import msvcrt
    msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
else:
    import fcntl
    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)

The imports are placed inside the branch rather than at module top level because import fcntl raises ModuleNotFoundError immediately on Windows. Importing only within the branch that will actually run lets both platform's code live in the same file without either one breaking the other's import.

A design choice: don't lock the target file itself

The naive approach is to open and lock the actual file you're writing to (say, sites.json) directly. But this runs into a Windows-specific pitfall: when one process has a file open in an exclusive mode, Windows can refuse even basic operations from other processes — including reads or opens in a different mode. Having the locking mechanism itself get in the way of writing the data defeats the purpose.

A common way around this is to introduce a disposable sidecar file, <target-file-name>.lock, and make that the sole object of locking. The actual data file (sites.json) is never opened for locking purposes at all — acquiring and releasing the lock is entirely a matter of creating and deleting sites.json.lock. This separation keeps platform-specific file-open quirks from ever touching the actual data I/O.

Making lock acquisition atomic with `O_CREAT | O_EXCL`

Creating the sidecar file has its own race condition to worry about. If two processes each perform "check whether the file exists, then create it if not" as two separate steps, another process can slip in between the check and the creation. The fix is the combination of flags passed to os.open(): O_CREAT | O_EXCL.

import os

try:
    fd = os.open('target.lock', os.O_CREAT | os.O_EXCL | os.O_RDWR, 0o644)
    # reaching this line means this process created the file — lock acquired
except FileExistsError:
    # another process already created it — lock acquisition failed
    pass

With O_EXCL set, "create the file if it doesn't exist, otherwise fail" runs as a single atomic operation inside the OS kernel. There is no window between the check and the creation for another process to interleave, so the race condition is prevented without any additional locking layer.

The remaining gap: stale locks

If the process holding a lock crashes instead of exiting cleanly, the sidecar file can be left behind indefinitely, and no other process will ever be able to acquire the lock again. One practical mitigation is to check the sidecar file's modification time: if it's older than some threshold (say, 30 minutes), treat it as stale, delete it, and retry acquisition.

import time

mtime = os.path.getmtime('target.lock')
if time.time() - mtime > 1800:  # older than 30 minutes: treat as stale
    os.remove('target.lock')
    # retry acquisition with O_CREAT | O_EXCL after deleting

This approach isn't perfect — there's no way to distinguish "a lock genuinely still held by a process that's just been running for a long time" from "a lock abandoned by a crash." In practice, you mitigate this by choosing a threshold generously longer than how long the protected operation normally takes to complete.

Wrapping it as a context manager for `with`

Bring together everything above — the platform branch, atomic file creation, staleness check, and timeout-with-retry — into a single class, and implement __enter__ / __exit__. Callers then get a clean interface:

with FileLock('sites.json', timeout=10):
    # this block is exclusive across processes
    write_json('sites.json', data)
# lock is released automatically on leaving the block

As long as __exit__ always releases the lock and removes the sidecar file, the lock is guaranteed to be released both on normal completion and when an exception is raised inside the with block — the exact guarantee a context manager exists to provide, without writing try/finally by hand every time.

Summary

Aspect	Unix-like	Windows
API	`fcntl.flock()`	`msvcrt.locking()`
Lock nature	Advisory (not enforced)	Explicit byte-range lock
Non-blocking flag	`LOCK_NB`	`LK_NBLCK`
Lock granularity	Whole file	Specified byte range

fcntl and msvcrt differ in both design philosophy and API shape, but with the surrounding design choices in place — locking a disposable sidecar file rather than the data file itself, and using O_CREAT | O_EXCL for atomic acquisition — the platform branch itself collapses to just a few lines. Worth considering the next time a cross-platform tool needs inter-process locking without pulling in an extra dependency.

The cp932 build-gate crash is the same shape of problem in a different corner: an encoding pitfall that never reproduces during development on macOS and only surfaces on Windows. Both cases come down to the same lesson — platform differences that stay invisible until the code actually runs where the difference matters.

Crontab syntax basics, and how it differs from WP-Cron

Susumu Takahashi — Sat, 05 Sep 2026 02:38:07 +0000

"What does */5 * * * * actually mean?" — anyone setting up a scheduled task on a server has probably stared at that row of asterisks at some point. If you run WordPress, you may already be familiar with inspecting WP-Cron's internals through WP-CLI, but the actual crontab syntax used by the OS itself is something many people never learn properly. Before you can switch WP-Cron over to a real OS-level cron job, you need to understand that syntax first.

Note: crontab is a scheduling mechanism built into Unix-like systems (Linux, macOS, etc.). The name is short for "cron table" — a configuration file, and the command used to manage it, that lists what to run and when, one line at a time.

The five time fields

Each line in a crontab consists of five time fields followed by the command to run.

minute hour day month weekday command
*      *    *   *     *       command

Field	Range	Meaning
minute	0-59	Which minute to run at
hour	0-23	Which hour to run at (24-hour clock)
day	1-31	Which day of the month
month	1-12	Which month
weekday	0-7 (0 and 7 both mean Sunday)	Which day of the week

* is a wildcard meaning "every value" for that field. A line where all five fields are * runs every single minute.

Common patterns worth memorizing

In practice, a handful of combinations cover almost everything you'll need.

# Run every minute
* * * * * command

# Run every 5 minutes
*/5 * * * * command

# Run daily at 3:00 AM
0 3 * * * command

# Run at 9:00 AM on weekdays (Mon-Fri)
0 9 * * 1-5 command

# Run at midnight on the 1st of every month
0 0 1 * * command

The slash notation in */5 is called a step value — "starting from 0, every 5 units." The hyphen in 1-5 is a range, covering Monday(1) through Friday(5). You can also list specific values with commas, like 1,3,5. Once you're comfortable combining steps, ranges, and comma lists, most schedules become expressible.

Some cron implementations also support shorthand strings like @daily (equivalent to 0 0 * * *) or @hourly (equivalent to 0 * * * *). They read more clearly, but support varies by implementation, so it's worth treating the five-field syntax as the portable baseline.

Editing with `crontab -e`

Jobs that run under your own user account are managed with crontab -e.

# Edit the current user's crontab
crontab -e

# List the current user's crontab
crontab -l

# Remove the current user's crontab entirely
crontab -r

crontab -e opens whatever text editor is set in your EDITOR environment variable. Changes take effect as soon as you save — no restart or reload step is needed. Because crontab -r wipes everything at once, it's worth making a habit of running crontab -l first to confirm what you're about to delete.

The PATH environment trap

Jobs run by cron execute with a much smaller PATH environment variable than your interactive login shell. A command that works fine when you type it yourself can fail with "command not found" once it's running from cron — this is one of the most common causes of "it works when I run it manually, but not from cron."

# Works in a login shell, but may not be found in cron's minimal PATH
0 3 * * * wp cron event run --due-now

# Fix: specify the full path to the binary
0 3 * * * /usr/local/bin/wp cron event run --due-now --path=/var/www/html

# Or set PATH explicitly at the top of the crontab file
PATH=/usr/local/bin:/usr/bin:/bin
0 3 * * * wp cron event run --due-now --path=/var/www/html

Running which wp (or the equivalent for whatever command you're scheduling) ahead of time and writing the full path into the crontab entry is the most reliable fix.

How this differs fundamentally from WP-Cron

The OS-level crontab covered above and WordPress's built-in WP-Cron share a name, but they work on completely different principles.

Aspect	OS crontab	WP-Cron
What triggers execution	The OS cron daemon, watching the clock	Every page load, when WordPress checks for overdue tasks
Low-traffic periods	Still runs on schedule	Doesn't run — the task waits for the next visitor
What actually runs it	An OS process, independent of the web server	A PHP process, running as part of handling a request
Where the schedule lives	Edited via `crontab -e`	Stored in the `wp_options` table

The reason WP-Cron is often described as "a pseudo-cron that depends on traffic" comes straight from the first row of that table. A scheduled post that doesn't go live on time on a low-traffic site late at night is a direct symptom of that design constraint.

Switching to a real crontab entry

Adding define('DISABLE_WP_CRON', true); to wp-config.php stops WP-Cron's automatic page-load trigger. From there, an OS crontab entry that periodically invokes WP-CLI gives you execution that no longer depends on visitor traffic.

# Process any overdue WP-Cron tasks every 5 minutes
*/5 * * * * /usr/local/bin/wp cron event run --due-now --path=/var/www/html/wordpress > /dev/null 2>&1

> /dev/null 2>&1 discards both standard output and standard error. Cron's default behavior is to try emailing you the output of every job, and on a server without mail configured, that can fail silently and repeatedly — appending this redirect avoids it. If you'd rather keep a record, point it at a log file instead of /dev/null.

Summary

What you want	Syntax / command
Run every 5 minutes	`/5 * * *`
Run at 9 AM on weekdays	`0 9 * * 1-5`
Edit your crontab	`crontab -e`
List your crontab	`crontab -l`
Avoid PATH issues	Use the full path to the command
Discard output	Append `> /dev/null 2>&1`

The five-field crontab syntax itself is simple, but the differences from an interactive shell — a minimal PATH, and cron's habit of trying to email job output — are where people usually get tripped up. Combined with the WP-CLI commands for inspecting WP-Cron's internals, this gives you a way to run WordPress's scheduled tasks through the OS's own reliable scheduler instead.

Organizing per-host settings with `~/.ssh/config` — a standard practice for anyone managing multiple servers

Susumu Takahashi — Fri, 04 Sep 2026 00:12:03 +0000

If you maintain WordPress sites across more than a couple of servers, you've probably typed a command like ssh -i ~/.ssh/xxx_key.pem -p 2222 user@203.0.113.10 more times than you'd like. Remembering the right key path, port number, and username for each server isn't realistic, and copying a similar-looking command from shell history is exactly how you end up connecting to the wrong box. ~/.ssh/config solves this by letting you collect per-host settings in one file.

Note: ~/.ssh/config is a file read by the OpenSSH client — it's not a server-side setting. It lives on your local machine (Mac/Linux/Windows SSH client) and teaches it how to reach each server, typically with just a few lines per host.

Basic structure

A minimal block looks like this:

Host myserver
    HostName 203.0.113.10
    User deploy
    Port 2222
    IdentityFile ~/.ssh/myserver_key
    IdentitiesOnly yes

Once saved, you can connect with:

ssh myserver

Host here is an alias — an arbitrary string, unrelated to the actual hostname. scp and rsync can use the same alias, so scp file.txt myserver:/tmp/ just works. You no longer need to pass the port or username on the command line every time, and there's no chance of mistyping the key path.

Why `IdentitiesOnly yes` matters

Specifying IdentityFile alone isn't quite enough. Without IdentitiesOnly yes, the OpenSSH client will offer the specified key plus any other keys registered with ssh-agent. If the server enforces a limit on authentication attempts (MaxAuthTries), or runs something like fail2ban that temporarily blocks an IP after repeated failed auth attempts, offering several unintended keys before reaching the correct one can get your connection blocked before it ever succeeds.

IdentitiesOnly yes restricts the client to only the key explicitly listed in that Host block, which avoids the extra authentication attempts. If you keep separate keys for different projects or separate personal and work use, this option is effectively mandatory.

Grouping shared settings across similar servers with wildcards

When you have several servers with similar setups, Host supports wildcard patterns so you can group shared settings:

Host staging-*
    User deploy
    IdentitiesOnly yes
    ServerAliveInterval 30

Host staging-web1
    HostName 203.0.113.10
    IdentityFile ~/.ssh/staging_key

Host staging-web2
    HostName 203.0.113.20
    IdentityFile ~/.ssh/staging_key

OpenSSH reads the config file top to bottom and keeps the first value it finds for a given option — later matching blocks don't override earlier ones. That means specific Host blocks need to come before the wildcard block. If staging-* were placed first, the individual blocks' HostName values would never be read, and every alias would try to connect to the same server.

ServerAliveInterval 30 sends a keepalive packet every 30 seconds, which matters on networks that drop idle connections (some routers and firewalls do this). It's particularly useful when running a long backup job over SSH that you don't want interrupted mid-way.

Splitting the config file with `Include`

As the number of projects grows, cramming every server into a single ~/.ssh/config gets hard to navigate. OpenSSH 7.3 and later supports an Include directive to split the file up:

# ~/.ssh/config
Include ~/.ssh/config.d/*.conf

Host *
    IdentitiesOnly yes

Keeping one file per project or client under ~/.ssh/config.d/ means that when a project ends, you delete one file and the cleanup is done. Include expands exactly where it's written, so whether you place it before or after a catch-all Host * block changes which settings take precedence — worth keeping in mind.

How this differs from WP-CLI aliases

Using WP-CLI aliases to switch between multiple WordPress environments safely covered wp-cli.yml aliases, which manage "which WordPress site a command runs against" at the application layer — inside WP-CLI itself. ~/.ssh/config operates one layer down, at the OS's SSH client, managing "how to connect to which server" in the first place.

The two are independent, but combining them compounds the benefit. ~/.ssh/config organizes the connection itself; WP-CLI aliases then organize the sites within each server. Together, both the connection command and the site-targeting command stay short and less error-prone.

A security note

~/.ssh/config stores hostnames, IP addresses, and port numbers in plain text. As a baseline, keep the file's permissions at 600 (readable/writable only by you) — some OpenSSH client implementations will warn if permissions are looser than that.

chmod 600 ~/.ssh/config

It's also worth being deliberate about not committing this file to a Git repository by accident, since that would leak internal connection details externally. ~/.ssh/ is typically outside any project repo, but if you version-control your dotfiles, make sure it's explicitly excluded via .gitignore.

Summary

Setting	Purpose
`Host`	Alias name (freely chosen)
`HostName`	Actual connection target (IP or domain)
`IdentityFile`	Path to the private key to use
`IdentitiesOnly yes`	Offers only the specified key, avoiding extra auth attempts
`Host pattern*`	Applies shared settings across multiple servers via wildcard
`Include`	Splits the config file by project or client

For anyone maintaining multiple WordPress environments over SSH, ~/.ssh/config is a setup cost paid once — after that, all you need to remember is an alias name. The real payoff isn't the shorter commands; it's that the structural risk of connecting to the wrong server drops significantly. For choosing which key type to generate in the first place, see also SSH key types (RSA / ED25519 / ECDSA) — what actually differs, and which one to pick.

SSH key types (RSA / ED25519 / ECDSA) — what actually differs, and which one to pick

Susumu Takahashi — Thu, 03 Sep 2026 02:55:19 +0000

If you maintain WordPress sites over SSH — running wp-cli remotely, checking logs, transferring files with rsync — you're relying on SSH key authentication as the foundation. What rarely gets explained clearly is what you're actually choosing when ssh-keygen -t asks for an algorithm. This post walks through what RSA, ECDSA, and ED25519 actually rest on mathematically, and which one makes sense to pick today.

Note: SSH key authentication uses public-key cryptography. You keep a private key on your machine (never shared) and place a public key on the server (safe to share). The server issues a challenge that only the matching private key can answer, so you prove who you are without ever sending a password.

What actually differs between the three types

The main options you'll see with ssh-keygen -t <algorithm> are:

Type	Mathematical basis	Typical key size	Introduced
RSA	Difficulty of factoring large numbers	2048–4096 bits	Late 1990s (for SSH use)
ECDSA	Discrete logarithm problem over elliptic curves	256–521 bits	Late 2000s
ED25519	Elliptic-curve cryptography (Ed25519's own Twisted Edwards curve)	Fixed, ~256-bit equivalent	Published 2011, supported since OpenSSH 6.5 (2014)

All three share the same core property — you can't forge a signature without the private key — but they differ in what mathematical hardness assumption they rely on and how the keys are generated.

Even though ECDSA and ED25519 are both "elliptic-curve" algorithms, they aren't interchangeable. ECDSA uses curve parameters standardized by NIST. ED25519 was published with parameters designed independently of any single government standards body. This distinction matters less as a practical threat and more as a design philosophy — it's part of why ED25519 tends to be preferred in contexts where provenance of the parameters is a concern.

Key size and the speed difference you'll actually notice

To reach a comparable security strength (roughly, how much computation a brute-force attack would require), the required key length varies a lot by algorithm. A commonly recommended 2048-bit RSA key is considered roughly comparable in strength to a 256-bit ED25519 key. Don't assume a longer bit count automatically means "more secure" — different math means different bit counts are needed for the same effective strength.

The difference you'll actually feel day to day is in how fast key generation, signing, and verification run. Because ED25519 keys are shorter, the cryptographic operations behind them are faster — ssh-keygen finishes quicker, and every login carries a lighter computational load. A large RSA key (4096 bits, say) does raise the security margin, but at the cost of heavier computation on every operation. If you connect over SSH frequently as part of routine maintenance, that difference adds up.

Which one should you actually use

Short answer: for a newly generated key today, ED25519 is the reasonable default, for three reasons:

Comparable strength at a much shorter key length — as noted, its ~256-bit key is roughly on par with a 2048–3072-bit RSA key
Faster in practice — generation, signing, and verification are all lighter
Less room for implementation mistakes — RSA implementations have historically had a string of vulnerabilities tied to poor randomness during key generation; ED25519's design leaves much less room for that class of implementation-specific bug

That said, there are real situations where ED25519 isn't the right — or even available — choice:

Older servers or embedded network devices: environments running an OpenSSH version older than 6.5 (2014), or embedded SSH implementations with limited algorithm support, may not support ED25519 at all. RSA (2048 bits minimum, ideally 3072–4096) is the fallback there
Compliance or internal policy requirements: if an audit or internal policy mandates a specific algorithm, follow that requirement
ECDSA: given the NIST-parameter provenance question mentioned above, it's rarely the algorithm you'd actively choose for a brand-new key. There's no urgent need to replace ECDSA keys already in use, but it's a weak default for new ones

Generating a key (general steps)

# ED25519 (recommended) — the comment helps you identify the key later
ssh-keygen -t ed25519 -C "example-comment"

# RSA, when you need broader compatibility (3072 bits or higher recommended)
ssh-keygen -t rsa -b 4096 -C "example-comment"

Key generation prompts for a passphrase. That passphrase encrypts the private key file itself, so even if the file is stolen, it can't be used immediately. Leaving it blank means the security of your account rests entirely on the private key file never leaking — setting a passphrase is worth doing whenever practical.

The public key (the .pub file) gets appended to ~/.ssh/authorized_keys on the server side. The private key should never leave the machine it was generated on. When multiple people share access to a server, the right pattern is for each person to generate their own key pair and register only their public key — not to hand around a shared private key file.

Summary

Situation	Recommended type
Generating a new key (compatible environment)	ED25519
Environments older than OpenSSH 6.5, embedded devices	RSA (3072–4096 bits)
Policy or audit mandates a specific algorithm	Whatever's mandated
Existing ECDSA keys already deployed	No urgent need to replace, but avoid for new keys

Choosing an SSH key type isn't something you revisit often once decided, but understanding the reasoning behind it makes it easier to separate "older documentation defaulted to RSA because that's what was standard at the time" from "ED25519 is now the sensible default." For managing SSH access across multiple WordPress environments safely, see also using WP-CLI aliases to switch between multiple environments. Once your key is set up, organizing where you connect is covered in organizing per-host settings with ~/.ssh/config. For the layer beneath this one — why use a key instead of a password in the first place — see why SSH key authentication beats password authentication.

How the WordPress transient API works, and when `wp transient delete` actually helps

Susumu Takahashi — Wed, 02 Sep 2026 00:42:20 +0000

WordPress ships with a built-in way to store data temporarily — save something for a fixed window of time, and it stops being valid once that window closes. This is the transient API, and both WordPress core and countless plugins lean on it to cache things like external API responses or the results of expensive calculations. It's a genuinely useful mechanism, but used without understanding how it actually behaves, expired entries can pile up and quietly bloat the database.

Note: the transient API is WordPress core's name for a small set of PHP functions — set_transient(), get_transient(), delete_transient() — built around the idea of a cache entry with an expiration.

How a transient actually works

Saving a transient means specifying three things: a value, a key, and an expiration in seconds.

set_transient('weather_data', $api_response, 3600); // cache for one hour

Where that value actually gets stored depends on the site's setup:

Default setup (most shared hosting environments): it lands in the wp_options table as a row named _transient_<key>, with a matching _transient_timeout_<key> row holding the expiration
With a persistent object cache (a plugin backed by Redis or Memcached): the value goes to that cache layer instead of wp_options

When get_transient() is called, WordPress compares the timeout value against the current time and returns false if the entry has expired. At that point, the design intends for the stale row to be cleaned up automatically — but that cleanup isn't as reliable as it sounds.

Why expired entries stick around

In theory, an expired transient should disappear. In practice, wp_options can accumulate a large number of long-expired rows. Two things typically cause this:

get_transient() is never called again for that key. The automatic cleanup described above is passive — it only fires when something actually tries to read the value and finds it expired. It isn't an active sweep. If a plugin sets a value once and never checks it again, the row just sits there past its expiration indefinitely.
WP-Cron's garbage collection doesn't run. WordPress core schedules a periodic cleanup job (wp_scheduled_delete, among others) to purge expired data. But WP-Cron is a pseudo-cron that only fires on page visits, so on a site with very light traffic, that cleanup can go a long time without actually executing.

What makes this worse is that most _transient_-prefixed options are saved with autoload set to yes — meaning WordPress loads them into memory on every single page request, whether or not that page needs them. A handful of stale rows is harmless. Thousands of them, and every page load starts carrying that weight, even pages that never touch the cached values in question.

Inspecting and cleaning up with `wp transient`

WP-CLI ships a dedicated set of subcommands for this:

# List everything currently stored as a transient
wp transient list

# Delete one specific key
wp transient delete weather_data

# Delete only the ones that have already expired
wp transient delete --expired

# Delete everything, expired or not
wp transient delete --all

The distinction between --expired and --all matters. --expired only touches rows that are already past their timeout, so running it has essentially no side effects. --all wipes out live, still-valid cache entries too — which means plugins have to recompute or re-fetch that data immediately afterward, possibly hitting external APIs all at once and causing a brief slowdown right after you run it. Unless you're deliberately forcing a full cache reset while troubleshooting something specific, --expired is the safer default for routine maintenance.

Note: on a site running a persistent object cache (Redis or Memcached), the wp transient commands operate against that cache layer instead of wp_options. Checking wp_options directly — for example with wp db query "SELECT COUNT(*) FROM wp_options WHERE option_name LIKE '_transient_%'" — only reflects reality on sites without a persistent object cache in front of it.

When it's worth running

As a first check when a site feels generally slow. Run wp option list --autoload=on --search='_transient_%' to see how many autoloaded transient rows exist. Thousands of rows is a reasonable signal that wp transient delete --expired is worth trying.
After swapping out or bulk-removing plugins. Some plugins don't bother calling delete_transient() for their own keys before being uninstalled, leaving orphaned _transient_ rows with no code left to ever read or clean them up.
As part of routine maintenance. Folding transient cleanup into the same cycle as wp db check / wp db optimize turns autoload bloat into something checked on a predictable schedule, rather than something that only gets noticed once it's already affecting page load times.

Summary

What you want to do	Command
List everything currently cached as a transient	`wp transient list`
Delete one specific key	`wp transient delete <key>`
Delete only expired entries (safe)	`wp transient delete --expired`
Delete everything, including live cache (has side effects — use for troubleshooting)	`wp transient delete --all`
Check for autoload bloat	`wp option list --autoload=on --search='_transient_%'`

The transient API's whole premise — save it temporarily, let it expire on its own — only holds up when get_transient() gets called regularly and WP-Cron's garbage collection is actually running. Folding a transient audit into the same routine as checking database health with wp db check / wp db optimize is a straightforward way to catch autoload bloat — one of the harder-to-see kinds of database debt — before it accumulates into a real performance problem.

`wp db check` / `wp db optimize` — the database health commands that get overlooked

Susumu Takahashi — Tue, 01 Sep 2026 00:21:39 +0000

A WordPress database doesn't tidy itself up over time. Spam comments pile up, expired transients linger, post revisions accumulate, and tables left behind by uninstalled plugins never quite go away. All of that adds up to bloated tables, and occasionally to actual table corruption. This is territory the admin dashboard barely shows you — but WP-CLI reaches it directly with two short commands: wp db check and wp db optimize.

Note: WP-CLI's wp db subcommands operate directly on the MySQL (or MariaDB) database WordPress uses, without going through the admin dashboard. Connection details are read automatically from wp-config.php.

`wp db check` — verifying table health

wp db check

Under the hood, this runs the equivalent of mysqlcheck --check against every table and reports each one's status:

wp_posts                       OK
wp_options                      OK
wp_postmeta                     OK

If a table comes back corrupt, SELECT and INSERT queries against it start failing. That can surface as something oddly specific — a single page going blank, one particular post refusing to save — with no obvious connection to a database problem. Running wp db check on a regular schedule catches that kind of issue before it turns into a visible symptom.

`wp db optimize` — defragmenting tables

wp db optimize

This one runs the equivalent of mysqlcheck --optimize, applying OPTIMIZE TABLE to each table. Tables that see a lot of row deletions and updates tend to become fragmented on disk over time. OPTIMIZE TABLE rebuilds the table and reclaims the space that deleted rows used to occupy.

Note: behavior differs by storage engine. WordPress's default engine, InnoDB, handles OPTIMIZE TABLE internally as a table rebuild (roughly equivalent to ALTER TABLE ... FORCE), which both defragments the table and refreshes its statistics. The older MyISAM engine doesn't reclaim space from deleted rows automatically at all — that disk space only gets released once OPTIMIZE TABLE runs. Some installs set up through a hosting provider's one-click installer still carry MyISAM tables left over from an older default, so it's worth checking for a mixed-engine setup once with wp db query "SHOW TABLE STATUS".

wp db optimize locks each table for writes while it runs. On a large table that can mean a brief slowdown for site visitors, so it's safer to run during a low-traffic window rather than in the middle of the day.

When to actually run these

Neither command causes harm if run at an arbitrary time, but a few moments make the payoff clearer:

Right after a bulk deletion — clearing out spam comments in bulk, deleting a large batch of posts, or uninstalling a plugin that no longer gets used, all shrink row counts suddenly
Before a major update — running wp db check ahead of a large WordPress core or plugin update makes it easier to tell, after the fact, whether a problem was caused by the update or was already sitting in the database beforehand
As part of routine maintenance — folding these into a weekly or monthly cycle turns fragmentation and corruption from "discovered too late" into something checked on a predictable schedule

If corruption turns up — `wp db repair`

When wp db check reports a table as corrupt, WP-CLI offers wp db repair (the equivalent of mysqlcheck --repair) as a next step. Repair isn't guaranteed to restore the data perfectly — depending on how severe the corruption is, some data can still be lost. Taking a fresh backup before attempting a repair is a prerequisite, not an optional step. A backup taken moments before the corruption is worth far more than one taken after the fact.

Summary

What you want to do	Command
Check every table's health	`wp db check`
Defragment tables and reclaim disk space	`wp db optimize`
Attempt to repair a corrupted table	`wp db repair` (back up first)
Check for mixed storage engines	`wp db query "SHOW TABLE STATUS"`

Both wp db check and wp db optimize are lightweight — they finish in seconds to a few minutes — yet they leave a record of the state of the one part of a WordPress site that's hardest to see from the dashboard. That's exactly why it's worth checking mechanically and on a schedule, rather than relying on symptoms to surface first.

WP-CLI's ability to reach the database directly, without going through the admin dashboard, is the same idea behind safely rewriting serialized data with wp search-replace and recovering from a wp-admin lockout. Checking database health is one more basic operation built on that same foundation.

Using WP-CLI aliases to switch between multiple WordPress environments safely

Susumu Takahashi — Mon, 31 Aug 2026 00:19:21 +0000

Anyone managing several WordPress environments — production, staging, or separate installs for different languages — ends up re-typing SSH connection details and install paths every time they run a command. Building that connection string by hand each time invites mistakes: a copy-paste error, or reusing a stale path, can send a command to the wrong environment entirely. That risk matters most for write commands — bulk plugin updates or database operations — where hitting the wrong target has real consequences.

WP-CLI has a built-in feature for exactly this problem: aliases.

Note: A WP-CLI "alias" assigns a short name (like @production) to a set of connection details — an SSH target and a WordPress install path. Once registered, that short name replaces the full connection string on every subsequent command.

Where aliases live

Aliases are registered in one of two config files:

Project-level: wp-cli.yml in the working directory
Global: ~/.wp-cli/config.yml in the home directory

If the same alias name exists in both, the project-level file takes precedence. If the same environments get used across multiple projects, consolidating aliases in ~/.wp-cli/config.yml keeps things easier to manage.

Example registration (config.yml):

@production:
  ssh: user@production.example.com:22
  path: /var/www/production/wordpress

@staging:
  ssh: user@staging.example.com:22
  path: /var/www/staging/wordpress

ssh specifies the username, host, and port; path points to the WordPress install directory. This assumes key-based SSH authentication — passwords should never be written into config.yml. If this file is tracked in a repository, an accidental commit turns it into a leak vector for connection details, so keep it in .gitignore, or store it outside the repository in the home directory instead.

Calling a single alias

Once registered, commands that previously required an ssh login first can run in a single line from your local machine:

wp @production plugin list
wp @staging plugin list

Under the hood, WP-CLI reads the alias's connection details and runs the command against the remote WordPress install over SSH, streaming the result back to the local terminal exactly as if it had run locally.

Running the same command across multiple environments with group aliases

Individual aliases can also be bundled into a "group alias":

@all:
  - @production
  - @staging

wp @all plugin list

Running a group alias makes WP-CLI execute the command against every listed alias in turn, labeling each block of output with which alias it came from. There's no need to retype the same command per environment, and the labeled output makes it easy to trace which result belongs to which site — a form of record-keeping that matters when reviewing what ran where.

Points to watch when using aliases

Aliases trade convenience for a wider blast radius when something is misconfigured. A few things worth keeping in mind:

Name aliases so the environment is obvious at a glance. Short forms like @a or @b become ambiguous the moment you're not looking at the config file — @production and @staging remove that ambiguity
Get in the habit of running wp cli alias list before executing anything unfamiliar. It shows the currently registered aliases and their targets without needing to open the config file directly
Avoid running write commands through a group alias. Something like wp plugin update --all or a wp db command run against @all can't be stopped partway if the first environment produces an unexpected result. Read-only commands (plugin list, checking core version, and similar) are a good fit for group execution when you just need a status overview; commands that change state are safer run one alias at a time, with a chance to confirm each result before moving to the next
Consider separating SSH keys by environment. Reusing one key across multiple production environments means a single key compromise affects all of them. Depending on how critical each environment is, splitting keys is worth considering

Summary

What you want to do	Command
List registered aliases	`wp cli alias list`
Run a command against a single alias	`wp @production plugin list`
Run a command across all environments at once	`wp @all plugin list`
Run one environment at a time (safer for write commands)	Execute manually per alias

When working across multiple WordPress environments, registering aliases once tends to prevent more mistakes than building connection strings by hand each time. Group alias output labels which environment produced which result, which makes it well suited to read-only status checks. Bulk-running write commands across environments deserves more caution — in situations where accuracy and traceability matter more than speed, running one environment at a time on purpose is a reasonable choice to keep.

WP-CLI's ability to reach into WordPress without going through the admin dashboard shows up elsewhere in this series too: inspecting what's actually scheduled in WP-Cron and recovering from a wp-admin lockout. Aliases extend that same idea to the problem of managing connection details across several environments at once.

Comparing pricing models across four WordPress maintenance tools — what the shape of a price reveals about cost structure

Susumu Takahashi — Fri, 28 Aug 2026 23:27:22 +0000

Background

While surveying the major WordPress maintenance tools (ManageWP, MainWP, WP Umbrella, and InfiniteWP), one thing stood out once their pricing was laid side by side: this isn't just a matter of "cheaper vs. more expensive." The shape of the pricing itself differs completely from company to company. And that shape isn't arbitrary — it closely mirrors how each company actually delivers its service.

Four companies, four pricing shapes

ManageWP: free core, stacked per-site add-ons

The core dashboard is free. Features like Backup, Security, Reports, and White-Label are sold separately as per-site monthly add-ons, typically $1–$2 each. This gives flexibility to pay only for what you need, but assembling the full feature set means costs stack up as (number of sites) × (number of add-ons). Starting free and paying only for the pieces you want is a classic pattern for a SaaS built from independently billed feature modules.

MainWP: free core (self-hosted) plus a flat Pro extension fee

MainWP's dashboard itself is open source and free. The practical features (backup extension, reporting extension, etc.) come as Pro Extensions, priced at $29/month, $199/year, or a one-time $599. What's easy to overlook here: you must provide, host, and maintain the WordPress site that runs this dashboard yourself. The software itself is free, but the infrastructure cost and upkeep of running it fall on you separately. It's a pricing model that closely inherits the culture of open-source, self-hosted software.

WP Umbrella: a single flat per-site rate

€1.99 per site per month, a clear and uniform rate regardless of scale. Because it's cloud-based and runs independent uptime monitoring, PHP error monitoring, and PageSpeed checks for every site, its own infrastructure cost genuinely scales roughly linearly with the number of sites monitored. Because the company's own cost structure scales linearly, billing customers at a single flat per-site rate lines up naturally with that cost. It's a case where the cost structure and the pricing model match cleanly.

InfiniteWP: free core plus an annual add-on license

The core is free and supports unlimited sites, but the practical agency-grade features (backup, white-label, scheduling, uptime monitoring) come as an add-on, sold as an annual license starting at $147/year. A hosted version (a bundle covering 100 sites) is also available at $597/year. Paying the same amount again every year to renew is a structure that reflects a software-licensing tradition inherited from the on-premise era, more than a continuously metered cloud service. Cost doesn't fluctuate finely with site count — it's bundled by license unit instead.

The shape of a price is a mirror of cost structure

Laying all four side by side, the differences in pricing model turn out not to be arbitrary marketing choices — they reflect how each company actually delivers its service.

If cloud infrastructure monitors each site independently, cost scales with the number of sites — so per-site metered billing is the natural fit (WP Umbrella).
If the customer runs their own dashboard, the company's own infrastructure cost is effectively passed on to the customer — so a flat, software-license-style fee makes sense (MainWP).
If each feature is delivered as its own independent service (backup storage, an uptime-monitoring server, etc.), per-feature metered billing arises naturally (ManageWP).
An annual bundled-renewal model reflects more of a "right to use a software asset" mindset than an ongoing cloud operating cost (InfiniteWP).

Note: SaaS (Software as a Service) is a delivery model where software is used over the internet rather than installed locally, typically billed monthly or annually as a subscription. What varies between providers is the unit of that billing — per site, per feature, or per license — and that unit tends to follow directly from the provider's own infrastructure structure.

What to watch for when comparing quotes

Understanding these differences in pricing shape makes it easier to spot costs that a simple "how much per month" comparison hides. MainWP's Pro Extension price alone looks inexpensive, but the hosting cost and upkeep of the WordPress site running the dashboard are separate and easy to miss. ManageWP lets you start free, but assembling the full feature set means paying for every add-on you need, one by one.

Looking at what cost structure a pricing model actually assumes — rather than just the headline number — gives a clearer picture of the real total cost of running the tool, and whether it fits how you actually work.

Differences in connection architecture and rollback design, beyond pricing, are covered in two earlier pieces: "Connection architectures for WordPress maintenance tools — mapping four products on a two-axis grid" and "Three gaps the WordPress maintenance industry still hasn't solved — from a survey of four major tools." Read together, they give a fuller picture of how differently this industry's tools are designed.

A tabbed form that silently refused to submit — required fields hidden behind another tab

Susumu Takahashi — Fri, 28 Aug 2026 00:21:37 +0000

Background

The site edit modal kept accumulating fields — site name, category, SSH connection details, WordPress install location — until editing anything meant scrolling up and down a single long form to find the right field. To clean this up, we split it into three tabs: "Registration info," "SSH," and "WordPress info." That change broke form submission itself, in a way that was hard to spot at first.

What tabbing broke

The tab implementation itself is straightforward. Each tab's fields live in a <div class="site-tab-content" data-tab="...">, and CSS toggles which one is visible.

.site-tab-content { display: none; }
.site-tab-content.active { display: block; }

An inactive tab is hidden with display: none. Nothing unusual so far, and visually it worked fine.

The problem showed up when a required field sat in a tab that was not currently active, and the user left it empty while saving from a different tab. Clicking the save button did nothing. No error message appeared. The form just looked stuck.

Root cause: a browser cannot report an error on a field it cannot show

HTML5 form validation works by having the browser automatically block the submit event whenever a constrained field (like required) fails, then focusing that field and showing its standard validation bubble (equivalent to calling reportValidity()).

Note: reportValidity() is a method from the HTML5 Constraint Validation API. It checks whether a form element's value satisfies its constraints (required, pattern, etc.) and, if not, displays the browser's standard error bubble.

But when the failing field sits inside a tab hidden with display: none, the browser has nowhere to anchor that error bubble. It still faithfully blocks the submit — but it cannot visualize the error, so it simply stops without any visible feedback. From the user's side, this looks exactly like a button that does not respond.

Before tabbing, every field lived on the same screen, so this never surfaced. Introducing tabs — a UI pattern that deliberately limits what's visible at once — broke an implicit assumption the browser's built-in validation depends on: that an invalid field is always visible.

The fix: novalidate plus JS-driven validation

The fix was to stop relying on the browser's automatic blocking. Adding novalidate to the form disables that automatic block and guarantees the submit event always fires, letting JavaScript take full control of validation.

async function saveSite(e) {
    e.preventDefault();
    const form = e.target;

    // If checkValidity() fails, switch to the tab containing the first
    // :invalid element, then focus it and call reportValidity().
    if (!form.checkValidity()) {
        const firstInvalid = form.querySelector(':invalid');
        if (firstInvalid) {
            const tabContent = firstInvalid.closest('.site-tab-content');
            if (tabContent && tabContent.getAttribute('data-tab')) {
                switchSiteTab(tabContent.getAttribute('data-tab'));
            }
            // Focus/scroll may not work right after a tab switch,
            // so call reportValidity() on the next frame.
            requestAnimationFrame(() => {
                try { firstInvalid.focus({ preventScroll: false }); } catch (_) {}
                firstInvalid.reportValidity();
            });
        }
        return;  // abort submission on validation failure
    }
    // ...normal save flow continues here
}

Two things matter here.

novalidate does not disable the constraints themselves. Attributes like required and pattern remain in effect, and both checkValidity() and the :invalid pseudo-class still work as expected. What novalidate disables is only the browser's automatic "block submit and show the error" behavior.
The code finds the first :invalid element and forces a switch to its tab before calling reportValidity(). By making the field visible first, the browser can render its error bubble without issue. Since a tab switch may not have finished painting yet, the code waits one frame via requestAnimationFrame before calling focus() and reportValidity().

A concrete case: making the SSH profile conditionally required

This mechanism paid off directly with the SSH profile requirement. The site edit modal has an "Update via browser only (no SSH)" checkbox; leaving it unchecked makes selecting an SSH profile mandatory. We wanted to prevent saving a site that satisfies neither option — no profile selected, and the checkbox left unchecked.

function toggleSSHFields() {
    const isBrowserOnly = document.getElementById('browser_only_check').checked;
    const profileSelect = document.getElementById('server_profile_select');

    if (isBrowserOnly) {
        // Browser-only mode doesn't need a profile
        profileSelect.value = "";
        profileSelect.removeAttribute('required');
    } else {
        // SSH mode requires a profile
        profileSelect.setAttribute('required', '');
    }
}

The required attribute is toggled dynamically based on the checkbox state, and the rest is handled by the cross-tab validation logic in saveSite described above. Trying to save without a profile selected automatically opens the "SSH" tab and shows the error bubble right on the profile dropdown. The user never has to hunt for why saving isn't working.

A side benefit: accessibility via ARIA

Alongside the tab split, we added role="tablist" / role="tab" / role="tabpanel" and aria-selected / aria-controls / aria-labelledby.

<div class="site-tabs" role="tablist" aria-label="Site edit tabs">
    <button type="button" class="site-tab-btn active" role="tab"
            id="site-tab-btn-info" aria-selected="true"
            aria-controls="site-tab-panel-info">Registration info</button>
    <!-- SSH and WordPress info tabs follow the same pattern -->
</div>

The tab-switching JavaScript keeps aria-selected in sync as well.

function switchSiteTab(tabName) {
    form.querySelectorAll('.site-tab-btn').forEach(btn => {
        const isActive = btn.getAttribute('data-tab-target') === tabName;
        btn.classList.toggle('active', isActive);
        btn.setAttribute('aria-selected', isActive ? 'true' : 'false');
    });
}

It is not just a visual toggle — screen reader users also get told which tab is currently selected.

Wrap-up

Splitting a form into tabs feels like an intuitive cleanup, but it can quietly break an assumption the browser's built-in validation depends on: that an invalid field is always visible on screen. Disabling the automatic block with novalidate, keeping the constraint checks alive through checkValidity() / :invalid, and making the failing field visible before calling reportValidity() — that small extra step is what lets a tabbed UI coexist with standard form validation. It's a modest but broadly reusable pattern for any design that splits a form across multiple views.

DEV Community: Susumu Takahashi

Code signing basics — what Apple Notarization and Windows Authenticode actually certify

What a signature proves — and what it doesn't

Apple's model: signing and Notarization are separate layers

Bundle signing order: inside out

Windows' model: Authenticode and the certificate chain

Without a timestamp, an expired certificate drags past signatures down with it

SmartScreen reputation is a separate axis from the signature itself

Summary

Running Flask's dev server as a desktop app's backend — what actually matters

The warning is about an unpredictable crowd of clients

Turn off the auto-reloader — it breeds a second process

Set threaded=True explicitly — or concurrent access will stall

Concurrent threads mean you now have to guard shared state

You own port allocation and duplicate-instance detection

The server has no way of knowing a browser tab was closed

Summary

Atomic writes — how tempfile + os.replace prevent corrupted JSON

Why direct overwrites are dangerous

The fix: write to a temp file, then swap it in

Why os.replace() is atomic

Forcing persistence to disk with os.fsync()

Cleaning up after a failed write

Guarding against leftover .tmp files

Summary

Cross-platform file locking in Python — fcntl vs msvcrt from scratch

Why avoid a third-party library

Unix-like systems: fcntl.flock is an advisory lock

Windows: msvcrt.locking locks an explicit byte range

The core abstraction: branch on sys.platform

A design choice: don't lock the target file itself

Making lock acquisition atomic with O_CREAT | O_EXCL

The remaining gap: stale locks

Wrapping it as a context manager for with

Summary

Crontab syntax basics, and how it differs from WP-Cron

The five time fields

Common patterns worth memorizing

Editing with crontab -e

The PATH environment trap

How this differs fundamentally from WP-Cron

Switching to a real crontab entry

Summary

Organizing per-host settings with `~/.ssh/config` — a standard practice for anyone managing multiple servers

Basic structure

Why IdentitiesOnly yes matters

Grouping shared settings across similar servers with wildcards

Splitting the config file with Include

How this differs from WP-CLI aliases

A security note

Summary

SSH key types (RSA / ED25519 / ECDSA) — what actually differs, and which one to pick

What actually differs between the three types

Key size and the speed difference you'll actually notice

Which one should you actually use

Generating a key (general steps)

Summary

How the WordPress transient API works, and when `wp transient delete` actually helps

How a transient actually works

Why expired entries stick around

Inspecting and cleaning up with wp transient

When it's worth running

Summary

`wp db check` / `wp db optimize` — the database health commands that get overlooked

wp db check — verifying table health

wp db optimize — defragmenting tables

When to actually run these

If corruption turns up — wp db repair

Summary

Using WP-CLI aliases to switch between multiple WordPress environments safely

Where aliases live

Calling a single alias

Running the same command across multiple environments with group aliases

Points to watch when using aliases

Summary

Comparing pricing models across four WordPress maintenance tools — what the shape of a price reveals about cost structure

Background

Four companies, four pricing shapes

The shape of a price is a mirror of cost structure

What to watch for when comparing quotes

Set `threaded=True` explicitly — or concurrent access will stall

Why `os.replace()` is atomic

Forcing persistence to disk with `os.fsync()`

Guarding against leftover `.tmp` files

Unix-like systems: `fcntl.flock` is an advisory lock

Windows: `msvcrt.locking` locks an explicit byte range

The core abstraction: branch on `sys.platform`

Making lock acquisition atomic with `O_CREAT | O_EXCL`

Wrapping it as a context manager for `with`

Editing with `crontab -e`

Why `IdentitiesOnly yes` matters

Splitting the config file with `Include`

Inspecting and cleaning up with `wp transient`

`wp db check` — verifying table health

`wp db optimize` — defragmenting tables

If corruption turns up — `wp db repair`