DEV Community: Dmitry Rechkin

Configuring WooCommerce Shipping From the Terminal: WP-CLI + Claude Code Skills

Dmitry Rechkin — Wed, 01 Jul 2026 04:46:01 +0000

TL;DR: To configure WooCommerce shipping from the command line, use the 1TeamSoftware plugins, which expose their full config and fulfillment surface through WP-CLI: run wp wc-shippo-shipping settings set to write origin, credentials, and services, wp wc-shippo-shipping validate to gate a deploy, and wp wc-shippo-shipping rates quote to prove a live rate comes back. The same commands ship as a Claude Code skill, so an AI agent can run them too.

This is the terminal how-to; every command is real and uses the Shippo namespace. It assumes you're comfortable with WP-CLI and know your way around WooCommerce shipping zones and methods. You don't need prior carrier-API knowledge.

Run more than one WooCommerce store and you've met the problem already: shipping setup doesn't survive scale.

You configure zones, boxes, and carrier credentials by clicking through wp-admin. It works. Then you do it again on staging, then again for the next client, each pass a little different because a settings screen won't let you repeat yourself exactly. The failure mode is the bad part. A customer hits checkout, sees no shipping options at checkout, and leaves. Nothing in the logs says why. You find out from a support email three days later.

I wanted shipping to behave like the rest of my infrastructure: text I can diff, commit, replay across environments, and gate in CI. That's what the 1TeamSoftware shipping plugins give you. It all runs through WP-CLI, and the same commands are wrapped in a Claude Code skill so an agent can drive them.

This is the developer tour. Every command below is real, copy-pasteable, and uses the Shippo namespace (wc-shippo-shipping). Swap the namespace for your carrier and the rest holds. For the complete reference with every flag and output shape, see the full pillar: configuring WooCommerce shipping with AI and WP-CLI.

Prefer to watch first? Here's the whole setup running end to end from the terminal, then handed to an AI agent. Every command below is in the video.

One prerequisite, said plainly

A lot of "official" carrier integrations import orders and print labels but never quote a price at checkout. If your current tool can't return a rate to the cart, no CLI command will make one appear there.

The plugins here quote woocommerce live shipping rates at cart and checkout, validate addresses, pack boxes, buy labels, and pull tracking. All of it is scriptable. The rest of this assumes you've got that.

The command shape

Everything follows one pattern:

wp <namespace> <command> [<subcommand>] [--flags]

The namespace is the plugin slug with -pro dropped, so Shippo is wc-shippo-shipping for both the free and PRO editions. Not sure what yours is?

wp help | grep shipping

wc-shippo-shipping    Manage Shippo shipping configuration and fulfillment.

One thing the command list won't hand you: the exact setting keys. Credential fields, service IDs, and box types differ per carrier, so discover them instead of guessing.

wp wc-shippo-shipping settings list

+----------------------+---------------------+
| key                  | value               |
+----------------------+---------------------+
| testApiToken         | [REDACTED]          |
| liveApiToken         | [REDACTED]          |
| sandbox              | yes                 |
| priceAdjustmentPercent | 1.00              |
| maxShippingRates     | 0                   |
+----------------------+---------------------+

settings list is your map. It prints every stored setting with secrets shown as [REDACTED], which is also how you find a carrier's credential keys before you write them. Shippo uses testApiToken and liveApiToken; other carriers name theirs differently. Read first, write second.

Start with status and validate

Before touching anything, check what the plugin actually sees.

wp wc-shippo-shipping status --format=json
wp wc-shippo-shipping validate
wp wc-shippo-shipping zones

status --format=json returns something like:

{
  "version": "2.4.10",
  "carrier": "Shippo",
  "sandbox": true,
  "debug": false,
  "live_rates": true,
  "origin": "San Francisco, CA, US",
  "method_instances": 2
}

status reports version, carrier, sandbox and debug flags, live-rate state, origin, and method-instance count. Watch what it doesn't report: API connectivity. There's no "connected: true" field, because the only honest connectivity test is asking the carrier for a real quote.

validate is the one to put in your pipeline. It runs every config check and reports PASS, FAIL, WARN, INFO, or PENDING, and it exits non-zero on any FAIL:

PASS  Origin address is complete
PASS  API token is set
WARN  No box presets configured; falling back to per-item packing
FAIL  Plugin not attached to zone "Rest of World"

That non-zero exit is what makes it a clean deploy gate:

wp wc-shippo-shipping validate --format=json 2>/dev/null \
  | jq -e 'all(.[]; .status != "FAIL")' >/dev/null \
  || { echo "Shipping config has failures"; wp wc-shippo-shipping validate; exit 1; }

WARN doesn't break the build; only FAIL does. Drop this in your release script and a broken shipping config stops a deploy before customers ever see it.

zones shows which WooCommerce shipping zones the plugin is attached to, with plugin_active, instance_id, and method_id per zone:

