Skip to content
Black Friday

20% off for every Pro licenses

BLACKFRIDAYClaim the Offer
Contact us

WP-CLI Commands

Media Cloud Sync registers a wp mcs command for running and monitoring its bulk jobs from the command line. This is the recommended way to process large libraries: jobs run in your terminal, with no browser tab, no dependence on WP-Cron, and no PHP time limit.

Available since version 1.5.0.

Jobs

Every bulk job on the site can be driven by name. List the ones available on your site with:

wp mcs jobs
JobWhat it does
sync_to_cloudUploads media that isn’t in the cloud yet.
restore_to_server PRODownloads cloud copies back to the server.
move_to_new_path PROMoves synced media to the path set in Settings.
bucket_to_bucket PROCopies synced media to the configured destination bucket.
remove_from_cloud PRODeletes cloud copies, optionally restoring them first.
remove_from_server PRODeletes local copies of synced media.
import_from_offload PROImports records from other offload plugins.
import_from_bucket PROCreates records for files already in the bucket.
repair_synced_media PROUploads files missing from the bucket.
update_file_headers PROApplies Cache-Control and content type to files in the bucket.
change_storage_class PROMoves media to another storage class.
clean_unused_files PROLists, or deletes, files no synced media uses.
export_media_inventory PROWrites the media inventory CSV.

Commands

wp mcs status

Shows media counts (total, synced, pending) and the state of every job.

wp mcs status
wp mcs status --format=json

wp mcs run <job>

Starts the job and processes it in the terminal, with a progress bar, until it finishes. If the job is already running or paused, it resumes it.

wp mcs run sync_to_cloud
wp mcs run sync_to_cloud --batch=25
  • --batch=<number>: items processed per step (default 10).
  • --yes: skip the confirmation prompt that jobs which delete files show first.
  • --<field>=<value>: a job option from the job’s confirmation dialog, for example --restore=false. Options you leave out use their default.

Press Ctrl+C to pause the job, and run the same command again to resume. This needs PHP’s pcntl extension; without it, Ctrl+C leaves the job running in the background through WP-Cron. The command tells you which applies when it starts.

When the job finishes with failed items, the command says how many and points you to wp mcs errors.

wp mcs start <job>

Starts the job in the background through WP-Cron, the same as the Start button in the admin, and returns immediately. Check progress with wp mcs status.

wp mcs start sync_to_cloud

Accepts the same --yes and --<field>=<value> options as run.

wp mcs pause|resume|stop <job>

The same controls as the job screen in the admin.

wp mcs pause sync_to_cloud
wp mcs resume sync_to_cloud
wp mcs stop sync_to_cloud

wp mcs errors <job>

Lists the job’s failed items (the Errors table in the admin): media ID, source, time, last message and file.

wp mcs errors sync_to_cloud
wp mcs errors sync_to_cloud --retry
wp mcs errors sync_to_cloud --format=json

--retry retries every failed item and reports how many were fixed. --clear empties the job’s error log without retrying.

Media commands

wp mcs sync <id>...

Syncs specific attachments to the cloud now. --force re-uploads attachments that are already synced.

wp mcs sync 123 456
wp mcs sync 123 --force

wp mcs info <id>

Shows an attachment’s cloud record: provider, bucket, whether it’s private, the URL WordPress currently serves, and for every file (full size, original, each size, extra files, backup) whether it’s still on the server, plus its cloud key and URL.

wp mcs info 123
wp mcs info 123 --format=json

Additional per-media commands may appear here when other features are installed and active on the site; wp help mcs lists everything available.

Site commands

wp mcs check

Runs the storage and delivery status checks, the same as the refresh buttons in Settings. Exits with status 1 if a check fails, so it can be used in monitoring scripts. A site with no delivery provider chosen shows Delivery as “not set up”, which doesn’t count as a failure.

wp mcs counts [--refresh]

Shows media counts. --refresh recounts first, for when the dashboard numbers look out of date.

wp mcs reset-lock

Clears a stuck job lock so jobs can run again. Only use it when a job is genuinely stuck; it asks for confirmation (--yes skips it).

wp mcs config

Shows the connection: storage provider, where credentials come from, bucket, region, delivery provider, whether media delivery is on, the custom domain, and whether media is currently served from the cloud or the server. Access keys and secrets are never shown.

wp mcs settings get [<key>] / wp mcs settings set <key> <value>

Reads or changes plugin settings. set goes through the same validation as saving in the admin, so a change the admin would refuse is refused here too.

wp mcs settings get
wp mcs settings get rewrite_url
wp mcs settings set rewrite_url on

Values: on/off (or true/false, yes/no), numbers, or text.

Notes

  • Only one job runs at a time. If another job is running, run and start say so and exit.
  • Each job’s own rules still apply. For example, a job that removes local copies refuses to start unless media is being delivered from the cloud.
  • Run the commands as a user that can write to the uploads folder (usually the web server user), since jobs read and write media files.