Specification — WP-CLI Command wp media find-orphans
- Context
WP-CLI already provides a wp media command dedicated to WordPress media. Existing subcommands notably allow users to import files as attachments, regenerate thumbnails, and list registered image sizes.
The proposed command fits as a new subcommand of wp media:
wp media find-orphans
It must not replace existing commands such as:
wp media import
wp media regenerate
wp media image-size
Its role is to find orphaned media-related files and records by comparing the WordPress media library, the physical files in the uploads directory, and the actual usage of media in site content.
- Objective
Create a WP-CLI subcommand that find orphaned media in a WordPress installation.
The command should identify media assets that appear to be unused, unreferenced, incomplete, or inconsistent, including:
- files present on disk but absent from the WordPress media library;
- attachment records in the database whose original file is missing from disk;
- generated thumbnails whose parent attachment is missing;
- media library attachments that are not attached to any post;
- media files not referenced in post content, excerpts, custom fields, or featured images;
- media URLs referenced in content but missing from disk;
- duplicate or stale files that no longer correspond to current attachment metadata.
The command is non-destructive by default. It must only report finded orphan candidates unless an explicit cleanup option is implemented separately.
- Command Name
wp media find-orphans
- Use Cases
5.1 Find all orphan media candidates
wp media find-orphans
Runs a full search process and outputs all orphan media candidates found across the media library, database metadata, and uploads directory.
5.2 Find files present on disk but missing from the media library
wp media find-orphans --type=filesystem
Reports files found in the uploads directory that do not correspond to any registered WordPress attachment.
5.3 Find database attachments missing their physical file
wp media find-orphans --type=database
Reports media attachments registered in WordPress whose original file cannot be found on disk.
5.4 Find unused media based on content references
wp media find-orphans --type=usage
Reports media attachments that do not appear to be referenced in post content, excerpts, featured images, or configured metadata fields.
5.5 Output results in machine-readable format
wp media find-orphans --format=json
Outputs the search report in JSON format for use in scripts, CI/CD pipelines, or automated QA workflows.
- Expected Behavior
By default, the command should:
- scan the WordPress media library attachments;
- scan the physical files in the wp-content/uploads directory;
- compare attachment metadata with actual files on disk;
- inspect content references where relevant;
- classify found orphan candidates by type;
- output a readable report;
- exit with a status code suitable for automation.
The command must not delete, move, or modify files unless a separate explicit destructive option is added later.
- Suggested Options
wp media find-orphans [--type=<type>] [--format=<format>] [--path=<uploads-path>] [--include-thumbnails] [--limit=<number>]
Suggested options:
- --type=: restrict search to a specific orphan type. Possible values: filesystem, database, usage, thumbnails.
- --format=: output format. Possible values: table, json, csv, yaml, ids.
- --path=: custom uploads directory path.
- --include-thumbnails: include generated thumbnails in filesystem checks.
- --limit=: limit the number of reported results.
- Example Output
+------------+----------------------+------------------------------------------+-------------------------------+
| Type | Attachment ID / File | Issue | Path |
+------------+----------------------+------------------------------------------+-------------------------------+
| filesystem | image-old.jpg | File exists on disk but not in library | uploads/2023/04/image-old.jpg |
| database | 1542 | Attachment file missing from disk | uploads/2022/11/banner.jpg |
| usage | 2189 | Attachment appears unused in content | uploads/2021/08/photo.jpg |
+------------+----------------------+------------------------------------------+-------------------------------+
- Non-goals
The command should not:
- automatically delete orphaned files;
- replace wp media regenerate;
- replace wp media import;
- optimize or compress media files;
- rewrite content URLs;
- repair metadata automatically;
- guarantee with absolute certainty that a media file is unused.
Orphan search should be treated as a candidate identification process, because media can be referenced by themes, plugins, page builders, external systems, hardcoded templates, or serialized/custom data.
- Safety Considerations
Because finding unused media can produce false positives, the command should be conservative by default.
Any future cleanup feature should require explicit confirmation and should ideally be implemented as a separate command or option, such as:
wp media delete-orphans --dry-run
or:
wp media find-orphans --delete --dry-run
Searching and deletion should remain clearly separated to avoid accidental data loss.
bash wp media find-orphans
It must not replace existing commands such as:
wp media import
wp media regenerate
wp media image-size
Its role is to provide a quality and consistency list around the media library, the physical files in the uploads directory, WordPress metadata, and editorial usage of media.
Specification — WP-CLI Command wp media find-orphans
WP-CLI already provides a wp media command dedicated to WordPress media. Existing subcommands notably allow users to import files as attachments, regenerate thumbnails, and list registered image sizes.
The proposed command fits as a new subcommand of wp media:
wp media find-orphansIt must not replace existing commands such as:
Its role is to find orphaned media-related files and records by comparing the WordPress media library, the physical files in the uploads directory, and the actual usage of media in site content.
Create a WP-CLI subcommand that find orphaned media in a WordPress installation.
The command should identify media assets that appear to be unused, unreferenced, incomplete, or inconsistent, including:
The command is non-destructive by default. It must only report finded orphan candidates unless an explicit cleanup option is implemented separately.
wp media find-orphans5.1 Find all orphan media candidates
wp media find-orphansRuns a full search process and outputs all orphan media candidates found across the media library, database metadata, and uploads directory.
5.2 Find files present on disk but missing from the media library
wp media find-orphans --type=filesystemReports files found in the uploads directory that do not correspond to any registered WordPress attachment.
5.3 Find database attachments missing their physical file
wp media find-orphans --type=databaseReports media attachments registered in WordPress whose original file cannot be found on disk.
5.4 Find unused media based on content references
wp media find-orphans --type=usageReports media attachments that do not appear to be referenced in post content, excerpts, featured images, or configured metadata fields.
5.5 Output results in machine-readable format
wp media find-orphans --format=jsonOutputs the search report in JSON format for use in scripts, CI/CD pipelines, or automated QA workflows.
By default, the command should:
The command must not delete, move, or modify files unless a separate explicit destructive option is added later.
wp media find-orphans [--type=<type>] [--format=<format>] [--path=<uploads-path>] [--include-thumbnails] [--limit=<number>]Suggested options:
+------------+----------------------+------------------------------------------+-------------------------------+
| Type | Attachment ID / File | Issue | Path |
+------------+----------------------+------------------------------------------+-------------------------------+
| filesystem | image-old.jpg | File exists on disk but not in library | uploads/2023/04/image-old.jpg |
| database | 1542 | Attachment file missing from disk | uploads/2022/11/banner.jpg |
| usage | 2189 | Attachment appears unused in content | uploads/2021/08/photo.jpg |
+------------+----------------------+------------------------------------------+-------------------------------+
The command should not:
Orphan search should be treated as a candidate identification process, because media can be referenced by themes, plugins, page builders, external systems, hardcoded templates, or serialized/custom data.
Because finding unused media can produce false positives, the command should be conservative by default.
Any future cleanup feature should require explicit confirmation and should ideally be implemented as a separate command or option, such as:
wp media delete-orphans --dry-runor:
wp media find-orphans --delete --dry-runSearching and deletion should remain clearly separated to avoid accidental data loss.
bash wp media find-orphansIt must not replace existing commands such as:
Its role is to provide a quality and consistency list around the media library, the physical files in the uploads directory, WordPress metadata, and editorial usage of media.