+---------+-----------------+---------------+-------------+
| zone_id | zone_name       | plugin_active | instance_id |
+---------+-----------------+---------------+-------------+
| 1       | US Domestic     | yes           | 4           |
| 2       | Rest of World   | no            | -           |
+---------+-----------------+---------------+-------------+

Remember this one. It's behind most "no rates" tickets: zone 2 above quotes nothing because the method was never added.

Reading and writing settings

Anything stored is readable and writable from the CLI, credentials and origin included.

wp wc-shippo-shipping settings get origin
wp wc-shippo-shipping settings set origin '{"name":"Co","address":"123 Main St","city":"SF","state":"CA","postcode":"94105","country":"US"}'

Associative settings flatten with bracket notation (origin[city], services[usps_priority][enabled]). Read a single value with settings get <key>, add --raw to reveal a secret, write with settings set <key> <value>, and target one zone with --instance=<id>. Your origin address now lives in a provisioning script instead of someone's memory.

Proving rates actually come back

This is the test that matters. A green validate tells you the config is internally consistent. A real quote tells you the carrier is reachable and the route is actually served.

wp wc-shippo-shipping rates quote --products="9405:2" --destination="500 5th Ave, New York, NY 10001, US"
wp wc-shippo-shipping rates get --order=12345

After the human log line, the JSON array looks like:

[
  { "service": "USPS Ground Advantage", "amount": "8.45", "currency": "USD", "days": 3 },
  { "service": "USPS Priority Mail",    "amount": "11.20", "currency": "USD", "days": 2 }
]

rates quote asks the carrier for a live quote on an ad-hoc product and destination. It needs at minimum a ZIP or postcode plus a country; a full street address sharpens accuracy. One scripting gotcha: it prints a human log line before the JSON, so when you parse it, extract the array from the first [ to the matching ] rather than leaning on 2>/dev/null. rates get does the same for an existing order by ID.

If a complete product on a covered route returns nothing, that tells you something real: either a connectivity failure or a route the carrier doesn't serve. Either way you now know, instead of guessing from a blank checkout.

How do I fix "no shipping options at checkout"?

When a store shows no rates for some customers but not others, it's almost always one of two things: a zone the plugin isn't attached to, or products with no weight. Here's the workflow I reach for.

The zone case is sneaky because rates work for you and not for the buyer in another region. The plugin only returns rates on zones where it's attached as a shipping method, so a missing zone is a silent dead end. You won't see it from your own checkout.

wp wc-shippo-shipping zones
wp wc shipping_zone_method create --zone_id=2 --method_id=wc-shippo-shipping --user=1

zones shows each zone's plugin_active. Where it reads plugin_active: no, add the method. In zone-based mode, being absent from a zone means no rates there; in global mode it's fine.

The product-data case is the other half. Rates drop silently when an item has no weight, because the carrier can't quote a parcel that has no size.

wp wc-shippo-shipping products audit --detailed --format=json --limit=0

{
  "total_products": 412,
  "completeness_percent": 87,
  "missing_weight_products": [1842, 1907],
  "missing_dimensions_products": [1842, 1907, 2003],
  "suspicious_data_products": [1559]
}

products audit gives a completeness percentage and flags missing weight, missing dimensions, and suspicious values. The per-product arrays (missing_weight_products, missing_dimensions_products, suspicious_data_products) only appear with --format=json. Pass --limit=0 so a big catalog isn't capped at 500. Fix the flagged products with wp wc product update, re-quote, and the rates come back.

Sizing boxes to what you actually ship

Rates look high for a boring reason more often than you'd think: parcels get quoted in oversized boxes nobody matched to the catalog.

wp wc-shippo-shipping products stats --format=json
wp wc-shippo-shipping products orders --since=2025-12-01 --format=json
wp wc-shippo-shipping products fit-box --length=12 --width=8 --height=6

products stats returns weight and dimension stats plus a size distribution. products orders analyzes completed and processing orders: items per order, top destination states, domestic versus international. products fit-box takes box dimensions (all three required) and reports what percentage of your catalog fits, rotation handled automatically. Together they tell you whether a candidate box set covers what leaves your warehouse before you commit it.

Tuning rates: markup, floors, and which services show

Same complaint, three flavors: undercharging, too many options at checkout, or a $1.50 Media Mail rate leaking through. All of these adjustment fields live in the free plugin.

wp wc-shippo-shipping settings set priceAdjustmentPercent 1.15
wp wc-shippo-shipping settings set priceAdjustment 2.00
wp wc-shippo-shipping settings set minRateCost 5.00
wp wc-shippo-shipping settings set maxShippingRates 3
wp wc-shippo-shipping services --format=json
wp wc-shippo-shipping settings set services '{"usps_ground_advantage":{"enabled":true,"name":"USPS Ground Advantage"}}'

Watch priceAdjustmentPercent. It's a multiplier, so 1.15 adds 15%. Set it to 15 and you multiply every rate fifteenfold, which makes for a funny bug report after the fact. Adjustments apply in order: carrier rate, then percent, then fixed, then floor and ceiling, then the max-count cap. To control which services quote at all, discover real IDs with services first and write them with settings set services. Never invent service IDs.

