Media Library

Manage attachments already in the WordPress Media Library, built on core attachment functions (wp_get_attachment_metadata, wp_update_post, wp_delete_attachment, …). To pull an external image into the library, use sideload-image; to search existing uploads use list-media.

get-media, update-media, and upload-media are enabled by default. delete-media ships disabled-by-default. Their switches are in the Stock & Media Images section of the WordPress tab on EMCP Tools → Tools. A fifth tool, resize-media, comes with the Image Optimization module.

emcp-tools/upload-media

New in v3.12.1. Uploads a file’s bytes straight from the client machine into the Media Library, the companion to sideload-image (which only fetches a URL the server can already reach). This is how an agent adds an image from your own computer.

Input: filename and data (both required): data is base64, an optional data:<mime>;base64, prefix is stripped automatically. filename must include a real extension. Optional: alt, title, caption, description, post_id (attaches to a post), convert_webp (default true; set false to skip optimization for this upload).

Returns: { id, title, url, mime_type, filesize, alt, width, height }.

Only WordPress-allowed file types are accepted, executable types are refused. Capped at 32 MB decoded (filterable via emcp_tools_upload_media_max_bytes). Runs through the same optimize/WebP pipeline as the other media tools.

Capability: upload_files.

emcp-tools/get-media

Full detail for one attachment: every registered image size (URL + dimensions), mime type, filesize, alt text, caption, description, and the raw attachment metadata.

Input: attachment_id.

Returns: { id, title, url, mime_type, filesize, alt, caption, description, sizes: { ... }, metadata: { ... } }.

Capability: edit_posts. Read-only.

emcp-tools/update-media

Edits an attachment’s title, alt text, caption, and/or description. Only the fields you pass change, a one-call accessibility/SEO fix for library images.

Input: attachment_id plus any of title, alt, caption, description.

Returns: { id, updated: [...] }.

Capability: edit_post on the attachment.

emcp-tools/delete-media

Deletes an attachment. Destructive and effectively permanent: WordPress bypasses Trash for media unless the MEDIA_TRASH constant is defined, so on most sites the file and its database record are gone for good.

A three-way gate protects this tool:

1. It is disabled-by-default. An admin must switch it on in EMCP Tools → Tools (the Stock & Media Images section of the WordPress tab) and save.
2. The caller needs delete_post on the attachment.
3. The input must include an explicit confirm: true.

Pass force: true to skip Trash even when MEDIA_TRASH is on.

Input: attachment_id, confirm (must be true), force (optional).

Returns: { id, deleted: true, forced }.

Capability: delete_post on the attachment. Destructive.

emcp-tools/resize-media

Resizes an existing Media Library image in place: the attachment ID and its URLs stay the same. It scales to fit the given width and/or height and keeps the aspect ratio; pass crop: true to hard-crop to exactly width × height. The original is backed up first, so the change can be reversed, and every sub-size (plus WebP) is regenerated. JPEG, PNG, WebP and GIF.

Input: attachment_id (required), width, height, crop (needs both width and height).

This tool registers only while the Image Optimization module is on. The module is off by default: switch it on in EMCP Tools → Modules (the Content & design group), then choose Save modules in the save bar. Its switch then appears in the Image Optimization section of the EMCP Modules tab on EMCP Tools → Tools. If the module’s “Largest side” setting is smaller than your target, that cap applies. See Image Optimization.

Capability: edit_post on the attachment.