Built to be scripted, and to behave predictably.
Offloft has WP-CLI commands for every task (wp offloft status, scan, offload, verify, resync, restore, exclude, include, issues, fix, job, test-connection) and a REST API under the offloft/v1 namespace. Normal offloading doesn't change your database, and every file's state is tracked and queryable.
WP-CLI
Every command below comes straight from the plugin's own command list. Run wp help offloft for each command's options.
| Command | What it does |
|---|---|
wp offloft status | Show how your media is doing. |
wp offloft scan | Scan the media library before offloading. Nothing is uploaded. |
wp offloft offload | Upload media items to your storage and check each copy. |
wp offloft verify | Check that cloud copies are there and complete (no download). |
wp offloft resync | Sync media items again now. |
wp offloft restore | Bring files missing from your server back from the cloud. |
wp offloft exclude | Keep media items on your server: they are no longer offloaded. |
wp offloft include | Offload excluded media items again (the upload runs in the background). |
wp offloft issues | List issues: what went wrong, what it affects, and what fixes it. |
wp offloft fix | Fix issues: one, every one of a kind, or all Offloft can fix. |
wp offloft run | Process the background tasks that are due now (uploads, checks, retries). |
wp offloft test-connection | Test the connection to your storage. |
wp offloft complete-setup | Finish setup without the wizard, for a connection set in wp-config.php or by script. |
wp offloft system-info | Show system information for a support request. Keys are masked. |
wp offloft job list | List running jobs and the last 20 finished ones. |
wp offloft job pause | Pause a job after the media item in hand. |
wp offloft job resume | Resume a paused job where it stopped (in the background). |
wp offloft job cancel | Cancel a job after the media item in hand. What is done stays done. |
REST API
Routes live under offloft/v1. Authenticate the WordPress way: cookies with a nonce, or application passwords. Every route needs the capability to manage Offloft, and no answer contains a secret key, signature or presigned URL.
Lists answer {items, total, page, per_page} and also send X-WP-Total and X-WP-TotalPages. Errors are WP_Errors with a plain-language message and an offloft_* code.
| Route | Methods |
|---|---|
/offloft/v1/activity | GET |
/offloft/v1/files | GET |
/offloft/v1/files/actions | POST |
/offloft/v1/files/{id} | GET |
/offloft/v1/issues | GET |
/offloft/v1/issues/groups | GET |
/offloft/v1/issues/groups/{type}/fix | POST |
/offloft/v1/issues/{id}/fix | POST |
/offloft/v1/issues/{id}/ignore | POST |
/offloft/v1/issues/{id}/unignore | POST |
/offloft/v1/jobs | GET, POST |
/offloft/v1/jobs/{id} | GET |
/offloft/v1/jobs/{id}/{command} | POST |
/offloft/v1/profiles | POST |
/offloft/v1/profiles/active | GET |
/offloft/v1/profiles/buckets | POST |
/offloft/v1/profiles/buckets/create | POST |
/offloft/v1/profiles/test | POST |
/offloft/v1/profiles/{id}/delivery-test | POST |
/offloft/v1/profiles/{id}/test | POST |
/offloft/v1/providers | GET |
/offloft/v1/providers/{id}/guide | GET |
/offloft/v1/queue/run | POST |
/offloft/v1/scan | GET, POST |
/offloft/v1/settings | GET, PUT |
/offloft/v1/settings/debug-log | GET, DELETE |
/offloft/v1/settings/environment | GET |
/offloft/v1/settings/export | GET |
/offloft/v1/settings/import | POST |
/offloft/v1/settings/key-preview | GET |
/offloft/v1/setup/complete | POST |
/offloft/v1/setup/progress | GET, PUT |
/offloft/v1/status | GET |
/offloft/v1/system-info | GET |
/offloft/v1/url-replace | GET |
/offloft/v1/url-replace/preview | POST |
/offloft/v1/url-replace/run | POST |
/offloft/v1/url-replace/undo | POST |
How are URLs served?
Offloft changes media URLs as a page is built. There is no search-and-replace, so your database keeps its original addresses and turning Offloft off takes effect at once.
A page cache stores the page with its cloud addresses in it. After you turn offloading on or off, clear your page cache so saved pages pick up the change.
File states
These are the exact values the API returns. Only verified and local_removed files may be served from the cloud.
| State | Meaning |
|---|---|
pending | Waiting to be uploaded. Your site serves the local file. |
uploading | Being sent to your bucket. Your site serves the local file. |
uploaded | Sent, and waiting for its check. Your site serves the local file. |
verified | Checked in your bucket. Your site may serve the cloud copy. |
failed | The upload or check didn't succeed. Your site serves the local file. |
missing_local | The file isn't on your server. |
missing_cloud | The file isn't in your bucket, or doesn't match what was sent. |
local_removed | Verified in your bucket, with the local copy removed by Pro. Your site serves the cloud copy. |
excluded | You chose to keep this file on your server, so it is not offloaded. |
deleting | Its media item was deleted in WordPress, and its cloud copy is being removed. |
Requirements and compatibility
PHP 8.1 or later with the cURL extension, and WordPress 6.5 or later. Tested up to WordPress 7.1. Multisite hasn't been tested yet, so please test on a copy first.
Source
Offloft is licensed under GPL-2.0-or-later. The free plugin's code, with its source, is in the download zip.
Your media, in your bucket, checked.
Install Offloft free. Setup takes five steps, and nothing moves until the connection test passes.