The PRO half: labels, tracking, manifests

Once a license is active, fulfillment is on the CLI too, and it behaves the same whether a person, an agent, or a cron job runs it.

wp wc-shippo-shipping labels purchase --orders=1240,1241,1242
wp wc-shippo-shipping labels pdf --orders=1240,1241,1242 --output=/var/labels/2026-06-11.pdf
wp wc-shippo-shipping track abc123 --order=1240 --format=json
wp wc-shippo-shipping manifest create --shipments=abc123,def456 --ship-date=2026-06-11
wp wc-shippo-shipping license activate YOUR-KEY

labels purchase buys a batch and auto-creates shipments if they're missing, but it logs label counts, not tracking numbers, so pull those from track or shipments get. labels pdf merges many orders into one print-ready file and errors if the target already exists, so dated filenames are the safe move. manifest create builds a carrier SCAN form from shipment IDs. And license activate takes the key as a positional argument, not --key=.

So a nightly fulfillment run is a five-line script: collect the day's processing order IDs, buy labels in one batch, merge to a dated PDF for the print station.

Handing it to Claude Code

The commands above are stable enough to script directly. There's a second mode too: install a skill and let an AI agent drive the same CLI from plain language.

npx skills add https://github.com/1TeamSoftware/skills --skill 1teamsoftware-wc-shipping

Under the hood the skill is a small library of playbooks. Ask it to fix box coverage and it reaches for the box-sizing routine instead of guessing at flags. It runs the exact same WP-CLI a human would, and it pauses to ask for secrets rather than inventing them. No hidden API layer, no magic. The free plugin ships 6 skills; PRO adds 4.

In practice you describe the job with real constraints and let it work one step at a time:

"Customers in some regions say no shipping options appear. Make the plugin active for both my US domestic zone and Rest of World, then show me the zone coverage table so I can confirm it's attached where it needs to be."

"Set up Shippo from scratch. Sandbox key is shippo_test_abc123, we ship from 215 Clayton St, San Francisco 94117. Audit my catalog for missing weight or dimensions, recommend a starter box set from what I actually sell, and prove rates come back with a real quote. Ask one question at a time and don't touch my live key yet."

The security model helps anyone managing a fleet: hand the agent a sandbox key during setup, rotate to the live key yourself, and it never needs to see the real one. Secrets stay redacted in CLI output, and you can store credentials in wp-config.php constants so they never touch the database at all.

Which carriers does this work with?

The same engine, settings model, and command set run across eight carrier plugins: Shippo, EasyPost, FedEx, ShipStation, ShipEngine, Shipmondo, ChitChats, and Stallion Express. Only the namespace and a few setting keys change. Run wp help | grep shipping to find the namespace, then settings list to discover the keys.

One catch worth knowing: the current ShipStation plugin runs on the carrier's API v2, so its namespace is wc-shipstation-shipping-v2, not the legacy wc-shipstation-shipping. When in doubt, trust what wp help prints.

Trade-offs: what this doesn't do

The CLI isn't free of edges, so here they are:

Free vs PRO is gated. Configuration, diagnostics, and live rate quotes work in the free plugin. Labels, tracking, and manifests need an active PRO license, and those commands fail without one.
An agent can't invent secrets. Hand Claude Code a store with no API token and it stops to ask. By design it never fabricates a credential or a service ID, so first-run setup still needs you in the loop for keys.
There's a CLI learning curve. If you've never touched WP-CLI, the first hour is slower than clicking through wp-admin. The payoff shows up on store two, not store one.
No connectivity check shortcut. validate confirms the config is internally consistent, not that the carrier is reachable. The only real proof is a rates quote, which costs an API round-trip.
priceAdjustmentPercent is a multiplier, not a percent field. 1.15 means +15%. Pass 15 and you've multiplied every rate fifteenfold. Easy to fat-finger.

Why bother, if a settings screen works?

For one store you set up once, it doesn't. The UI is fine.

The CLI earns its keep the moment shipping becomes something you operate: multiple stores, staging-to-production parity, agency work that repeats per client, audits you can re-run on demand, a deploy gate that blocks releases on a broken config, and increasingly a workflow you can hand to an agent. That's the same engine already running on thousands of WooCommerce stores, so this is a well-worn path, not an experiment.

Try it

The free Shippo plugin covers configuration and live rate quotes; PRO adds labels, tracking, and manifests. Install the skill, point Claude Code at a staging store, and run a validate plus a rates quote to watch the whole loop work:

npx skills add https://github.com/1TeamSoftware/skills --skill 1teamsoftware-wc-shipping

If you've ever debugged a blank checkout at 11pm, shipping you can diff and replay is worth the ten minutes it takes to set up. The full command reference and AI-agent walkthrough live in the WooCommerce shipping WP-CLI and AI pillar.

I Stopped Clicking Around wp-admin and Treated WordPress Media Offload Like Infrastructure

