This is the routine I followed: a database backup with the WP-CLI console built into Plesk’s WP Toolkit, an FTP download, a quick check that the dump is complete, a version inventory to roll back from, and then updates in batches by risk. It takes about 15 minutes before the first update, and all of it can be repeated on the next site.

Why not just use Plesk’s backups?

Plesk already had nightly incremental backups for this account, which is good, but they weren’t the right tool for rolling back a plugin update:

• They cover the whole subscription. The subscription hosted more than one site. Restoring it to undo a broken plugin risks rolling back a site you never touched, unless you pick through the restore options very carefully.
• They’re from last night. Anything changed since then, such as a content edit made this morning, would be lost in a restore.
• No per-site snapshot. I went looking for WP Toolkit’s per-site backup. On this server, every backup button led to the full subscription backup in Backup Manager.

What a plugin update changes is the database (migrations, new options) and the plugin’s own files. So that’s what to secure.

Step 1: Export the database with WP Toolkit’s WP-CLI

In Plesk, open the site in WP Toolkit and click WP-CLI. You get a single command field with wp already filled in, so you type everything after it. There’s no shell, so no pipes, gzip or ls. That’s fine, because wp db export does the whole job:

db export ../site-pre-updates-2026-10-13.sql

The ../ matters. It writes the dump one level above the web root, so it can’t be downloaded by URL, whatever it’s called. If your account can’t write there, drop the ../ and remember to delete the file from the web root afterwards.

Expected output:

Success: Exported to '../site-pre-updates-2026-10-13.sql'.

WARNING: option --ssl-verify-server-cert is disabled, because of an insecure passwordless login.

The warning comes from the MariaDB client about a local socket connection and is harmless here.

Step 2: Download it over FTP

Connect over FTP, go one level up from the web root, and download the .sql file to your machine. Now you have a copy that doesn’t depend on the server.

If the folder you download into is a git repo, as my per-client notes folder is, ignore the dump before you forget:

backups/
*.sql
*.sql.gz

A database dump contains user accounts, password hashes and form entries. It should never be committed, private repo or not.

Step 3: Check that the dump is complete

Don’t trust a backup you haven’t looked at. Three quick checks on your machine:

ls -lh backups/site-pre-updates-2026-10-13.sql          # not zero, plausible size
grep -c 'CREATE TABLE' backups/site-pre-updates-2026-10-13.sql   # table count
tail -c 200 backups/site-pre-updates-2026-10-13.sql     # ends with "Dump completed on ..."

Mine was 13.7 MB with 35 tables and ended with -- Dump completed on 2026-10-13 3:26:20. A missing “Dump completed” line means the export was cut off. If the table count looks low, compare it with db tables in the WP-CLI console.

Step 4: Record versions before changing anything

Back in the WP-CLI console, run three read-only commands:

plugin list --fields=name,status,version,update_version

theme list --fields=name,status,version,update_version

core check-update

Paste the output into your notes. That list is your file-level rollback. For anything from wordpress.org, going back is one command:

plugin install <slug> --version=<old-version> --force

Paid plugins are the exception. ACF Pro, Gravity Forms and its add-ons can’t be reinstalled from wordpress.org at an older version. Before updating them, zip their folders in Plesk’s File Manager (wp-content/plugins/gravityforms → Add to archive), or download the current version from the vendor’s account.

Step 5: Sort the updates by risk

The version list tells you what’s pending. The theme code tells you what’s dangerous. On this site:

• Major version jumps: Gravity Forms 2.10 → 3.1, Smush 3 → 4, GTM4WP 1 → 2, and Yoast 25 → 28.
• Plugins the theme calls directly. A grep through the theme turned up custom Gravity Forms submit buttons. A gform_submit_button_{id} filter replaced the button markup with HTML that calls window.gform.submission.handleButtonClick(). If a major Gravity Forms release changes that JavaScript API, every form on the site stops submitting, and nobody notices until enquiries stop coming in.
• Plugins that hold content structure. The theme registered no post types itself. The team-members post type behind the agent photos came from Custom Post Type UI, so an innocent-looking minor update to it could still break the front end.
• The custom theme’s name. A custom theme whose folder name happens to match a theme on wordpress.org can show an “update”. Never apply it, or your theme gets replaced with someone else’s. Here the custom theme showed no update, but check every time.

grep -rn "gform_\|register_post_type\|acf_\|get_field" --include='*.php' wp-content/themes/your-theme | head

The result is a set of batches:

Step 6: Update a batch, then check from outside

Batch 1 in the WP-CLI console:

theme update twentytwentyfive twentytwentyfour twentytwentyone twentytwentythree twentytwentytwo

plugin update wp-crontrol duplicate-page svg-support wp-mail-smtp custom-post-type-ui google-site-kit updraftplus

Then flush the page cache (LiteSpeed in this case) and check the live site from your own machine, bypassing any cache with a query string:

for u in "" some-listing-page/ another-key-page/; do
  curl -sL -o /tmp/p.html -w "$u HTTP %{http_code} %{time_total}s\n" \
    "https://example.com/$u?nocache=$(date +%s)"
  grep -qi "critical error\|Fatal error" /tmp/p.html && echo "  PHP ERROR on /$u"
done

A 200 status with no “critical error” is the minimum. Then check what this site specifically depends on. Here that was the agent name and photo on each listing card and the team section, so I counted those in the HTML.

Step 7: Confirm the versions with WP-CLI, not the admin badge

After batch 1, the admin still said 20 updates and listed WP Crontrol at its old version. WP-CLI said otherwise:

plugin list --fields=name,version,update_version

Every plugin in the batch showed its new version and an empty update_version. The admin was showing an old count from before the updates, and reloading the Updates screen cleared it. Trust plugin list, not the badge.

Step 8: Get approval before the risky batches

This site is managed through an agency, and extra work only gets paid if it was agreed beforehand. Batch 1 was small enough to include in time already being billed. For batches 2–4 I sent a short message instead: which updates are pending, why Gravity Forms 3 needs care, a time estimate, and a request to go ahead. Do the risky work after a yes, not before.

Cleanup

When the updates are done, or if they’re postponed, delete the server-side dump:

• In Plesk’s File Manager, go one level above the web root and delete site-pre-updates-*.sql.
• Keep the local copy until the site has run cleanly for a few days.

The checklist

1. WP Toolkit → WP-CLI:  db export ../site-pre-updates-YYYY-MM-DD.sql
2. FTP: download the dump, keep it out of git
3. Verify: size, CREATE TABLE count, "Dump completed" footer
4. WP-CLI: plugin list / theme list / core check-update → save as rollback reference
5. Archive paid plugin folders (File Manager) before updating them
6. Grep the theme for plugin hooks; sort updates into risk batches
7. Per batch: update → flush cache → curl check → plugin list to confirm
8. Ask before major or billable updates
9. Delete the server-side dump

If you only have FTP and no control panel at all, the database step is harder. I covered a PHP-script approach in WordPress Database Backup When You Only Have FTP.

This is the kind of routine maintenance we do for client WordPress sites at Imagewize. If your sites are carrying a pile of pending updates that nobody dares to click, get in touch.

Do you do plugin updates differently on Plesk? Find me on Mastodon at @jfrumau@mastodon.social.

This post is the checklist I now follow, written down after refreshing three sites in one sitting (a main site, a multisite demo network and a small marketing site, all on Trellis with a Lima VM).

Pick the command that does the whole job

wp-ops has two families of database commands, and they are not equivalent:

