Managing WordPress media with WP-CLI

Why the media library leaves the admin screen

Media-heavy sites outgrow the admin screen quickly: a gallery site with a hundred thousand attachments makes the grid hang, and bulk regeneration times out in the browser. WP-CLI brings the media library back under control because it runs server-side with no page limit.

The relevant commands are grouped in wp media and a few in wp post:

wp media list --post_type=attachment --format=table
wp media regenerate --yes
wp media import /local/path --post_id=123

Audit first

Before changing anything, list the state:

wp media list --fields=ID,title,filesize,url --format=csv

This reads the attachment post rows and reports the metadata (sizes, dimensions) rather than only the filename. Use it to find patterns that the admin hides:

• Orphaned rows: attachments whose file is gone from disk (a broken import) but the row remains.
• Duplicate files: identical file names across posts, usually the outcome of "save as copy".
• Oversized originals: files far above the largest thumb size, useful context for image optimisation.

Regenerate thumbnails

When a theme changes its registered image sizes, every existing attachment needs new thumbnails:

wp media regenerate --post-filter='ID=12,34,56'

• Run it on an <12,34,56> set first, not the whole library.
• It re-creates the sizes registered by add_image_size, not the original.
• The dry check is simple: wp media list before, then compare the size metadata after.

Regenerating on a real production library with the permissions wrong can churn disk and slow the site. The safe path is staging first, and a kill switch is available in the command itself with --all=false followed by a fixed set.

Clean old sizes

WordPress keeps every intermediate size as a file. When a theme deregisters a size, the old files stay:

wp media regenerate --only-missing --yes

--only-missing regenerates only something that is missing, which is how you add the absent new sizes without touching the churn of the whole library. To physically delete stale intermediate sizes, delete orphaned sizes with a tool that runs a query, after verifying the lookup against the attachment metadata.

The import and the task order

Bringing in many files:

wp media import ./photos/*.jpg --post_id=5

wp media import runs the same pipeline as the admin upload (generates sizes, creates attachments), so it respects WordPress hooks and filters. The practical batch order for a large import:

1. Copy or mount the files to a local temp dir.
2. wp media import with --post_id if all go to one post, else loop per post.
3. Regenerate the sizes your theme needs.
4. Verify with wp media list that filesize and formats look right.

Cleanup guardrails

The whole media-command suite has the same safety profile as bulk content edits:

• Back up the database first; the attachment post rows and metadata are the recoverable part.
• Files are not deleted by default. Deleting attachment posts orphans the files on disk, which is a separate wp media delete or a cleanup that respects the disk layout.
• Smoke tests: run a one-item regenerate, verify the new size exists on the theme side, and only then scale.

The result of a well-run media pipeline is a library whose disk usage matches the content and whose sizes match the theme. When the library has grown beyond reason, the media upload guide covers the growth itself, and the image plugin one keeps the file sizes honest.