Dmitry Rechkin — Sun, 08 Mar 2026 01:20:28 +0000

I Stopped Clicking Around wp-admin and Treated WordPress Media Offload Like Infrastructure

WordPress media libraries have a habit of turning into infrastructure problems in slow motion. At first it is just uploads. Then it is product galleries, thumbnails, originals, PDFs, course files, and downloads piling up on the same server that is supposed to stay lean.

That arrangement does not age well. Disks fill up, backups get bloated, restore times get longer, and moving a site between environments becomes more painful than anyone expected. The media library quietly becomes one of the least portable parts of the stack.

The first fix is straightforward: stop keeping all of that media on the WordPress server. Offloading uploads to object storage such as Cloudflare R2, Amazon S3, or Google Cloud Storage takes that weight off the app layer and makes the stack easier to scale.

But offloading media creates a second problem. Somebody still has to configure the provider, test the account, migrate existing files, verify URL rewriting, and repeat the setup without drift across environments. That is where a settings page starts to feel pretty flimsy.

If media offload matters to your stack, it needs a repeatable CLI workflow with wp and wp cloudsync, explicit verification steps, and clear boundaries for where AI is allowed to help.

TL;DR

Treat WordPress media offload as infrastructure, not as a page full of one-time clicks.
Use WP-CLI as the execution layer.
Use agent skills for repeatability, not for "magic."
Verify what your installed plugin edition actually supports with wp help cloudsync.
Be honest about what you have tested locally.

The thing that kept bugging me

Most WordPress automation discussions get weirdly abstract, weirdly fast.

People jump straight to "AI agents managing infrastructure" without first answering a much more boring question: is the workflow itself any good?

If the setup depends on memory, screenshots, and whoever configured production six months ago, an agent is not going to save you. It will just fail faster and in a more exciting way.

The useful version is much smaller:

Write down the exact CLI steps.
Decide what is allowed to run.
Add verification points.
Let the agent execute the boring parts.

That is it. No mystery. No hand waving.

Why media offload becomes an infrastructure concern

Once uploads stay on the app server, you get the usual headaches:

disk usage grows in places you were hoping would stay disposable
backups get bigger and slower
multi-environment parity gets sloppy
stateless deployments stop being truly stateless
migration work gets riskier than it needs to be

Moving media to object storage helps. Doing it repeatably is the real win.

That is why WP-CLI matters here. A GUI is fine for exploration. It is not a serious operating model for repeated rollout.

Where AI actually fits

A plugin with meaningful CLI coverage gives an agent something it can use safely:

known commands
known flags
visible output
a place to stop and verify

CloudSync Master exposes this through wp cloudsync, but the exact command set depends on whether you are running the free plugin or Pro. Check wp help cloudsync on the target site first. Do not write a giant automation layer around commands you have not even confirmed exist.

If your team uses reusable agent instructions, 1TeamSoftware already publishes them here:

Install looks like this:

npx skills add https://github.com/1TeamSoftware/skills --skill 1teamsoftware/wp-cloudsync-master

That gives the agent plugin-specific instructions. It does not replace judgment. It just reduces guessing.

What was verified locally

On a LocalWP site, I was able to get WP-CLI working against the correct PHP runtime and MySQL socket, then verify these free CloudSync commands:

wp cloudsync status
wp cloudsync accounts list
wp cloudsync sync

Those worked locally.

The broader Pro command surface was not fully validated in that environment. During CLI testing, the Pro plugin hit a fatal because of a missing NullTaskScheduler class. So the larger command blocks below should be read as Pro-oriented workflow examples unless they have been verified on the target site.

A practical R2 workflow

Cloudflare R2 comes up often for WordPress media for an obvious reason: egress.

If you serve a lot of images, egress is often the part that gets expensive in a hurry. R2 changes that conversation. It does not make storage free, and it does not remove operational mistakes, but it does change the cost model enough that teams keep revisiting it.

Official pricing reference: Cloudflare R2 Pricing

Here is a Pro-oriented example flow.

1. Add and activate the R2 account

Before you run this, replace the placeholders with real values:

R2_ACCESS_KEY: your R2 access key ID
R2_SECRET_KEY: the matching secret
R2_ACCOUNT_ID: your Cloudflare account ID

You usually get them from the Cloudflare dashboard while creating the R2 API token and bucket.

wp cloudsync accounts add \
  --provider=cloudflare_r2 \
  --name="Production R2" \
  --bucket=my-media-bucket \
  --access-key-id=$R2_ACCESS_KEY \
  --secret-access-key=$R2_SECRET_KEY \
  --region=auto \
  --api-endpoint=https://$R2_ACCOUNT_ID.r2.cloudflarestorage.com \
  --custom-domain=media.example.com \
  --activate

2. Test it before you do anything expensive

wp cloudsync accounts test --account=1

This is where a lot of bad migrations should stop. Wrong endpoint, wrong key pair, wrong bucket policy, clock skew: better to find it here than halfway through a queue.

