---
title: "WP-CLI Commands"
url: "https://dudlewebs.com/guideline/media-cloud-sync/developers/wp-cli-commands/"
markdown_url: "https://dudlewebs.com/guideline/media-cloud-sync/developers/wp-cli-commands.md"
type: "Docs"
language: "en-US"
date_published: "2026-11-08T11:25:25+00:00"
date_modified: "2026-11-09T17:36:34+00:00"
---

# 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:

```bash
wp mcs jobs
```

| Job | What it does |
| --- | --- |
| `sync_to_cloud` | Uploads media that isn’t in the cloud yet. |
| `restore_to_server` `PRO` | Downloads cloud copies back to the server. |
| `move_to_new_path` `PRO` | Moves synced media to the path set in Settings. |
| `bucket_to_bucket` `PRO` | Copies synced media to the configured destination bucket. |
| `remove_from_cloud` `PRO` | Deletes cloud copies, optionally restoring them first. |
| `remove_from_server` `PRO` | Deletes local copies of synced media. |
| `import_from_offload` `PRO` | Imports records from other offload plugins. |
| `import_from_bucket` `PRO` | Creates records for files already in the bucket. |
| `repair_synced_media` `PRO` | Uploads files missing from the bucket. |
| `update_file_headers` `PRO` | Applies Cache-Control and content type to files in the bucket. |
| `change_storage_class` `PRO` | Moves media to another storage class. |
| `clean_unused_files` `PRO` | Lists, or deletes, files no synced media uses. |
| `export_media_inventory` `PRO` | Writes the media inventory CSV. |

## Commands

### `wp mcs status`

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

```bash
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.

```bash
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`.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

[← Previous Helper API and Data Model](https://dudlewebs.com/guideline/media-cloud-sync/developers/helper-api-and-data-model/) [Back to All Media Cloud Sync guides →](https://dudlewebs.com/guideline/media-cloud-sync/)

Still need help?

[Chat with us Quick questions, answered live](https://dudlewebs.com/contact/) [Contact us Sales, partnerships or anything else](https://dudlewebs.com/contact/) [Create a ticket Technical issues with your site](https://dudlewebs.com/submit-ticket/)