db-pull is the one I reach for now. It streams wp db export from the remote straight into the VM’s database with no intermediate file, and it runs wp search-replace twice (the full URL, then the home URL, covering https:// and a stray http://). The thing I had previously done wrong was using a plain backup/download command and importing by hand, which skips the replace step entirely.

Before you pull

1. Is the VM running? trellis vm shell drops you into a shell if so, and errors if not. The local databases live in the VM.
2. Check what “local” means. The replace target comes from trellis/group_vars/development/wordpress_sites.yml. If site_hosts.0.canonical is wrong there, the pull will faithfully rewrite everything to the wrong hostname.
3. Export TRELLIS_DIR to your Trellis directory so the playbooks find their inventory:

export TRELLIS_DIR=$PWD/trellis

The pulls

wp-ops db-pull example.com production --yes
wp-ops db-pull demo.example.com production --multisite --yes
wp-ops db-pull small-site.com production --host example.com --yes

Two flags are easy to forget:

• --multisite for a network. It also fixes the wp_blogs and wp_site domain rows and scopes the search-replace with --url. Without it, subsites keep their production domains and the network breaks. On my demo network that was 9 rows corrected plus 93,000-odd link replacements in one run.
• --host when the site lives on a server whose SSH name differs from the site name. One of mine is hosted on another site’s server, and SSH to its own hostname failed host-key verification, so the default (derive the host from the site name) can’t work.

I run them one at a time. Each prints numbered steps (read dev URL, back up local, pull, import, replace, flush cache), and the “Made N replacements” lines are a quick sanity check: a main site with 88 replacements, a tiny site with 37.

Each run also writes dev_backup_<timestamp>.sql.gz into the site’s database_backup/ folder before importing. That’s your undo button. Check that folder isn’t tracked by git.

Don’t forget the uploads

The database pull doesn’t touch wp-content/uploads. Without it you get correct pages with broken images:

wp-ops files-pull example.com production

Run it per site. It’s rsync, so repeat pulls are cheap. I confirmed it worked by counting files afterwards (about 17,000 for the main site), because the Ansible recap says skipped=4 even on success, which looks alarming and isn’t.

Verify, don’t assume

Three checks per site, all through WP-CLI inside the VM:

wp option get home
wp option get siteurl
wp db query "SELECT COUNT(*) FROM wp_posts WHERE post_content LIKE '%://example.com%'"

home and siteurl should be the .test URLs, and the count should be 0. A looser search for just example.com still returned a few hundred hits on the main site, and every one was an email address or plain-text mention. Searching for the scheme (://) is what separates real links from noise. On a multisite network also run wp site list and confirm every subsite shows the local domain.

Side effects to expect

• Production-only plugins come along for the ride. The pulled database re-activates everything production had active, including a 2FA plugin that has no business running locally. While active, it wrote its encryption key into wp-config.php, an uncommitted change and a secret. I reverted the file with git checkout, then deactivated the plugin on every local site so it wouldn’t happen again: wp plugin deactivate <plugin>, or with --network on a multisite where it is network-active (plain deactivate refuses with a warning). Make this a post-pull step.
• Shell gotcha. I separated two commands with echo ===== and zsh answered =====: not found, which aborted the rest of the line. The second pull silently didn’t run until I noticed. Use &&, or run each command separately.
• Theme state. If your themes are Composer-installed and git-ignored, a database pull doesn’t change them, but production’s active theme and any page or template-part overrides now apply locally. If a recent theme fix doesn’t show up, the content in the database is probably shadowing the theme files.

The short version

export TRELLIS_DIR=$PWD/trellis
wp-ops db-pull <site> production --yes            # + --multisite / --host as needed
wp-ops files-pull <site> production
wp option get home && wp option get siteurl        # expect .test

Use the command that backs up, imports and replaces, pass the multisite and host flags where they apply, pull the uploads separately, and verify with a scheme-anchored search. That’s the whole difference between a refresh I trust and one I have to redo.

The Visual Problem

Issue #9 was straightforward on the surface: on phones, the light header’s mobile menu overlay rendered with core’s default unstyled look — white background, black text, right-aligned links, no dividers — none of which matched the rest of the site’s chalk-and-ivy palette. The design called for a base (chalk) background, secondary (ivy-green) Roggenkamp typography, left-aligned links with rule-coloured (border-light) dividers between them, and a full-width Contact CTA button below the links.

Simple enough. The overlay needed restyling, the links needed left-aligning, and the CTA needed appending. What wasn’t obvious: headless Chrome would spend the better part of a debugging session convincing us the header itself was broken.

The First Hurdle: Testing the Overlay at All

Mobile overlays are stateful — the hamburger has to be clicked to open them, and core’s responsive container only switches into its fixed-position modal once the viewport is narrow enough for overlayMenu: "mobile" to kick in. That means:

• You can’t test the closed state at desktop width and infer the open one
• You can’t force the state with a class toggle and trust the CSS is identical to what the real click produces
• You need an actual narrow viewport and a real click

Static HTML snapshots or DOM hacks that toggle is-menu-open miss any JavaScript that runs during the real transition. A real interaction test, at a real phone width, was the only reliable check.

Enter Headless Chrome

My first instinct was the usual headless Chrome one-liner:

chrome --headless=new --window-size=390,700 --screenshot=/tmp/ecotuin-390.png https://ecotuin.test/

Then click the hamburger via DevTools Protocol or a small Puppeteer script, wait for the overlay to open, screenshot again. Standard workflow.

What I got back looked alarming: between 375px and 430px, the header’s right edge overflowed the viewport and the hamburger icon was clipped off-screen. The overlay itself was fine once open, but the trigger to open it was unreachable. That suggested the header’s padding or the icon’s positioning was fundamentally broken at those widths.

Except it wasn’t. A manual check on a real iPhone showed the hamburger sitting exactly where it should. Retesting with Playwright at the same viewport widths confirmed: no overflow, no clipping, hamburger fully visible and tappable. The bug didn’t reproduce at all.

The Footgun: --window-size Below ~500px

The culprit, documented in the project’s internal CLAUDE.md notes: headless Chrome silently ignores viewport widths below roughly 500px when launched via --window-size. It renders at a wider width instead (around 500px minimum, inconsistently), and doesn’t tell you it’s doing so. The screenshot you get back looks plausible — it’s a real render, just not at the width you asked for — and if your layout has a breakpoint or overflow issue between 375px and 500px, you’ll never see it in that test.

In our case, the lie was the opposite direction: the screenshot showed an overflow that didn’t exist at the requested 375px, because Chrome was actually rendering at ~500px where the header did fit. The phantom bug sent us down a rabbit hole of header padding checks and icon positioning that all looked fine in isolation, because the real problem was the testing tool itself.

Playwright’s viewport: { width, height } parameter, by contrast, is exact — pass 390 and it renders at 390, every time. And because node_modules/playwright already exists (pulled in by wp-pattern-sentinel), there’s no extra install step:

const { chromium } = require('/Users/…/ecotuin/node_modules/playwright');
const browser = await chromium.launch();
const page = await browser.newPage({ viewport: { width: 390, height: 700 } });
await page.goto('https://ecotuin.test/', { waitUntil: 'networkidle' });
await page.click('.wp-block-navigation__responsive-container-open');
await page.screenshot({ path: '/tmp/overlay-open-390.png' });

That’s the pattern we now use for any check where the actual viewport width matters below ~500px.

The Second Hurdle: CTA Placement

The design’s mobile dropdown ends with a full-width Contact button directly below the navigation links. In the Site Editor, those links live in a separately-stored Navigation menu (the “Diensten / Werkwijze / Projecten / …” items), not inline in the template part. core/navigation has a quirk: it only renders its referenced menu when the block has no inner blocks of its own. If you add inner blocks to the nav in parts/header.html — say, a core/buttons block for the CTA — WordPress replaces the referenced menu with those inner blocks instead of appending to it. The real links disappear.

That meant the CTA couldn’t be part of the template part’s markup. Two options remained:

1. Add the CTA link to the Navigation menu itself in the WordPress admin. Simple, but it pollutes the menu’s desktop presentation (an extra “Contact” item in the inline nav at desktop width) and the client would see it as a menu item they could reorder or remove.

2. Append the CTA via a filter after rendering. render_block_core/navigation fires after WordPress has assembled the block’s HTML from its referenced menu, so we can inject additional markup at that point without touching what the block stores.

We went with option 2. The function scopes itself to the light header’s nav via a className (ecotuin-header__nav), appends a full-width button block right after the </ul>, and lets CSS hide it everywhere except the open overlay:

function ecotuin_header_nav_cta( $block_content, $block ) {
    $class_name = $block['attrs']['className'] ?? '';

    if ( false === strpos( $class_name, 'ecotuin-header__nav' ) ) {
        return $block_content;
    }

    $cta = sprintf(
        '<div class="wp-block-buttons ecotuin-header__overlay-cta"><div class="wp-block-button wp-block-button__width-100"><a class="wp-block-button__link wp-element-button" href="%s">%s</a></div></div>',
        esc_url( home_url( '/contact/' ) ),
        esc_html__( 'Contact', 'ecotuin' )
    );

    return preg_replace( '#</ul>#', '</ul>' . $cta, $block_content, 1 );
}
add_filter( 'render_block_core/navigation', __NAMESPACE__ . '\ecotuin_header_nav_cta', 10, 2 );

CSS then hides it by default and only shows it inside the open overlay:

.ecotuin-header__overlay-cta {
    display: none;
}

.ecotuin-header:not(.ecotuin-header--dark) .wp-block-navigation__responsive-container.is-menu-open .ecotuin-header__overlay-cta {
    display: flex;
    margin-top: var(--wp--preset--spacing--small);
}

The CSS Fixes: Alignment and Full-Width Links

With the CTA in place, the styling itself fell into three pieces:

1. Raising the Breakpoint

Core hardcodes overlayMenu: "mobile" to collapse at 600px. Between 600px and 1024px, the inline nav competed with the wordmark, cart/account icons, and CTA, wrapping the masthead to 105px tall on tablets. We raised the effective breakpoint to 1024px by re-declaring the two core rules that switch the container between overlay and inline:

@media (min-width: 600px) and (max-width: 1023px) {
    .ecotuin-header .wp-block-navigation__responsive-container:not(.hidden-by-default):not(.is-menu-open) {
        display: none;
    }

    .ecotuin-header .wp-block-navigation__responsive-container-open:not(.always-shown) {
        display: flex;
    }
}

2. Left-Aligning Links and Full-Width Dividers

Core’s overlay right-aligns the link list via align-items: flex-end in two places: on the container-content and on each navigation item. That shrink-wraps each <li> to its text width and pins it to the right edge — fine for a right-aligned desktop nav, but not what the design called for.

Design v3e uses display: block for mobile list items, so each one spans the full width and the divider border runs edge-to-edge. We reproduced that with align-items: stretch in both locations, then added text-align: left to position the text within the now full-width box:

.ecotuin-header .wp-block-navigation__responsive-container.is-menu-open .wp-block-navigation__responsive-container-content,
.ecotuin-header .wp-block-navigation__responsive-container.is-menu-open .wp-block-navigation__container,
.ecotuin-header .wp-block-navigation__responsive-container.is-menu-open .wp-block-navigation-item {
    align-items: stretch;
}

.ecotuin-header .wp-block-navigation__responsive-container.is-menu-open .wp-block-navigation__container {
    text-align: left;
}

3. Styling to Match v3e Design

Finally, the visual restyling to match the design’s mobile dropdown:

/* Chalk background, ivy text */
.ecotuin-header:not(.ecotuin-header--dark) .wp-block-navigation__responsive-container.is-menu-open {
    background-color: var(--wp--preset--color--base) !important;
    color: var(--wp--preset--color--secondary) !important;
}

/* Rule-coloured dividers between links */
.ecotuin-header:not(.ecotuin-header--dark) .wp-block-navigation__responsive-container.is-menu-open .wp-block-navigation-item__content {
    border-bottom: 1px solid var(--wp--preset--color--border-light);
    font-size: 1.25rem;
    padding-block: 0.75rem;
}

/* Remove the underline that works as a divider on desktop */
.ecotuin-header .wp-block-navigation__responsive-container.is-menu-open .wp-block-navigation-item__content::after {
    content: none;
}

The !important flags are necessary because core emits its own !important selectors for color handling on navigation blocks without explicit background/text colors.

The Takeaways

1. Don’t trust headless Chrome below ~500px width. Use Playwright for any narrow-viewport check where the exact width matters. It’s already a dependency in many WordPress projects via pattern validation or other tooling, so there’s often no extra setup.

2. core/navigation replaces referenced menus with inner blocks. If your nav references a separately-stored menu and you need to add content to it (like a CTA button that only appears in the overlay), do it via render_block_core/navigation, not by editing the template part’s markup.

3. Overlay state needs real interaction. Static snapshots or class toggles miss JavaScript that runs during the real transition. A real click test at the real width is the only way to be sure.

4. Core’s overlay CSS makes assumptions about alignment. It right-aligns for a right-anchored desktop nav, which doesn’t translate cleanly to left-aligned mobile designs. Overriding align-items and text-align together gets you full-width items with left-aligned text.

5. Document the footguns. We added the headless Chrome warning to the project’s internal CLAUDE.md notes so the next person (or the next project) doesn’t repeat the same time sink. Small notes like that pay for themselves the first time someone else hits the same issue.

What This Looked Like in Practice

The PR that shipped this (#10) touched eight files across six commits:

• parts/header.html — added ecotuin-header__nav className for scoping
• functions.php — the render_block_core/navigation filter for CTA injection
• style.css — breakpoint raise, alignment fixes, color palette application, CTA visibility toggles
• CLAUDE.md — the headless Chrome footgun documentation
• Version files: style.css header, readme.txt, package.json, CHANGELOG.md

Total: ~185 lines added/modified, with the actual overlay styling being a minority of the effort. The rest was testing infrastructure and placement mechanics.

This is the kind of careful, edge-case-aware WordPress work we do at Imagewize. If you’re building block themes and hitting surprising layout or testing issues — or just want to avoid the headless Chrome trap on your next responsive check — get in touch.

Questions about block theme navigation or mobile overlay testing? Find me on Mastodon at @jfrumau@mastodon.social.

Scope note: this backs up the database only — posts, options, users, terms, everything in MySQL. It does not touch wp-content/uploads, themes, or plugin files. If you need a full-site backup, use FTP to also download those directories; the database is just the part you can’t grab as a folder copy.

The Constraints

When you only have FTP, the usual tools are off the table:

• No wp db export — WP-CLI requires shell access
• No mysqldump — command line only
• No phpMyAdmin — not installed, and you can’t install it
• No adminer.php — same problem: no upload path for a new tool
• No CPanel/Plesk backups — no control panel at all

What you do have: the ability to upload a PHP file to the site root, trigger it via a browser, and download the result. That is enough.

The DIY PHP Script Method

Create a file named backup-db.php with this content:

<?php
require('wp-load.php');

$db = new wpdb(DB_USER, DB_PASSWORD, DB_NAME, DB_HOST);
$tables = $db->get_results('SHOW TABLES', ARRAY_N);
$output = '';

foreach ($tables as $table) {
    $table_name = $table[0];
    
    // Table structure
    $output .= "--\n-- Table: $table_name\n--\n";
    $output .= "DROP TABLE IF EXISTS `$table_name`;\n";
    $create = $db->get_row("SHOW CREATE TABLE `$table_name`");
    $output .= $create->{'Create Table'} . ";\n\n";
    
    // Table data
    $rows = $db->get_results("SELECT * FROM `$table_name`");
    foreach ($rows as $row) {
        $output .= "INSERT INTO `$table_name` VALUES(";
        $output .= implode(',', array_map(function($val) use ($db) {
            return is_null($val) ? 'NULL' : $db->prepare('%s', $val);
        }, (array)$row));
        $output .= ");\n";
    }
}

$filename = 'wp-content/backup-' . date('Y-m-d-His') . '.sql';
file_put_contents($filename, $output);

echo "Backup complete. Download: <code>/wp-content/{$filename}</code>";

Step-by-Step

1. Create the file locally with the code above
2. Upload it to the site root via FTP (same directory as wp-config.php)
3. Access it in your browser: https://example.com/backup-db.php
4. Download the backup from /wp-content/backup-YYYY-MM-DD-HHMMSS.sql via FTP
5. Delete the script immediately — this is critical (see Security Notes below)

What It Does

The script connects using the same credentials WordPress itself uses (DB_USER, DB_PASSWORD, DB_NAME, DB_HOST from wp-config.php), via WordPress’s own wpdb class, then:

1. Lists every table in the database
2. For each table: writes a DROP TABLE IF EXISTS statement, the full CREATE TABLE definition, and every row as an INSERT statement
3. Escapes every value with wpdb::prepare() before writing it, so quotes, newlines, and other special characters in post content don’t break the dump
4. Saves the complete SQL dump to wp-content/backup-YYYY-MM-DD-HHMMSS.sql
5. Outputs a message with the exact filename to download

None of this touches the live database — it’s a read-only export. The DROP TABLE IF EXISTS line is just text written into the .sql file; it only runs if you later import that file somewhere. This matches standard mysqldump behavior and exists so a restore is a clean, exact replacement rather than a merge. The catch: if you import this dump into a database where those tables already hold data you want to keep, that data is dropped first. Restore into an empty/target database, or a copy, not over live data you haven’t backed up separately.

This produces a standard MySQL dump that can be restored with mysql -u user -p db_name < backup.sql or imported via phpMyAdmin, Adminer, or any other MySQL client.

Verify the Backup Before You Delete Anything

Don’t trust the dump blind. Before deleting the script or the original data, do a quick sanity check via FTP or by eyeballing the file:

• File size isn’t zero or suspiciously tiny for the site’s size
• Table count matches — the number of -- Table: comment lines should equal the number of tables you’d expect (check against SHOW TABLES output if unsure)
• It ends cleanly — open the last few KB and confirm the final INSERT statement looks complete, not cut off mid-row (a sign the script hit a timeout or memory limit)

If any of these look wrong, don’t delete the live data or overwrite an older backup — re-run with the per-table or gzip variant below instead.

Security Notes — READ THIS

This script is a live SQL credential exposure while it exists on the server.

• Anyone who guesses or finds the URL example.com/backup-db.php can trigger a backup — and in the process, they confirm that wp-config.php credentials work, which is valuable reconnaissance
• The script itself contains no credentials (it pulls them from wp-config.php), but it proves those credentials are valid to anyone who can reach it
• The backup file lands in a web-accessible directory (wp-content/). If the filename is predictable, an attacker can download the entire database without authentication

Mitigation:

• Use a non-obvious filename — not backup-db.php, not dump.php, not backup.php. Something like x73k2p90.php that won’t be guessed
• Write the dump outside the web root if you can. Many shared hosts put public_html (or htdocs/www) as a subfolder of your FTP home directory, with sibling folders that aren’t served over HTTP. If your FTP account can navigate one level up, point $filename at something like ../backup-db.sql instead of wp-content/backup-db.sql — the dump is then unreachable by URL no matter what it’s named
• Delete the script immediately after the backup completes and you’ve downloaded the file
• Download the backup immediately and then delete it from the server as well — don’t leave SQL dumps in web-accessible directories
• Consider adding a simple authentication gate (see Variations below)

See also the Hardening WordPress guide for the broader set of practices this fits into.

Variations

Faster for Large Databases: mysqldump via PHP exec()

If the host has mysqldump available on the system path and PHP’s exec() or shell_exec() is not disabled, a one-liner is faster and more reliable for large databases:

<?php
require('wp-load.php');
$filename = 'wp-content/backup-' . date('Y-m-d-His') . '.sql';
exec("mysqldump --user=" . escapeshellarg(DB_USER) . " --password=" . escapeshellarg(DB_PASSWORD) . " --host=" . escapeshellarg(DB_HOST) . " " . escapeshellarg(DB_NAME) . " > " . escapeshellarg($filename));
echo "Backup complete. Download: <code>/wp-content/{$filename}</code>";

Note: Many shared hosts disable exec() and the shell functions for security reasons. Test it first — if you get an empty file or a 500 error, fall back to the wpdb method.

Basic Authentication Gate

Add a simple check to prevent unauthorized triggering:

<?php
// ADD THIS AT THE TOP
$valid_token = 'your-secret-token-here-12345';
if (empty($_GET['token']) || $_GET['token'] !== $valid_token) {
    header('HTTP/1.0 404 Not Found');
    exit;
}

require('wp-load.php');
// ... rest of the script unchanged

Then access via: https://example.com/backup-db.php?token=your-secret-token-here-12345

Warning: This is not cryptographic security — the token is visible in the URL and in server logs. But it stops casual guessing and bots.

Gzip Compression for Large Databases

For large sites where the SQL dump might exceed PHP memory limits or FTP upload limits, add gzip compression with PHP’s gzopen()/gzwrite():

<?php
require('wp-load.php');
$db = new wpdb(DB_USER, DB_PASSWORD, DB_NAME, DB_HOST);
$tables = $db->get_results('SHOW TABLES', ARRAY_N);

$filename = 'wp-content/backup-' . date('Y-m-d-His') . '.sql.gz';
$fp = gzopen($filename, 'w9');

foreach ($tables as $table) {
    $table_name = $table[0];
    gzwrite($fp, "--\n-- Table: $table_name\n--\n");
    gzwrite($fp, "DROP TABLE IF EXISTS `$table_name`;\n");
    $create = $db->get_row("SHOW CREATE TABLE `$table_name`");
    gzwrite($fp, $create->{'Create Table'} . ";\n\n");
    
    $rows = $db->get_results("SELECT * FROM `$table_name`");
    foreach ($rows as $row) {
        gzwrite($fp, "INSERT INTO `$table_name` VALUES(");
        gzwrite($fp, implode(',', array_map(function($val) use ($db) {
            return is_null($val) ? 'NULL' : $db->prepare('%s', $val);
        }, (array)$row)));
        gzwrite($fp, ");\n");
    }
}

gzclose($fp);
echo "Backup complete. Download: <code>/wp-content/{$filename}</code>";

This reduces the file size by ~70-80%, which can mean the difference between a downloadable backup and one that times out or exceeds FTP limits.

Per-Table Backup for Memory-Constrained Hosts

If you hit memory limits on very large tables, process tables one at a time and flush:

<?php
require('wp-load.php');
$db = new wpdb(DB_USER, DB_PASSWORD, DB_NAME, DB_HOST);
$tables = $db->get_results('SHOW TABLES', ARRAY_N);

foreach ($tables as $table) {
    $table_name = $table[0];
    $filename = 'wp-content/backup-' . $table_name . '-' . date('Y-m-d-His') . '.sql';
    
    $output = "--\n-- Table: $table_name\n--\n";
    $output .= "DROP TABLE IF EXISTS `$table_name`;\n";
    $create = $db->get_row("SHOW CREATE TABLE `$table_name`");
    $output .= $create->{'Create Table'} . ";\n\n";
    
    $rows = $db->get_results("SELECT * FROM `$table_name`");
    foreach ($rows as $row) {
        $output .= "INSERT INTO `$table_name` VALUES(";
        $output .= implode(',', array_map(function($val) use ($db) {
            return is_null($val) ? 'NULL' : $db->prepare('%s', $val);
        }, (array)$row));
        $output .= ");\n";
    }
    
    file_put_contents($filename, $output);
    echo "Saved: <code>/wp-content/{$filename}</code><br>";
}
echo "Done. Download all files from /wp-content/";

This creates one file per table, avoiding the memory spike of holding the entire database in a single string.

Raising Limits: Fighting Timeouts and Memory Caps

Before reaching for the per-table variant, it’s often enough to ask PHP for more room at the top of the script — if the host’s PHP configuration allows overrides:

<?php
require('wp-load.php');
ini_set('memory_limit', '512M');
set_time_limit(300); // 5 minutes; some hosts ignore this if safe mode-style restrictions are in place

See ini_set() and set_time_limit(). Some shared hosts hard-cap these via php.ini or .user.ini regardless of what the script requests — if the dump still cuts off, that’s your signal to switch to the per-table or gzip approach instead.

Alternatives That Don’t Work in This Scenario

It’s worth noting what you can’t do with only FTP:

The PHP script method is one of the few that works within the FTP-only constraint.

Real-World Use Cases

Emergency backup before a migration: You’re moving a client site to new hosting, the old host only provides FTP, and you need a fresh database snapshot before pointing DNS. This gets you the dump in under 5 minutes.

Debugging a live site: Something is wrong with the database and you need to inspect it locally. You can’t get SSH access quickly, but FTP works. Upload the script, grab the dump, restore to a local MySQL instance, and debug without touching the live site.

Recovery after a hack: A site has been compromised and you suspect the database was tampered with. The host won’t grant SSH access. This method lets you pull a clean dump (assuming the attack didn’t also compromise wp-config.php credentials) for forensic analysis.

Client with restrictive hosting: A client is on a budget host that only provides FTP. They need a database backup before a plugin update. This is the only method that doesn’t require upgrading their hosting plan.

Limitations

• Speed: The wpdb method is slow for large databases (100MB+). Each row is fetched and serialized individually in PHP. The mysqldump variant is much faster, but it’s often blocked.
• Memory: Large tables can exhaust PHP memory limits. The per-table variant helps, or use gzip to reduce in-memory size.
• Reliability: If the script times out mid-execution, the backup may be incomplete. For hosts with short PHP max_execution_time, the per-table approach is more resilient.
• Character encoding: The script uses wpdb->prepare() which handles escaping, but ensure your database and PHP are using the same character set (usually utf8mb4).

The Takeaway

When all you have is FTP, the DIY PHP script is your lifeline. It’s not elegant, it’s not fast for huge databases, and it demands strict cleanup discipline — but it works, and it’s saved more than one project from a hosting dead-end.

The complete pattern:

1. Create backup-db.php with the wpdb script
2. Upload to site root via FTP
3. Visit https://example.com/backup-db.php
4. Download the .sql from /wp-content/
5. DELETE backup-db.php immediately

This is exactly the kind of constraint-driven problem solving we do day-to-day in WordPress operations work at Imagewize. If you’re managing WordPress sites on restrictive hosting and want help building tooling that works within those limits, get in touch.

Hit a hosting scenario this doesn’t cover? Or found a better FTP-only backup method? Find me on Mastodon at @jfrumau@mastodon.social.

PASS=$(openssl rand -base64 16) && wp user update admin --user_pass="$PASS" && echo "New password: $PASS"

It generates a strong random password, sets it for the admin user, and prints it to your terminal — without ever persisting it in your shell history, a script log, or a process list where a shoulder-surfer might spot it.

The Problem It Solves

The first time most people need to reset a WordPress password from the command line, they do this:

wp user update admin --user_pass='correct-horse-battery-staple'

That works. It also writes the password to ~/.bash_history, ~/.zsh_history, or whatever your shell’s history file is named. From there it can end up:

• In a backup that gets restored months later
• In a shared CI log if you forget you’re in a script
• Visible to anyone with momentary access to your terminal session
• Grepped accidentally by a teammate looking for “admin” in a log file

The second time most people need to do it, they remember the first time and reach for --prompt:

wp user update admin --prompt=user_pass

That’s better — the password is typed interactively and never hits the history. But it still has friction: it won’t run in a script, it’s awkward over SSH to a remote host, and you need to manually type a strong password or copy-paste one from a generator, which puts it back on the clipboard where it can leak.

How the One-Liner Works

PASS=$(openssl rand -base64 16) && wp user update admin --user_pass="$PASS" && echo "New password: $PASS"

Breaking it down:

1. openssl rand -base64 16 generates 16 random bytes and base64-encodes them, producing a 24-character password like FYSB+DvNIUNZCw2wYekdGA==. Note this is standard base64, not the URL-safe variant — it can contain +, /, and trailing = padding, which is why the --user_pass="$PASS" quoting in step 3 matters.

2. PASS=$(...) captures that output into a shell variable. Variables don’t survive the shell session — once you close the terminal or the script exits, the password is gone.

3. wp user update admin --user_pass="$PASS" updates the user. The quotes around $PASS keep the shell from word-splitting or globbing parts of the password.

4. echo "New password: $PASS" prints it once so you can see it and copy it to your password manager. This is the only time it’s visible.

The && chains ensure that if any step fails (OpenSSL missing, wp not found, user doesn’t exist), the whole thing stops and the password never gets set to a half-finished value.

Security Notes

This is secure against history, but not against shoulder surfing or screen capture. The password is still displayed on screen for anyone looking at your terminal. For environments where that’s a risk, consider:

• Running the command over SSH and only showing the output locally
• Using wp user reset-password admin --skip-email --porcelain instead, which also avoids history but only prints the password

It is also not secure against process listing. For a brief moment the variable’s value exists in the process environment. On a shared system where other users can run ps eww, this is a vulnerability. For most local or single-user deploy contexts it’s fine.

If you need the highest level of paranoia, use WP-CLI’s own password generator:

wp user reset-password admin --porcelain --skip-email

This generates a 12-character password internally (WordPress’s wp_generate_password() default) and prints only the result. It never touches your shell, so it can’t leak through history, environment, or process listing. The trade-off is you can’t control the length or the character set.

Variations

Different user: Replace admin with the username or user ID:

PASS=$(openssl rand -base64 16) && wp user update 42 --user_pass="$PASS" && echo "New password: $PASS"

Longer password: Base64 encodes 6 bits per character, so 16 bytes becomes 24 characters. For a longer password, increase the byte count:

PASS=$(openssl rand -base64 24)  # ~32 characters
PASS=$(openssl rand -base64 32)  # ~44 characters

Alphanumeric only: Some systems reject special characters. Use tr to strip them:

PASS=$(openssl rand -base64 24 | tr -dc 'a-zA-Z0-9') && wp user update admin --user_pass="$PASS" && echo "New password: $PASS"

Copy to clipboard automatically (macOS):

PASS=$(openssl rand -base64 16) && wp user update admin --user_pass="$PASS" && echo "$PASS" | pbcopy && echo "New password copied to clipboard"

Remote host via SSH:

ssh user@example.com "PASS=\$(openssl rand -base64 16) && wp user update admin --user_pass=\"\\$PASS\" && echo \"New password: \$PASS\""

That escaping is messy. A cleaner approach is to run the password generation locally and pass only the value:

PASS=$(openssl rand -base64 16) && ssh user@example.com "wp user update admin --user_pass='$PASS'" && echo "New password: $PASS"

Creating a new user with a generated password:

PASS=$(openssl rand -base64 16) && wp user create deploybot bot@example.com --role=administrator --user_pass="$PASS" && echo "New password: $PASS"

Why Not Just Use --show-password with reset-password?

WP-CLI’s reset-password command has a --show-password flag:

wp user reset-password admin --show-password

This also avoids shell history. The difference is mainly ergonomic: reset-password emails the user by default, so you need --skip-email if that’s not desired. And it uses WP-CLI’s own password generator, which may or may not match your preferred length or character set.

The OpenSSL version gives you more control, and it’s a pattern you can reuse in other contexts (database passwords, API keys, etc.).

What This Doesn’t Do

• It doesn’t expire old sessions. After changing a password, existing login sessions for that user remain valid until they expire or the user logs out. For incident response, add wp user session destroy admin --all.

• It doesn’t verify the password. Use wp user check-password admin 'the-password' to verify without changing it.

• It doesn’t rotate application passwords. For API access, use wp user application-password create admin 'deploy-pipeline'.

Real-World Use Cases

Emergency lockout recovery: You’re handed a site where the admin password is lost, SSH is available, and you need to get back in fast. This is the two-second fix.

Provisioning scripts: A deploy or setup script needs to create users with strong passwords. The variable approach keeps them out of script files and logs.

Client handovers: You’re transferring a site to a new owner and need to set a temporary admin password. Generating it inline means it’s never written down anywhere permanent.

Security incident response: A password may have been compromised. Rotating it with a one-liner gets it done immediately, and the echo lets you communicate the new password to the affected user through a separate secure channel.

The Takeaway

PASS=$(openssl rand -base64 16) && wp user update admin --user_pass="$PASS" && echo "New password: $PASS"

It’s a small pattern with outsized utility: strong passwords, no history pollution, one copy-paste, and it works identically whether you’re local or on a remote server over SSH. Keep it in your back pocket for the next time you need to set a WordPress password from the command line.

This is the kind of small but critical detail we handle day-to-day in WordPress operations work at Imagewize. If you’re building or maintaining WordPress sites and want help with the tooling and workflow around them, get in touch.

Found a better one-liner? Or hit a case this doesn’t cover? Find me on Mastodon at @jfrumau@mastodon.social.

The scanners, briefly

wp-cli/security/scanner-targeted.php and scanner-general.php are pattern-matching malware scanners for a WordPress install — targeted looks for site-specific threats, general does broader-spectrum detection, both checking PHP/JS/HTML files for known-bad signatures. Since 5.22.0 they also run wp core verify-checksums first and skip pattern-scanning any core or plugin file that hashes clean against WordPress.org’s official checksums — the single biggest source of false positives (an unmodified wp-includes/SimplePie/... file matching a mysql.php-shaped pattern by pure coincidence of its name, for instance) goes away automatically.

Running them locally, or via wp eval-file on a box the scanner already lives on, was always fine. Remote was the awkward case.

The old remote workflow, and why it broke

Before 5.22.0, scanning a remote site meant copying scanner-targeted.php up by hand and running it over SSH. Once the checksum module shipped, that stopped working outright — both scanners now do:

require_once dirname(__FILE__) . '/checksum-verify.php';

A lone copied file has no sibling checksum-verify.php next to it, so it fatals on Failed opening required '.../checksum-verify.php'. The capability to run this properly against a remote or VM target only existed inside the project’s MCP server tool — not from the CLI.

wp-ops malware-scan

wp-ops malware-scan example.com production
wp-ops malware-scan example.com production --mode both

--mode picks targeted, general, or both (default targeted). What it does under the hood: it inlines checksum-verify.php’s source in place of that require_once line, then streams the assembled, self-contained script to php /dev/stdin on the target over SSH. Nothing is ever written to the server — there’s no file to scp, no file to forget, no file to delete.

A real run, both scanners, against a production Bedrock site:

========================================
Malware Scan: example.com (production)
========================================

  Target: web@example.com:/srv/www/example.com/current/web/wp
  Mode:   both

--- TARGETED SCANNER ---

WordPress Core: VERIFIED
Plugins Verified: 6
Files Verified: 3338
Files Failed: 0

Found 1,955 files to scan
Skipping 1955 verified core/plugin files (checksum passed)
After checksum filtering: 0 files to pattern-scan

SCAN SUMMARY:
  Files with matches: 0
  Total matches: 0
  Checksum-verified files skipped: 1,955

✓ No threats detected!

--- GENERAL SCANNER ---

WordPress Core: VERIFIED
Plugins Verified: 6

SCAN SUMMARY:
  Suspicious filenames: 0
  Files with matches: 0
  Checksum-verified filename hits suppressed: 4

✓ No threats detected!

Both scanners agree, checksum verification did the heavy lifting (1,955 files skipped from pattern-matching because they’re provably unmodified core/plugin code), and the whole thing ran in about 11 seconds total.

Host and WordPress path default from a small site registry when one exists, so a site whose SSH host isn’t its own domain — several client sites sharing one box, which is exactly our own setup — needs no flags at all. Without a registry it falls back to the stock Trellis layout: web@<site-name>, /srv/www/<site>/current/web/wp.

The bug the first release shipped with

Both scanners end with a block like this:

============================================
  SECURITY WARNING
============================================

⚠ DELETE THIS FILE after use or move it outside the web root!
  This scanner should not remain accessible on a production server.

That warning is correct advice — for the FTP-upload, cPanel/Plesk-terminal, or scp’d-wp eval-file workflows, where the scanner genuinely does land as a file in or near the web root. But it kept printing on malware-scan runs too, where nothing was ever written to disk. Stale advice in a security tool’s own output is exactly the kind of thing that erodes trust in the rest of what it tells you, so it needed fixing before the next scan.

My first attempt checked __FILE__ against a short list of expected stdin paths — /dev/fd/0, /dev/stdin, php://stdin. It passed clean on my Mac. It did not pass against the actual production target, which is Linux: php /dev/stdin there resolves __FILE__ to /proc/<pid>/fd/pipe:[18694749] — a real pipe, just not one of the strings I’d guessed. String-matching platform-specific pipe representations was never going to be a complete list.

The fix that actually holds across platforms:

function scanner_file_is_on_disk() {
    return is_file(__FILE__);
}

is_file() asks the filesystem directly rather than pattern-matching a path. It returns false for a pipe on every platform I could test — macOS’s /dev/fd/0 and Linux’s /proc/.../fd/pipe:[...] both fail it — and true for a script actually sitting on disk. Wrap the warning block in that check, and it fires exactly when there’s a real file for someone to go delete, on any host, regardless of how that platform happens to name its stdin pipe internally.

The lesson that actually generalizes here: a fix verified only against your own machine, for anything touching cross-platform filesystem or process behavior, isn’t verified. Re-running the real command against the real remote target — not a local approximation of it — is what caught the gap.

Manually checking a file the scanner skipped

Pattern-matching has a 5MB file-size cap for performance, so scan output sometimes includes a note like:

============================================
  SKIPPED FILES
============================================

  /srv/www/example.com/current/web/wp/wp-includes/js/dist/script-modules/vips/worker.min.js
    Reason: File too large (12.8 MB)

Worth knowing: that cap only applies to the pattern-matching pass. Checksum verification has no size limit — wp core verify-checksums hashes every core file regardless of size — so a skipped file is still very likely covered by the earlier “WordPress Core: VERIFIED” result, just not pattern-scanned on top of that. If you want to confirm one specific file yourself rather than take that on faith, WordPress.org’s checksums API makes it a two-line check:

ssh web@example.com '
WP_VER=$(cd /srv/www/example.com/current && wp core version --path=web/wp)
FILE="wp-includes/js/dist/script-modules/vips/worker.min.js"
curl -s "https://api.wordpress.org/core/checksums/1.0/?version=${WP_VER}&locale=en_US" \
  | python3 -c "import json,sys; print(json.load(sys.stdin)[\"checksums\"].get(\"$FILE\", \"NOT FOUND\"))"
md5sum /srv/www/example.com/current/web/wp/$FILE
'

The API returns every core file’s official md5 for that exact WordPress version, keyed by its relative path from the wp root. Fetch the one hash you care about, md5sum the live file, and compare by eye:

Official md5: 2710fbcfdcdf95a4ed07e251bc09c66c
Local md5:    2710fbcfdcdf95a4ed07e251bc09c66c

A match means the file is stock, unmodified core straight from wordpress.org for that version — no scanner, no size cap, no waiting required.

Where this leaves things

malware-scan is on the tap now:

brew upgrade --cask wp-ops
wp-ops malware-scan example.com production --mode both

Both scanners are the same ones you’d run locally or via wp eval-file — the remote path just gets you there without a file to clean up afterward, and without a leftover warning telling you to clean up something that was never there.

This is part of the tooling we run at Imagewize for client WordPress operations on Trellis. If your team is still doing the scp-and-remember-to-delete dance for remote security checks, get in touch.

Questions about your own Trellis workflow? Find me on Mastodon at @jfrumau@mastodon.social.

Known limitation: the CLI does not yet support MCP servers that require OAuth authentication. Use the stdio or http transport with an API key or other static credential.

That statement is out of date. OAuth is fully implemented and working in Vibe today. The confusion stems from stale docs and a config gap that’s easy to miss. Here’s how to get the Upwork MCP server connected with OAuth in Vibe, what the docs get wrong, and why the fix is simpler than you think.

The documentation gap: what the docs say vs. what the code does

The Mistral docs claim OAuth for MCP servers isn’t supported. The actual code tells a different story. In the current Vibe repository (commit 6c79ef0, Sep 4, 2026), OAuth support is complete and production-ready:

• vibe/core/auth/mcp_oauth.py — full PKCE authorization-code flow, loopback callback server, OS-keyring token storage, refresh-aware handling, dynamic client registration (DCR) support
• vibe/cli/textual_ui/widgets/mcp_oauth_app.py — the textual UI widget for the login flow

So why the disconnect? The docs are stale, and there’s a subtle configuration detail that tripped up early attempts — including mine.

The actual blocker: missing auth block in .vibe/config.toml

If your Upwork MCP server shows as “enabled, no tools” in Vibe, it’s not because OAuth is unsupported. It’s because your [[mcp_servers]] entry is missing the [mcp_servers.auth] block entirely. When that block is absent, Vibe defaults to MCPStaticAuth (empty, no token). The code that would auto-promote a server to OAuth on a 401 response — _late_bound_oauth in vibe/app_server/_mcp_auth.py — explicitly excludes config-owned [[mcp_servers]] entries. The comment in the source is clear: “a static entry there is a decision.”

In practice, this means:

• Without [mcp_servers.auth]: Vibe treats the server as static-credential only. Attempting to authenticate via /mcp browser will fail with MCP server 'upwork' is not configured for OAuth.
• With [mcp_servers.auth] of type = "oauth": Vibe starts the OAuth flow when you select the server in the /mcp browser and the server connects fully.

The fix: three lines in .vibe/config.toml

Here’s the working configuration I’m using in my SEO strategy project:

[[mcp_servers]]
name = "upwork"
transport = "http"
url = "https://mcp.upwork.com/mcp"

[mcp_servers.auth]
type = "oauth"
scopes = []

That’s it. No client_id, no client_metadata_url. This relies on the Upwork MCP server supporting Dynamic Client Registration (RFC 7591) — and it does.

How Dynamic Client Registration (DCR) works here

DCR is the key to why this config is so minimal. Instead of requiring you to pre-register an OAuth client with Upwork and paste static credentials into your config, the Upwork MCP server:

1. Accepts a DCR request from Vibe at OAuth flow start
2. Returns a temporary client_id and client_secret for that session
3. Uses those ephemeral credentials for the duration of the auth flow
4. Stores the resulting tokens in your OS keyring (via the keyring Python library)

The result: zero pre-registration, zero static secrets in your config. From the Vibe CLI, run /mcp to open the MCP server browser, select the upwork server, choose Authenticate in browser, complete the consent flow, and the server flips from [http] no tools ● enabled to [http] 48 tools ● connected with the full Upwork tool list:

• upwork__find_jobs
• upwork__get_account
• upwork__boost_profile
• And the rest of the Upwork MCP catalog

Transport note: http vs. streamable-http

The docs mention transport types. In practice, both transport = "http" and transport = "streamable-http" route to the same code path in Vibe. From registry.py:_discover_server:

case "http" | "streamable-http":

Both hit _discover_http → streamable_http_client. The distinction is a config-schema discriminator, not a functional difference. Use http unless you have a specific reason not to.

Verification: it works

I applied the three-line auth block, then used the Vibe MCP browser to authenticate. From the Vibe CLI, run /mcp to open the MCP server browser, select the upwork server from the list, and choose Authenticate in browser. This launches your default browser to Upwork’s OAuth consent screen. Complete the consent flow there, and Vibe automatically receives the OAuth tokens and connects the server. No manual client registration, no static keys, no workarounds. DCR against Upwork’s MCP endpoint works with zero pre-registration.

Direct terminal usage with –enabled-tools

Once OAuth is configured and connected, you can also use Upwork MCP tools directly from the terminal without entering the full Vibe CLI. Pass a single-shot prompt with -p, restrict to the specific tool via --enabled-tools, and set --output text for clean output:

vibe -p "Call list_accounts and return ONLY the org_uid values, one per line, with no other text." \
    --enabled-tools "upwork_upwork__list_accounts" \
    --output text \
    --workdir "$PWD" \
    --trust

This pattern works for any Upwork MCP tool. Replace upwork_upwork__list_accounts with the tool you need (e.g., upwork_upwork__get_account, upwork_upwork__find_jobs, etc.) and adjust the prompt to match. The --trust flag allows the command to run non-interactively, and --output text strips the markdown formatting for easier parsing or scripting.

As documented in Mistral’s MCP server docs under “Browse”, the /mcp command opens an interactive MCP server browser that lists all configured servers and provides authentication options for each.

Separately, the Upwork MCP server also works headlessly via Claude Code 2.1.251+ (verified Aug 31, 2026), which handles its own OAuth internally. That path is independent of Vibe’s DCR implementation and remains a proven alternative if you hit edge cases.

What the docs should say

The current documentation limitation note should be updated to reflect reality:

OAuth is fully supported for MCP servers. For servers requiring OAuth, add a [mcp_servers.auth] block with type = "oauth" to your [[mcp_servers]] entry. Many MCP servers support Dynamic Client Registration (DCR), which requires no pre-registered client credentials. Use /mcp to open the MCP server browser, select your server, and choose Authenticate in browser to start the OAuth flow.

And for servers that don’t support DCR, you’d add the static client credentials:

[mcp_servers.auth]
type = "oauth"
client_id = "your-pre-registered-client-id"
client_secret = "your-client-secret"  # if required by the server
scopes = ["scope1", "scope2"]

But for Upwork, the minimal DCR config above is all you need.

The seven-step check if your Upwork MCP server isn’t connecting

If you’re still seeing “no tools” after adding the auth block:

1. Verify the config — ensure name, transport, url, and [mcp_servers.auth] with type = "oauth" are all present
2. Restart Vibe — config changes require a full restart to take effect
3. Check /mcp list — confirm the server appears with [http] prefix
4. Run /mcp to open the MCP browser — select the upwork server and choose Authenticate in browser
5. Complete the consent flow — approve all requested permissions in your browser
6. Check /mcp list again — the server should now show tool count > 0 (e.g., [http] 48 tools ● connected)
7. Test a tool call — try upwork__get_account to verify connectivity

If step 4 fails with “not configured for OAuth”, double-check that the [mcp_servers.auth] block is directly under the [[mcp_servers]] entry for Upwork, not at the root level or under a different server. As noted in the official docs, the /mcp command provides the interactive browser interface for managing MCP server connections.

Why this matters for agency workflows

For my SEO strategy work, Upwork MCP access means:

• Freelancer discovery — programmatic access to find specialists for specific tasks (technical SEO audits, content writing, link building)
• Job automation — posting, updating, and managing job listings without leaving the CLI
• Profile integration — boosting visibility and managing proposals at scale
• Data-driven hiring — pulling freelancer metrics and past work to inform hiring decisions

Before this working OAuth setup, the only path was manual API key management or using the Upwork web interface. Now it’s a native part of the Vibe workflow: ask for a task, Vibe can query Upwork for the right freelancer, post the job, and manage the process end-to-end.

Bottom line

The Mistral docs are wrong on this one. OAuth for MCP servers isn’t a limitation — it’s fully implemented and working. The Upwork MCP server connects with three lines of config and Dynamic Client Registration. The confusion came from stale documentation and a config detail that’s easy to overlook.

If you’ve been holding off on MCP server integrations because of the “OAuth not supported” note, give it another try. The code has moved on.

Questions about your own Vibe or MCP setup? Find me on Mastodon at @jfrumau@mastodon.social. The .vibe/config.toml used as the basis for this post is available here.

There is a pending change of the admin email to hallo@example.com. Cancel

The change had been made 16 days earlier. My own notes recorded it as done. It wasn’t done — it had been sitting in limbo the entire time, and the site had been mailing its update notices and fatal-error alerts to the old address the whole while, silently.

The cause isn’t a bug. It’s that the input box labelled Administration Email Address does not write to the admin_email option, and never has. This post is the mental model I keep re-deriving, plus the WP-CLI commands for admin email and passwords that I keep half-remembering and looking up again.

The one line of core that explains it

Here’s the field, from wp-admin/options-general.php:

<th scope="row"><label for="new_admin_email">Administration Email Address</label></th>
<td><input name="new_admin_email" type="email" id="new_admin_email"
     value="<?php form_option( 'admin_email' ); ?>" class="regular-text ltr" />

Look at the mismatch. The input is named new_admin_email. Its value is printed from admin_email. So the box shows you the live address, and saves to a completely different option.

Nothing about the UI signals that those are two different places. You type a new address into a field pre-filled with the current one, hit Save, and the page reloads showing… the old address, plus a notice. Most people read that notice once, assume it’ll sort itself out, and move on. It doesn’t sort itself out.

What actually happens on save

Saving new_admin_email fires an action hooked in wp-admin/includes/admin-filters.php:

add_action( 'add_option_new_admin_email',    'update_option_new_admin_email', 10, 2 );
add_action( 'update_option_new_admin_email', 'update_option_new_admin_email', 10, 2 );

And that handler (wp-admin/includes/misc.php) does this:

function update_option_new_admin_email( $old_value, $value ) {
    if ( get_option( 'admin_email' ) === $value || ! is_email( $value ) ) {
        return;
    }
    $hash            = md5( $value . time() . wp_rand() );
    $new_admin_email = array(
        'hash'     => $hash,
        'newemail' => $value,
    );
    update_option( 'adminhash', $new_admin_email, false );
    // ... then emails a confirmation link to the NEW address

So a “change” leaves you with three options in the database, not one:

The swap into admin_email only happens when somebody opens the confirmation email sent to the new address and clicks the link. If that inbox doesn’t exist yet, or belongs to a client who files it under “probably spam,” or the site can’t send mail reliably in the first place — the change never lands, and the only trace is a notice on a settings page nobody visits.

That last one is worth dwelling on. The confirmation goes to the new address, so a site with broken outbound mail can never complete an admin email change through the UI. And a broken-mail site is exactly the site whose admin address you’re most likely trying to fix.

Inspecting the real state

Never trust the settings screen. Ask the database:

wp option get admin_email
wp option get new_admin_email   # errors if not set — that's the healthy case
wp option get adminhash

On the site above, that gave me:

admin_email:     jasper@example.com
new_admin_email: hallo@example.com
adminhash:       array ( 'hash' => 'a2bd4e6c…', 'newemail' => 'hallo@example.com' )

Sixteen days of “done.” A one-liner for a fleet:

for site in site-a site-b site-c; do
  printf '%-12s live=%-28s pending=%s\n' "$site" \
    "$(wp --url="$site" option get admin_email)" \
    "$(wp --url="$site" option get new_admin_email 2>/dev/null || echo '-')"
done

Cancelling a pending change

The Cancel link in the admin does exactly two deletes. From wp-admin/options.php:

} elseif ( ! empty( $_GET['dismiss'] ) && 'new_admin_email' === $_GET['dismiss'] ) {
    check_admin_referer( 'dismiss-' . get_current_blog_id() . '-new_admin_email' );
    delete_option( 'adminhash' );
    delete_option( 'new_admin_email' );

So the CLI equivalent is:

wp option delete new_admin_email
wp option delete adminhash

Delete both. Dropping only new_admin_email leaves adminhash behind, and the confirmation link in that already-sent email stays live — so months later someone can dig it out of an archive folder, click it, and flip your production admin address. Deleting adminhash is what actually revokes the token.

If you’re already looking at the notice, just click Cancel

Worth saying plainly, because it’s what I didn’t do: that link is one click, and it does both deletes for you, behind a nonce check. I was staring straight at it and reached for WP-CLI out of habit — two commands to accomplish what the UI had sitting right there under my cursor.

The CLI version earns its keep in the cases where the link isn’t an option:

• You can’t log in. A locked-out admin, or a fresh site handover where nobody has credentials yet.
• The site can’t send mail. As above, the confirmation goes to the new address, so a broken-mail site can never complete the change through the UI at all. CLI is the only way through.
• You’re auditing rather than fixing. The notice tells you an address is pending; wp option get tells you all three values, which is what you actually need to reason about the state.
• More than one site. Nobody clicks through twelve dashboards.
• It’s in a script. Provisioning, a migration, a handover checklist.

Away from those, the button is the better tool. Knowing the option names is still what lets you verify the button did what you think — which is the real reason to know them.

Setting it for real

If you want the change to take effect now, skip the request/confirm dance and write the live option directly:

wp option update admin_email hallo@example.com

No confirmation, no token, no waiting. I verified this on a sandbox — the value changes immediately and no adminhash is created:

$ wp option update admin_email direct-test@example.com
Success: Updated 'admin_email' option.
$ wp option get adminhash
Error: Could not get 'adminhash' option. Does it exist?
$ wp option get admin_email
direct-test@example.com

One side effect to know about: update_option_admin_email is hooked to wp_site_admin_email_change_notification, which sends a courtesy heads-up to the old address. That’s usually what you want. Suppress it with the send_site_admin_email_change_email filter if you’re scripting a bulk change.

Forcing it does not cancel a pending change

This is the part that will bite you, and it’s the reason the two commands above belong together rather than being alternatives.

Writing admin_email directly changes the live address. It does not touch new_admin_email or adminhash. If a pending change was already sitting there, it survives untouched:

$ wp option update new_admin_email pending@example.com   # pending change exists
$ wp option update admin_email forced@example.com        # force the live value

$ wp option get admin_email
forced@example.com          <- changed
$ wp option get new_admin_email
pending@example.com         <- survived
$ wp option get adminhash
array ( 'hash' => 'd8f404f5…', 'newemail' => 'pending@example.com' )   <- survived

Now look at what redeems that token, in wp-admin/options.php:

if ( ! empty( $_GET['adminhash'] ) ) {
    $new_admin_details = get_option( 'adminhash' );
    if ( is_array( $new_admin_details )
        && hash_equals( $new_admin_details['hash'], $_GET['adminhash'] )
        && ! empty( $new_admin_details['newemail'] )
    ) {
        update_option( 'admin_email', $new_admin_details['newemail'] );

There is no expiry check. No timestamp, no comparison against the current admin_email, no nonce. The only conditions are that adminhash exists and the hash matches. So the confirmation link stays redeemable indefinitely — and when a logged-in administrator eventually digs that mail out of an archive folder and clicks it out of curiosity, WordPress overwrites your forced address with the old pending one and reports success.

There’s a nastier variant. The admin notice only renders when the two differ:

if ( $new_admin_email && get_option( 'admin_email' ) !== $new_admin_email ) {

So if you force admin_email to the same address that’s pending, the warning disappears from Settings → General while the stale adminhash is still sitting in the database, still armed. The UI now looks completely clean and tells you nothing.

The fix is to treat “set the admin email” as three commands, not one:

wp option update admin_email hallo@example.com
wp option delete new_admin_email
wp option delete adminhash

Set the live value, then revoke the token. Deleting adminhash is the part that actually disarms it.

And per the section above — if a pending change is already showing in the dashboard, click Cancel first. That clears both options in one click, and what’s left for the CLI is a single command:

wp option update admin_email hallo@example.com

Order matters slightly, and not in the direction you’d guess. Cancel then set is clean. Set then cancel also works, but if you force admin_email to the same address that’s pending, the notice vanishes on reload — so the Cancel link you were about to click disappears from the screen while the armed token is still in the database. Clear the pending change while you can still see it.

The assumption I had wrong

I went into this believing the confirmation flow was an admin-UI thing — that WP-CLI wrote options “raw” and bypassed it. That’s wrong, and I only found out by testing it:

$ wp option update new_admin_email trap-test@example.com
Success: Updated 'new_admin_email' option.
$ wp option get adminhash
array (
  'hash' => '464d11e35cea8eee7894c23d5922b7fb',
  'newemail' => 'trap-test@example.com',
)

WP-CLI loads the admin includes, so those hooks fire perfectly well from the command line. The dividing line is the option name, not the interface. wp option update new_admin_email queues a pending change and mails a confirmation link, exactly like the settings form. Only admin_email is immediate.

Which means it’s entirely possible to create this same stuck state from a deploy script, and never see the notice that would have told you.

Multisite

Network settings are a separate option in a separate table:

wp site option get admin_email          # network admin email
wp option get admin_email --url=sub.example.com   # per-site

Network-level changes route through update_network_option_new_admin_email (wp-admin/includes/ms-admin-filters.php) with the same request/confirm shape. Changing a site’s admin email does not touch the network’s, and vice versa.

The sibling trap: user profile emails

The exact same pattern guards a user changing their own email, which is where the second round of confusion usually comes from. It’s stored in user meta rather than options:

wp user meta get 5 _new_email
# array( 'hash' => '…', 'newemail' => 'new@example.com' )

wp user meta delete 5 _new_email    # = the "Cancel" link on profile.php

But there’s a catch worth internalizing, from wp-admin/user-edit.php:

if ( IS_PROFILE_PAGE && isset( $_GET['newuseremail'] ) && $current_user->ID ) {

That IS_PROFILE_PAGE guard means the confirmation dance only applies to users editing themselves. An administrator editing somebody else’s account changes that email instantly, no confirmation. And from the CLI:

wp user update 5 --user_email=new@example.com   # immediate, always

So “changing a user’s email needs confirmation” is only true in one specific case. Everywhere else it’s instant.

Passwords, while we’re here

The other thing I look up every time.

Set a known password:

wp user update admin --user_pass='correct-horse-battery-staple'

That lands in your shell history in plain text. Use the --prompt global parameter to type it interactively instead:

wp user update admin --prompt=user_pass

Generate a strong one instead of inventing it:

wp user reset-password admin --show-password
# or, to capture it in a script:
NEW_PASS=$(wp user reset-password admin --porcelain --skip-email)

reset-password emails the user by default, which is usually right for a real person and wrong for a service account — hence --skip-email. --porcelain prints only the password, nothing else.

Create a user with a password up front:

wp user create deploybot bot@example.com \
  --role=administrator --user_pass="$(openssl rand -base64 24)"

Verify a password without changing it — genuinely useful when a client insists their login is broken and you want to know whether it’s the password or something else entirely:

wp user check-password admin 'the-password-they-swear-works'

Exit code 0 means valid, 1 means not. Nothing is modified.

Kick everyone out after a password change. Changing the password does not invalidate existing sessions, which surprises people during an incident response:

wp user session destroy admin --all

Application passwords for API and integration access, so you never hand out the real one:

wp user application-password create admin 'deploy-pipeline' --porcelain
wp user application-password list admin
wp user application-password delete admin <uuid>

The takeaway

Two WordPress settings look like plain text fields and are actually two-phase state machines: the site’s administration email, and a user’s own email address. Both leave a pending record that is invisible unless you go looking, and both can sit unresolved indefinitely while everything appears fine.

So when you change either one, verify the live value afterward rather than trusting the success notice:

wp option get admin_email && wp option get new_admin_email

If the second command errors, you’re clean. If it returns an address, you haven’t changed anything yet — you’ve only asked.

The fix wasn’t a better memory. It was collapsing everything into one catalog: wp-ops, a single CLI that wraps the Ansible playbooks, WP-CLI scripts, and shell utilities I’d built up over time into one binary with real --help, search, and shell completions. Here’s the actual loop I run against it — daily and weekly — and what each command is doing underneath.

Why one binary instead of a folder of scripts

Before wp-ops existed, this was a directory of ~74 things: Ansible playbooks under trellis/, standalone Bash under scripts/, WP-CLI PHP under wp-cli/. All useful, all discoverable only if you already knew the filename. The CLI auto-discovers all of it from manifest comments at the top of each script:

# @desc     Back up a site's database from any environment
# @category backup
# @platform trellis
# @requires ansible-playbook
# @example  wp-ops database-backup imagewize.com production

That manifest is the whole trick — wp-ops --help, wp-ops search, and shell completions are all generated from it, so there’s no second list to keep in sync. Run wp-ops doctor once after installing and it tells you which of the underlying tools (WP-CLI, Ansible, gh, ImageMagick…) are actually on your machine before a command fails halfway through.

brew install imagewize/tap/wp-ops
wp-ops init      # shell completions
wp-ops doctor    # check dependencies

With that in place, here’s the loop. The examples below use our own site keys — imagewize.com for the main site, demo.imagewize.com for our local pattern-showcase install — swap in whatever key matches your project’s entry in wordpress_sites.yml.

1. Database backup

wp-ops database-backup imagewize.com production

Runs trellis/backup/database-backup.yml against the target environment: wp db export on the remote, gzipped, pulled down as a timestamped imagewize_com_production_2026_08_29_10_00_00.sql.gz. I run this before anything that touches production data, not just on a schedule.

2. Database pull, with URL search-replace already done

wp-ops database-pull imagewize.com production

This is the one that looks simple and isn’t. database-pull.yml doesn’t just fetch a dump — it backs up your current local database first, into a database_backup/ folder inside the project, before it imports anything. That’s easy to miss because it’s buried in the middle of the playbook, but it’s the difference between “oops, wrong environment” being an inconvenience versus a lost afternoon.

After the import it runs the URL swap itself:

url_from: "{{ wordpress_sites[site].site_hosts.0.canonical }}"
url_to:   "{{ dev_wordpress_sites.wordpress_sites[site].site_hosts.0.canonical }}"

resolving both sides from group_vars — production’s canonical hostname and your local local_path config — so wp search-replace runs with the right values without you typing either URL. I wrote up the playbook’s internals (and two bugs I had to patch in the stock version) in an earlier post if you want the full mechanics.

3. Files pull via rsync

wp-ops files-pull imagewize.com production

Syncs shared/uploads/ from the remote into web/app/uploads/ locally. It’s additive by default — local-only files (test images, things since deleted from the remote media library) survive the sync. Add --delete yes only when you actually want local to mirror remote exactly; that flag is destructive on the local side, so I don’t reach for it without a reason.

4. Dropping a pattern onto a page to test it

This one isn’t a single wp-ops command yet — it’s a wp post update run against the Trellis VM, and it’s the step I reach for most when a new block pattern needs a real page to render on before it ships. I do this against demo.imagewize.com, our local showcase site, rather than risk it on a client project:

trellis vm shell --workdir /srv/www/demo.imagewize.com/current -- bash << 'VMEOF'
cat > /tmp/page-content.html << 'EOF'
<!-- wp:pattern {"slug":"nynaeve/pattern-slug"} /-->
EOF
CONTENT=$(cat /tmp/page-content.html)
wp post update PAGE_ID --post_content="$CONTENT" --url=https://demo.imagewize.test/ --path=web/wp
VMEOF

The trap here isn’t the command, it’s what happens after: any pattern using get_template_directory_uri() bakes an environment-specific URL straight into post_content — http://demo.imagewize.test/app/themes/nynaeve/patterns/images/foo.webp. That’s fine on local. It is not fine if that content ever reaches production without a search-replace pass first, since it’ll silently serve broken images or trip mixed-content warnings. I run a URL audit before anything with test patterns in it goes near a production database — worth building into your own checklist if you do content work this way.

5. Security checkup

wp-ops security-scan imagewize.com production
wp-ops security-scan imagewize.com production --hours 48 --threshold 50

Scans Nginx access logs on the target for attack signatures — repeated wp-login.php hits, SQL-injection strings, scanner user-agents — over a configurable window, flagging any IP over the request threshold. For file-level malware checks instead of log analysis, that’s a separate WP-CLI pass: wp eval-file wp-cli/security/scanner-wrapper.php run on the server, which is closer to a monthly job than a daily one.

6. Monitor checkup

wp-ops quick-status imagewize.com production

for the fast version — recent status codes, error counts, service status, good for “is this site okay right now.” The Nginx and PHP-FPM status checks used to fail outright with Missing sudo password: the playbook had become: yes on those two tasks, but systemctl status is a read-only query that doesn’t need root, and there’s no password source when the command runs non-interactively. Dropped become from both tasks so they run as the regular deploy user, matching the other read-only monitoring playbooks in the repo.

Fixing that surfaced a second, quieter bug in the same task: systemctl status php*-fpm was silently returning nothing. Systemd’s unit-name globbing needs the full suffix, so php*-fpm never matched php8.4-fpm.service even though the unit was loaded and running — and it exited rc=0 with empty output instead of erroring, so it went unnoticed right alongside the sudo fix. Quoting the glob and adding .service ('php*-fpm.service') fixed it for good.

For traffic alone — no security or AI-crawler noise mixed in — there’s a narrower command:

wp-ops traffic-report imagewize.com production --hours 120

That’s the last five days, and on a real run against imagewize.com it surfaces exactly what you’d hope: the homepage and /contact/ up top (436 and 187 hits), then whichever blog post is actually pulling organic traffic that week — /how-to-audit-your-woocommerce-store/ at 131 hits over that window, well ahead of the wp-ops post itself at 43. It’s the same Nginx log parsing as the combined monitor.sh run below, minus the security and error-log sections — the one I reach for when I just want a pulse check on what’s resonating that week, not a full report.

One gotcha: traffic-report runs through ansible-playbook, so it needs TRELLIS_DIR pointed at your Trellis project (export TRELLIS_DIR=/path/to/trellis), or to be run from inside it — unlike quick-status and the other read-only checks above, which resolve that on their own.

One more thing worth knowing before you trust that “real user” number: if you routinely hit the site over a VPN while testing, that traffic counts as human too — the UA-based bot filter has no way to catch it. Pulling a six-week traffic trend on imagewize.com surfaced this directly: the same three IPs (146.70.14.43–45, a ProtonVPN Indonesia exit-node range I test through) kept showing up in “Top IP Addresses,” inflating some weekly windows by up to 8%. traffic-monitor.sh 5.14.0 adds an EXCLUDE_IP_PATTERN for exactly this — set it once to your own VPN or dev-IP range and every section of the report (totals, top pages, top IPs, the SEO breakdowns) excludes it automatically, no extra filtering pass needed.

When I want the fuller picture — traffic, security, AI-crawler activity, and error logs together, saved as a timestamped report — that’s:

ssh web@imagewize.com 'bash -s' < scripts/monitoring/monitor.sh

streamed over SSH stdin rather than installed on the server, so there’s nothing left behind to clean up afterward.

7. GitHub traffic across the main repos

wp-ops gh-traffic imagewize/wp-ops imagewize/nynaeve imagewize/aludra imagewize/elayne imagewize/aviendha imagewize/ixian imagewize/ollama-opencode-setup imagewize/sage-native-block --all

Pulls views, clones, and referrers for each repo via GitHub’s traffic API — --all gets you every section, --quiet drops table headers if you’re piping the output somewhere. GitHub only retains 14 days of this data, so I run it weekly rather than let a slow week’s numbers age out unseen. imagewize.com itself is private, so it’s left out here — the traffic API is really only worth checking on the public repos anyway.

That’s the per-repo detail; when I just want to know which of those eight is actually getting traction that fortnight, --summary collapses it to one table instead:

wp-ops gh-traffic imagewize/wp-ops imagewize/nynaeve imagewize/aludra imagewize/elayne imagewize/aviendha imagewize/ixian imagewize/ollama-opencode-setup imagewize/sage-native-block --summary --all

Summary (14-day totals, sorted by unique views)
+---------------------------------+-------+--------+--------+--------+
| Repo                            | Views | Unique | Clones | Unique |
+---------------------------------+-------+--------+--------+--------+
| imagewize/ollama-opencode-setup |   173 |     96 |     12 |     12 |
| imagewize/wp-ops                |   176 |      8 |    215 |     96 |
| imagewize/nynaeve               |   278 |      7 |    108 |     50 |
| imagewize/sage-native-block     |    12 |      3 |      6 |      6 |
| imagewize/aviendha              |    62 |      3 |     83 |     41 |
| imagewize/aludra                |   131 |      3 |    329 |    113 |
| imagewize/elayne                |    56 |      2 |    153 |     55 |
| imagewize/ixian                 |    98 |      1 |    121 |     29 |
+---------------------------------+-------+--------+--------+--------+

To rank by clone activity instead of views — useful when you care more about adoption than browsing — add --sort-by unique-clones (or unique-views, the default):

wp-ops gh-traffic imagewize/wp-ops imagewize/nynaeve imagewize/aludra imagewize/elayne imagewize/aviendha imagewize/ixian imagewize/ollama-opencode-setup imagewize/sage-native-block imagewize/pt-cli imagewize/warder-cookie-consent imagewize/waygate imagewize/wp-cli-pattern-validate imagewize/trellis-wp-monitoring --summary --all --sort-by unique-clones

Summary (14-day totals, sorted by unique clones)
+-----------------------------------+-------+--------+--------+--------+
| Repo                              | Views | Unique | Clones | Unique |
+-----------------------------------+-------+--------+--------+--------+
| imagewize/wp-ops                  |   230 |      8 |    287 |    101 |
| imagewize/elayne                  |   122 |      2 |    198 |     60 |
| imagewize/aviendha                |    69 |      3 |    135 |     52 |
| imagewize/warder-cookie-consent   |    38 |      1 |    104 |     51 |
| imagewize/aludra                  |    29 |      2 |    115 |     47 |
| imagewize/nynaeve                 |    88 |      5 |    117 |     45 |
| imagewize/ixian                   |    32 |      1 |     56 |     23 |
| imagewize/pt-cli                  |     3 |      1 |     18 |     14 |
| imagewize/waygate                 |     4 |      3 |     13 |     12 |
| imagewize/sage-native-block       |     5 |      2 |      9 |      8 |
| imagewize/trellis-wp-monitoring   |    13 |      3 |      9 |      7 |
| imagewize/ollama-opencode-setup   |   154 |     96 |      6 |      6 |
| imagewize/wp-cli-pattern-validate |     2 |      1 |      4 |      4 |
+-----------------------------------+-------+--------+--------+--------+

Sorted by unique views rather than raw views, which is the more honest ranking — ollama-opencode-setup had fewer total hits than nynaeve but far more distinct people looking, versus wp-ops itself pulling 176 views from what’s mostly the same handful of visitors returning. Clones tell a different story again: aludra and wp-ops both see heavy clone volume relative to their view counts, which reads as CI or dependency installs pulling the repo rather than people browsing it on GitHub.

The point of collapsing this into a CLI

None of these seven things were hard to run individually — every one of them already existed as a playbook or script before wp-ops did. What was hard was remembering which one and with what flags, across a dozen site keys, without pasting a domain into the wrong environment. Manifest-driven discovery means the catalog documents itself: wp-ops search backup, wp-ops <command> --help, and the interactive picker all read from the same source the commands themselves declare, so the list can’t drift out of sync with what’s actually runnable.

This is part of the tooling we run at Imagewize for client WordPress operations on Trellis. If your team is drowning in the same kind of scattered-script sprawl, get in touch.

Questions about your own Trellis workflow? Find me on Mastodon at @jfrumau@mastodon.social.

That was the last straw. This post covers PR #397: moving Nynaeve from a git-tracked directory to a real Composer dependency — the same pattern the project already used for imagewize/min and imagewize/callandor — and the deploy-hook rework that made it work with Trellis.

The Old Setup

• web/app/themes/nynaeve was committed straight into the site repo: 411 files, full history, PHP source, compiled assets, fonts, icons — everything.
• The theme’s actual source of truth was a separate repo, ~/code/nynaeve.
• rsync-theme.sh pushed changes from the site repo copy back to the standalone repo (or the reverse, depending on which way you’d last edited). Either direction relied on a human running it at the right time.
• Two copies, one intended source of truth, no enforcement. The block-namespace drift was the first visible symptom; it wouldn’t have been the last.

What Changed

site/composer.json now requires the theme directly:

"require": {
    "imagewize/nynaeve": "^3.1.0"
}

Nynaeve’s own composer.json already declares "type": "wordpress-theme", so Bedrock’s existing installer-paths mapping drops it into web/app/themes/nynaeve/ automatically — no extra config needed on the consuming side. site/.gitignore gets web/app/themes/nynaeve added, matching the other Composer-managed themes already in the project (twentytwentyfive, ianua). The 411 tracked files come out of git in the same commit.

That’s the easy part. The part that took real thought was the deploy hooks.

Why the Deploy Hook Had to Split in Two

Trellis builds a release in stages, and two of our theme-build steps depend on the theme’s PHP source being present on the remote release path — not just locally:

1. The theme’s own composer install (its acorn / illuminate / acf-composer dependencies — Sage themes carry their own theme-scoped vendor/, separate from the project root’s).
2. Copying the compiled public/build assets up to the release.

Before this change, Nynaeve’s source was git-tracked, so git archive — which is what actually populates a Trellis release directory — brought the theme’s PHP along for free. Once Nynaeve stopped being git-tracked, git archive had nothing to bring. The theme only exists on the release path after something runs composer install against the release’s composer.json.

That something is Trellis’s own core hook. deploy_build_after (roles/deploy/defaults/main.yml) runs the core roles/deploy/hooks/build-after.yml — which does the root-level composer install that fetches imagewize/nynaeve onto the release — before it runs our site’s own build-after.yml override. That ordering is the whole trick: our custom build-after hook can safely assume the theme source already exists on the release path, because Trellis’s own hook just put it there.

Which means the theme’s own composer install and the asset copy can’t live in build-before.yml — at build-before time, on a fresh deploy, the theme hasn’t been fetched onto the release yet. They have to move to build-after.yml, downstream of the core hook.

build-before.yml — local concerns only

- name: Install root Composer dependencies (pulls nynaeve theme package)
  command: composer install
  delegate_to: localhost
  args:
    chdir: "{{ project_local_path }}"
  when: site == 'imagewize.com'

- name: Install npm dependencies
  command: npm install
  delegate_to: localhost
  args:
    chdir: "{{ project_local_path }}/web/app/themes/nynaeve"
  when: site == 'imagewize.com'

- name: Compile assets
  command: npm run build
  delegate_to: localhost
  args:
    chdir: "{{ project_local_path }}/web/app/themes/nynaeve"
  when: site == 'imagewize.com'

Everything here runs on the machine doing the deploy, not the remote release. The local composer install pulls imagewize/nynaeve down locally too (so npm install/npm run build have theme source to compile against), and a stat + fail guard right after confirms public/build/manifest.json exists before the deploy is allowed to continue — no silently shipping a release with no compiled assets.

build-after.yml — the two steps that need the remote release

- name: Install theme's own Composer dependencies
  command: composer install --no-ansi --no-dev --no-interaction --no-progress --optimize-autoloader --no-scripts --classmap-authoritative
  args:
    chdir: "{{ deploy_helper.new_release_path }}/web/app/themes/nynaeve"
  when: site == 'imagewize.com'

- name: Copy compiled assets
  synchronize:
    src: "{{ project_local_path }}/web/app/themes/nynaeve/public"
    dest: "{{ deploy_helper.new_release_path }}/web/app/themes/nynaeve"
    group: no
    owner: no
    rsync_opts: --chmod=Du=rwx,--chmod=Dg=rx,--chmod=Do=rx,--chmod=Fu=rw,--chmod=Fg=r,--chmod=Fo=r
  when: site == 'imagewize.com'

The compiled assets themselves are still built locally in build-before (rebuilding on the server would mean shipping npm/node as a production dependency, which we don’t want), then rsynced up from the local public/build directory onto the just-fetched theme on the release path. Both steps stay gated when: site == 'imagewize.com' — block themes like Elayne on demo.imagewize.com skip this whole file, same as before.

Switching to Packagist

The PR started with a vcs repository entry pointing straight at git@github.com:imagewize/nynaeve.git on a dev-main pin, purely to prove the mechanism worked end to end. Once that was confirmed, imagewize/nynaeve got published to Packagist — same as Elayne, Aviendha, and Aludra — and the vcs entry came out, replaced with a version constraint:

"imagewize/nynaeve": "^3.1.0"

composer.lock now records a genuine dist install: a GitHub zipball pulled through Packagist, not a live git clone. No .git/ directory shows up in the installed copy, which is the tell that confirms it. On-disk style.css reports Version: 3.1.0, matching the lockfile.

One Idea That Didn’t Survive Contact With Lima

Before settling on the Composer-dependency approach, there was a tempting shortcut: add a path repository (../../nynaeve, symlink: true) ahead of the Packagist one, so Composer would symlink straight to ~/code/nynaeve locally instead of downloading a dist copy. That would kill the rsync loop entirely and give live HMR against uncommitted theme edits — no publish step needed just to see a change.

It works fine on the raw macOS filesystem. It does not work inside the Lima VM that actually serves imagewize.test. Lima only mounts specific subdirectories of ~/code/imagewize.com — confirmed with limactl show-ssh imagewize.com — and ~/code/nynaeve isn’t one of them. From inside the VM, the symlink points at nothing. Reverted that part. A Lima mount for ~/code/nynaeve is a plausible follow-up if the sync-script loop below turns out to be annoying in daily use, but it wasn’t worth blocking this PR on.

Local Dev Workflow Now

Editing happens in ~/code/nynaeve, same as before. Testing a change locally without cutting a full release uses wp-ops’s sync script, matching the pattern already in use for Elayne, Aviendha, and Aludra:

SITE_ROOT=~/code/imagewize.com/site/web/app \
  wp-ops/scripts/sync/rsync-package-to-site.sh theme nynaeve ~/code/nynaeve

To publish for real: tag and push the theme repo, then pull it into the site with composer update imagewize/nynaeve. The old rsync-theme.sh — the one that synced imagewize.com’s copy back to the mirror — is obsolete and gone.

A Tradeoff We’re Leaving As-Is

Nynaeve’s own composer.json require (acorn, illuminate/*, acf-composer, etc.) now also gets resolved into the site’s root vendor/ when Composer solves the whole project, on top of the theme’s own theme-scoped vendor/ that functions.php actually loads via __DIR__.'/vendor/autoload.php'. The root copy is never used — it’s dead weight from Composer’s dependency solver, not a functional problem. This is a pre-existing property of the Sage/Acorn “theme carries its own vendor” convention, not something this change introduced, and not worth fighting.

Verifying It

Before the Packagist switch, we ran the full local equivalent of the new build-before → build-after sequence by hand against the Trellis VM:

composer update imagewize/nynaeve --with-dependencies   # in site/ — pulled from GitHub, dev-main
npm install && npm run build                              # in the theme dir — built clean
composer install ...                                       # in the theme dir — own vendor/autoload.php
wp cache flush && wp theme status nynaeve                  # → Status: Active, Version: 3.1.0
curl http://imagewize.test/                                 # → 200, correct <title>

After switching to Packagist, the re-check was static rather than a full VM run — same installed theme, just a different resolution path: composer validate passes, composer.lock/installed.json agree on v3.1.0 resolved via Packagist’s GitHub zipball dist, no .git/ present (confirming dist, not VCS), and style.css still reports 3.1.0.

An actual trellis deploy to production was intentionally left for after merge — the plan was to review the build-before/build-after split first, then deploy and watch the theme’s Composer-install step and the asset-copy step specifically, since those are the two that moved.

Takeaway

The mechanism worth remembering here isn’t Composer-specific — it’s the hook ordering. Trellis’s core build-after.yml hook runs before a site’s own override of the same file, and that ordering is what makes it possible to fetch a package onto the release and immediately depend on it being there in the very next hook, without any extra “wait for it” logic. Once that ordering clicked, the fix was mechanical: move the two steps that need the theme’s PHP present on the remote release from build-before to build-after, and let Trellis’s own hook do the fetching in between.

The bigger win is structural, not mechanical: one source of truth for the theme, published like any other dependency, with drift no longer possible by construction instead of caught after the fact — the way the block-namespace bug was.

This is part of the Trellis/Bedrock/Sage deployment stack we run at Imagewize for client projects. If you’re maintaining a Sage or Acorn theme alongside a Trellis deploy and want a second set of eyes on the setup, get in touch.

Running a similar Composer-managed theme setup and hit a snag? Find me on Mastodon at @jfrumau@mastodon.social.