3. Apply baseline settings

wp cloudsync settings set createObjectOnFileUpload yes
wp cloudsync settings set rewriteFileUrlWithObjectUrl yes
wp cloudsync settings set uploadBatchSize 25
wp cloudsync settings set uploadConcurrency 3

I would start conservatively. Teams love turning concurrency up too early, then acting surprised when the host or provider becomes the bottleneck.

4. Sync existing media

wp cloudsync sync --batch-size=100

5. Stop and look at the system

wp cloudsync status --format=json
wp cloudsync queue status

If your automation cannot pause and make someone look at state, it is not mature enough yet.

Migration is where people get nervous

Fair enough. They should.

Most teams are not setting this up from scratch. They are moving from an existing plugin and trying not to break URLs, image rendering, or download paths along the way.

For teams moving from WP Offload Media, a Pro migration flow can look like this:

wp cloudsync migrate detect
wp cloudsync migrate import --from=wp-offload-media
wp cloudsync accounts list
wp cloudsync accounts test --account=<imported-id>

That is the part I would scrutinize hardest during evaluation:

can it import metadata from the current plugin?
can it verify the imported account cleanly?
can you keep serving media safely during the transition?
can you move configuration out of the admin UI after cutover?

A direct comparison is here: CloudSync Master vs WP Offload Media.

Current provider support note

As of March 5, 2026, the WordPress.org listing for WP Offload Media Lite includes Amazon S3, DigitalOcean Spaces, and Google Cloud Storage, but not Cloudflare R2. For teams that want to use R2, that difference matters.

Reference: WP Offload Media Lite on WordPress.org

The hardening step people skip

One of the better habits in infrastructure work is moving from "it works in the dashboard" to "this is managed configuration now."

That means:

configure the account
validate it
export the hardened configuration
move the source of truth to wp-config.php or environment variables

In Pro, that looks like:

wp cloudsync config generate --account=1

It is not the flashiest part of the workflow, but it is the bit that makes audits, environment parity, and incident response less annoying later.

A few mistakes I keep seeing

Treating prompts as process

A good prompt is not the asset. The asset is a repeatable workflow with guardrails.

Rolling out to production first

No. Use staging with representative media first. Always.

Hiding uncertainty

If you have not tested the command on a real site, say that. Developers can handle uncertainty. What they hate is fake certainty.

Leaving rollback vague

"We can just revert it" is not a rollback plan.

Write down the exact rollback steps:

switch active account back
disable URL rewriting if needed
keep fallback behavior intact until samples are clean

A simple evaluation checklist

If I were choosing a WordPress media offload plugin today, I would ask:

Can I operate it through CLI instead of through screenshots and memory?
Can I test an account before migration?
Can I migrate from WP Offload Media or another existing plugin?
Can I move config into wp-config.php or env vars?
Can I start with the free version before committing to Pro?

That last one matters more than people admit.

You can start here:

The 67MB Problem: Building a Lightweight WordPress Media Offload Alternative

Dmitry Rechkin — Tue, 24 Feb 2026 20:52:11 +0000

We had unused Google Cloud credits sitting around, so I threw WordPress onto Google Cloud Run as a serverless experiment. It went fine until I hit the media library.

That roadblock led me down a rabbit hole: trying to offload media from WordPress to cloud storage usually means installing heavy, bloated SDKs. Here’s how that discovery led us to build a different kind of WordPress media offload plugin.

The Problem

If you run a CMS in a stateless environment, the biggest headache is always the same: where do the uploads go?

To horizontally scale compute instances, your infrastructure has to be stateless. Every image or PDF uploaded to the WordPress media library needs to go straight to an object store like Google Cloud Storage (GCS). Otherwise, your containers drop out of sync, and images start breaking the second a new instance spins up.

I assumed finding a plugin to connect WordPress to Google Cloud Storage would take five minutes.

It didn't.

Step 1: Discovering SDK Bloat

I started testing existing WordPress offload media plugins. Since I was targeting GCS, my first thought was to grab one built on the official Google Cloud PHP SDK.

Then I checked the deployment sizes.

One of the most popular offload plugins weighed 67MB installed.

The entire WordPress core is about 73MB. A single offload plugin was nearly the size of the CMS itself.

Why does a plugin that just moves images from Point A to Point B need to rival the size of WordPress? Two words: SDK Bloat.

Bundling an official SDK (like the AWS SDK or Google Cloud PHP Client) gets you the methods to upload and delete files. But it also drags in tens of megabytes of boilerplate, dependencies, and API definitions for cloud services you are never going to touch.

Why this breaks serverless WordPress:

On a standard $5/month VPS, a 67MB plugin slows down WP-Admin a bit. Annoying, but manageable.
In serverless environments, deployment size dictates performance. Cold start times and deployment speeds depend on keeping the codebase small.
I also experimented with running WordPress on Vercel (see my vercel-wordpress repo), where serverless functions have a 250MB size limit. WordPress is ~73MB, WooCommerce adds another ~51MB, and one 67MB offload plugin puts you at 191MB — leaving barely 60MB for your theme and every other plugin combined.

