Usage

Day-to-day operation: Media → WP to S3, Test/Save, live offload, Media Library tools, and WP-CLI.

Admin screen

Open Media → WP to S3. Tabs:

Tab	Purpose
Settings	Connection, enable switch, CDN/base URL, delete-local, concurrency, etc.
Migrate	Background bulk upload of existing local files
Tools	Full doctor dump, optional historic content URL rewrite

Default capability: manage_options (Administrators). Override with:

define('WP_TO_S3_CAPABILITY', 'edit_posts'); // e.g. Editors

Choose a provider preset (Amazon S3, R2, MinIO, Spaces, Linode, or Custom) to fill endpoint/region/path-style hints.
Enter bucket, access key, and secret key (and adjust endpoint/region as needed).
Leave Delete local after upload unchecked until you trust the setup.
Click Test next to Save Changes.

Test runs a fast probe against the configured bucket:

PUT a tiny object wp-to-s3-connection-test/wp-to-s3.txt (body Hello, world!, under your key prefix if set)
GET and verify the body
DELETE the object

Failures list the method, HTTP status (when available), and error message.

Changing connection fields (provider, endpoint, region, bucket, prefix, keys, path-style, object ACL) locks Save until Test passes for those values.
Non-connection options (CDN URL, concurrency, delete-local, redirects, content rewrite) can be saved without re-testing.
Unchecking Enabled always allows Save (escape hatch).
A successful test fingerprint is kept in the browser tab (sessionStorage).

After a green Test, click Save Changes.
Check Enable and save again (or enable before testing if connection fields are already verified).

Prefer secrets in wp-config.php / environment variables for production. See Configuration.

When Enabled is on and configuration is complete:

New Media Library uploads are pushed to the bucket (PHP AWS SDK).
Attachment metadata (_wp_attached_file) stays WordPress-native.
Object keys match paths relative to the uploads directory, plus optional prefix.
If Delete local after upload is off (default), a local copy remains; same-host URLs serve local first.
If delete-local is on, missing locals are streamed from S3 (X-WP-To-S3: 1 on the response).

New sites never need Migrate if all media is uploaded after enable. See New WordPress site.

Feature	What it does
List column S3 status	Offloaded / local only / dual / missing remote
Attachment metabox	Push to S3; delete local when remote OK
Bulk actions	Push selected; delete local when remote OK

These use the upload_files capability (anyone who can upload media).

For sites that already have files under wp-content/uploads, use the existing site guide.

Quick reference:

Admin: Media → WP to S3 → Migrate → Start (optional path filter, sequential mode).
CLI: wp s3 migrate --resume (uses s5cmd when available).

Live offload stays available while migrate runs — there is no migrate-only mode.

Default: keep /wp-content/uploads/... on your domain.
Optional: set Public base URL to rewrite attachment URLs to a CDN or public bucket host.

See WP-CLI reference for doctor, migrate, and verify.

wp s3 doctor
wp s3 migrate --dry-run
wp s3 migrate --resume
wp s3 verify --sample=100