Shipping a 67MB vendor folder just to upload images feels like bad architecture. It increases cold-start latency, slows down deployment pipelines, and adds thousands of files to your security surface area.

I wanted a lightweight WordPress cloud storage plugin that could offload media without dragging down performance. Since I couldn't find one that was actually lean, I pulled in my team and we decided to build it ourselves.

Step 2: Dropping the SDK Entirely

Think about what a WordPress media offload plugin actually needs to do:

Authenticate.
PUT an object.
DELETE an object.
Generate a signed URL for private files.

We don't need a unified SDK for that. We just need to make authenticated REST API calls.

// Generic SDK clients were replaced with focused Guzzle requests
$client = new \GuzzleHttp\Client();
$response = $client->request('PUT', $cloud_provider_url, [
    'headers' => $authentication_headers,
    'body'    => $file_stream
]);

How it works:

We use Guzzle for the underlying HTTP requests.
Uploads happen asynchronously in the background. This keeps the upload process from blocking the main WordPress thread. Nobody wants a slow WP-Admin.

We wrote our own authentication wrappers (handling AWS V4 signatures and Google OAuth) and talked directly to the cloud REST APIs. This let us throw out the bloated SDKs entirely.

Step 3: Engineering CloudSync Master

That realization turned into CloudSync Master.

Focusing purely on the necessary API calls brought the installed plugin size down to under 2.5MB (the PRO build compiles to 1.5MB).

It’s roughly 30x smaller than the 67MB behemoth we started with. The codebase is lean, 95% type-safe, and it doesn’t drag down the site’s admin performance.

The project started as a quick way to run WordPress on Google Cloud Run using free credits. But halfway through, I paused the migration. Storage itself is cheap, but serving those files (bandwidth egress) adds up fast.

We pivoted to Cloudflare R2. The reason is simple: R2 charges zero egress fees and comes with Cloudflare's global CDN built in. For a media-heavy WordPress site, that's a significant cost difference.

Switching providers created a new problem: moving existing media from GCS to R2. Downloading gigabytes of files to small server instances just to re-upload them would instantly blow out our local disk space and crash the container.

Instead, we built a cross-provider migration engine directly into the plugin. It streams files from the old provider into memory, pushes them to the new provider, and rewrites the database URLs, all in the background. Files never touch the local disk.

This lightweight, API-first approach scaled better than we expected. CloudSync Master now supports 10 providers—Amazon S3, Cloudflare R2, DigitalOcean Spaces, Backblaze B2, Wasabi, and others—inside that same 2.5MB footprint.

Step 4: The Sync Bottleneck (Why Background Queues Matter)

When you're migrating a site with 10,000 existing images, you start to notice how WordPress handles file uploads.

By default, the process is painfully synchronous. You upload a file. The server processes it, generates 5-7 different thumbnail sizes, and then (if you're using an offload plugin) pushes every single one of those files to the cloud over an external HTTP request.

If you do this synchronously, the main PHP thread stays blocked the entire time. The WordPress dashboard hangs. If you try to bulk-upload a gallery, PHP hits its max_execution_time limit, and your server throws a 504 Gateway Timeout.

To fix this, we completely decoupled the upload process.

Instead of pushing to the cloud immediately, CloudSync Master queues the job. It uses background scheduled tasks (cron) to validate and push items asynchronously. You can drop 500 images into the media library, close the browser tab, and go get coffee.

Giving Users Control Under the Hood

We learned quickly that async "black boxes" frustrate users. If something fails, you need to know what and why. So we built a real-time queue dashboard into the plugin. If a file fails because of a network blip or a provider timeout, you click retry on that item. No restarting the whole batch.

We also introduced a Concurrency slider.

By default, the plugin processes 5 items simultaneously.
If you're on a capable server and need to move a massive library fast, you can crank the concurrency up to 20 parallel uploads.

This keeps bulk uploads from overwhelming cheap shared hosting while letting capable servers push files as fast as they can.

Step 5: Killing the Configuration Headache (OAuth vs. JSON Keys)

One more thing was bugging us: the setup experience.

Most WordPress media offload plugins require you to go into AWS IAM or the Google Cloud console, create a service account, assign bucket policies, download a JSON credentials file, and carefully paste strings into WordPress. It takes 15 minutes, and if you miss a bracket in the IAM policy, nothing works.

We wanted connecting to Cloudflare R2 or Google Cloud Storage to take 10 seconds, not 10 minutes.

For Cloudflare R2, we built a Quick Setup flow (PRO only — someone had to write and debug all that token plumbing). You click a button, the plugin opens Cloudflare's token creation page with the right permissions pre-filled, you create the token and paste it back. Buckets auto-populate in a dropdown. Cloudflare doesn't offer OAuth like Google does, but this is as close to one-click as their platform allows.

For Google Cloud, we registered an OAuth app and integrated it into the PRO version — that part alone took more work than you'd expect. But now you just click "Sign in with Google", authorize, and your buckets appear. No creating service accounts, no navigating the IAM console (which feels like it requires a PhD), no downloading JSON key files.

No copy-pasting IAM policies. No credential files floating around. We still support manual Access Keys for users who need that level of control, but most people pick the quick flow and move on. I don't like clicking through 15 setup screens either -- that was the whole point.

Step 6: The WooCommerce Edge Case (Signed URLs)

WooCommerce support is a whole separate beast and deserves its own post, but one bug we hit is worth sharing here because it's a good architectural lesson.

When you need to serve private digital products, things get tricky. We ran into this integrating with WooCommerce digital downloads. Customers were buying products, but clicking the download link returned 403 Forbidden.

The Root Cause:
If you serve public assets, you typically map a custom domain to your bucket (e.g., cdn.yourstore.com -> public-bucket). But when you generate a temporary Signed URL to securely deliver a protected zip file, that file lives in a private bucket.

Our URL generation logic was accidentally bucket-agnostic. When it generated a Signed URL for a file in the private bucket, it was applying the custom domain from the public bucket. The request would hit the public proxy, looking for a private file, and fail.

The Fix: Bucket-Aware Domains
We had to rewire how our S3Credentials class handled routing. Instead of globally applying a custom domain, we implemented strict bucket-aware custom domains.

Now, when WooCommerce asks the plugin for a secure download link, the system checks:

Is this file in the primary public bucket? If yes, apply the custom domain.
Is this file in a private bucket? If yes, bypass the custom domain completely and fall back to the provider's direct API endpoint (like the Cloudflare R2 API) to generate a valid, cryptographically signed URL.

A small routing change, but it's the difference between a working checkout and customers filing support tickets.

Wrapping Up

We started this project to run WordPress on Google Cloud Run. We ended up rethinking how offload plugins should be built.

If you're pushing WordPress into serverless or containerized hosting, plugin size matters more than most people think. The vendor SDKs are convenient, but they come with real costs: cold-start latency, deployment bloat, and thousands of extra files in your attack surface.

What worked for us:

Skip the SDKs. Direct REST API calls with Guzzle handle everything an offload plugin needs to do, at a fraction of the size (67MB down to 2.5MB).
Queue everything. Background cron keeps uploads from blocking the WordPress admin thread.
Make setup fast. If connecting a cloud provider takes 15 minutes, something is wrong.

If you're dealing with plugin bloat or looking for a lightweight WP Offload Media alternative, CloudSync Master is free on WordPress.org. Full setup guides and WP-CLI reference are in the documentation.

Happy to answer questions about the architecture, serverless WordPress, or cloud provider migration in the comments.

AI E-Mail Event Booking Agent

Dmitry Rechkin — Sun, 01 Sep 2024 04:57:23 +0000

This is a submission for the Nylas Challenge: AI Expedition.

What I Built and Why

As a member of the strata council, I regularly handle reservations for the amenity room. While the current volume of bookings isn’t overwhelming, it does come with its own set of challenges—negotiating time slots, enforcing reservation rules, ensuring the completion of PDF forms, verifying them, and then manually booking the room.

With more residents moving into our building, I began to think about automating this process. However, communicating new methods, such as using specific URLs for reservations, might not work for everyone. That's when the idea of building an AI agent to manage reservations started taking shape in my mind. The Nylas challenge was the final push I needed to put aside other projects and dive into this one.

Nylas offers the exact tools I was looking for, so I decided to create something practical that we can actually use in our building.

Demo

Driven by the motto “go PRO or go home,” I might have gone a bit overboard with the video. The real action starts at the 2:30 mark and lasts about 2 minutes.

youtube.com

Code

The source code for the AI email event booking agent can be found on

dmitryrechkin / ai-email-event-booking-agent

AI Email Event Booking Agent

This project implements an AI-powered Email Event Booking Agent designed to automate the process of handling incoming event booking requests via email. The agent intelligently processes emails, validates the information provided, requests additional details if necessary, checks calendar availability, fills out PDF forms, and books events.

This solution is optimized to run on serverless Cloudflare Workers, aiming to minimize external dependencies for enhanced speed and efficiency. Many packages have been custom-written to support this goal, ensuring that the solution remains lightweight and fast.

Key Features

Serverless Architecture: Runs on Cloudflare Workers, leveraging Cloudflare KV for storage.
Nylas API Integration: Handles incoming emails via the Nylas API, transforming them into a common format for AI processing.
Dynamic AI Agent: Utilizes AI to decide which tools to use based on natural language instructions and a customizable JSON schema.
Minimal Dependencies: Custom code replaces…

View on GitHub

Your Journey

I'm a huge fan of serverless technology, particularly Cloudflare Workers.

Initially, I planned to take advantage of the Nylas SDK. However, I quickly ran into issues because it wasn’t particularly compatible with Cloudflare Workers.

No big deal, I figured. Nylas has well-documented APIs, which are explained in detail here.

The challenge was understanding which combination of APIs would best suit my needs.

At first, I decided to use the Create Events API and the Send Message API.

Then, I discovered the Nylas Scheduler API, which seemed perfect for my AI Event Booking Agent. You can learn more about it here.

However, I quickly realized that the requirements to create a configuration object, followed by a session, might be too complex for an AI to handle. So, I reverted to my original plan of using the Email, Calendar, and Event APIs separately.

Although the webhook provides a snippet of the email, I realized that the body of the email is often in HTML and can contain previous messages embedded within it. This could potentially confuse the AI agent, so I embarked on a journey to find a library that could extract just the latest email body as text, making it easier to feed to the LLM.

After much searching, I found that nothing worked as expected or required Node.js. So, I implemented my own solution, which turned out to be pretty decent and will likely be used in future projects: text-email-body-parser.

One of the requirements was to be able to read and fill PDF forms. While this is relatively easy with existing libraries, I needed a set of shortcut classes capable of reading and filling PDF files represented as byte arrays since working with files was out of the question in this case.

During the process of implementing my abstraction layer on top of the Nylas API, which could be used in a Node.js-less environment, I created two helper packages: calendar-nylas and message-nylas. These packages enable the AI Event Booking Agent to perform the necessary tasks for booking events and sending emails.

As I researched the best way to implement the agent, I chose Vercel’s AI SDK (AI SDK Core) because it provides a streamlined method for automating tool calls. This allows me to focus on creating tools and refining prompts instead of worrying about the mechanics.

To make my code easily adaptable for tool use, I created a tiny library, foundation-core, which lets me create actions in a predictable way and use them as tools with automatic input and output validation using Zod.

Next, I wanted to define a schema for the data to collect, so I could efficiently extract it with AI and then pass it to my tool. While Zod is amazing for this, I couldn't find a pre-existing solution that allowed dynamic schema definition without generating static code.

This led to the creation of json-schema-to-zod, which I can use to store data structures as JSON schemas in KV storage and dynamically convert them to Zod schemas for use with AI tools.

Finally, it was just a matter of putting everything together. I’ve described the architecture in the repository, so I won’t go into it again here.

Conclusion

This project was an exciting journey into the world of AI-driven automation. The combination of Nylas, Cloudflare Workers, and Vercel’s AI SDK allowed me to build a practical solution that I can use in my own building. It’s fascinating to see how AI can manage something as complex as event bookings, complete with all the quirks and challenges of real-world scenarios.

While there were a few hurdles along the way, like adapting the Nylas API for Cloudflare Workers and dealing with the intricacies of parsing email bodies, these challenges ultimately led to the creation of several reusable libraries that I’m sure will be beneficial in future projects.

In the end, the AI Event Booking Agent not only simplifies the reservation process but also opens the door to more sophisticated AI-driven workflows. I’m excited to see how this project evolves and how AI can further enhance everyday tasks in our work and life.

DEV Community: Dmitry Rechkin

Configuring WooCommerce Shipping From the Terminal: WP-CLI + Claude Code Skills

One prerequisite, said plainly

The command shape

Start with status and validate

Reading and writing settings

Proving rates actually come back

How do I fix "no shipping options at checkout"?

Sizing boxes to what you actually ship

Tuning rates: markup, floors, and which services show

The PRO half: labels, tracking, manifests

Handing it to Claude Code

Which carriers does this work with?

Trade-offs: what this doesn't do

Why bother, if a settings screen works?

Try it

Further reading

I Stopped Clicking Around wp-admin and Treated WordPress Media Offload Like Infrastructure

I Stopped Clicking Around wp-admin and Treated WordPress Media Offload Like Infrastructure

TL;DR

The thing that kept bugging me

Why media offload becomes an infrastructure concern

Where AI actually fits

What was verified locally

A practical R2 workflow

1. Add and activate the R2 account

2. Test it before you do anything expensive

3. Apply baseline settings

4. Sync existing media

5. Stop and look at the system

Migration is where people get nervous

Current provider support note

The hardening step people skip

A few mistakes I keep seeing

Treating prompts as process

Rolling out to production first

Hiding uncertainty

Leaving rollback vague

A simple evaluation checklist

Further reading

The 67MB Problem: Building a Lightweight WordPress Media Offload Alternative

The Problem

Step 1: Discovering SDK Bloat

Step 2: Dropping the SDK Entirely

Step 3: Engineering CloudSync Master

Step 4: The Sync Bottleneck (Why Background Queues Matter)

Giving Users Control Under the Hood

Step 5: Killing the Configuration Headache (OAuth vs. JSON Keys)

Step 6: The WooCommerce Edge Case (Signed URLs)

Wrapping Up

AI E-Mail Event Booking Agent

What I Built and Why

Demo

Code

dmitryrechkin / ai-email-event-booking-agent

AI Email Event Booking Agent

Key Features

Your Journey

Conclusion