WP-CLI overview

Every bulk job in OmniOffloader can also run from the terminal with WP-CLI. The admin screens and the terminal do the same work and follow the same settings.

Command	What it does
wp omnioffloader offload	Upload media to cloud storage.
wp omnioffloader restore	Bring Back: download offloaded media to the server again.
wp omnioffloader retention	Apply a retention policy to media that is already offloaded.
wp omnioffloader status	Show the provider, connection, Safe mode, media counts and running jobs.

The same reference, with copy buttons, is on the OmniOffloader → Tools screen.

When to use WP-CLI

• Large libraries. A terminal command is not limited by the browser or by short web request time limits. On libraries of 5,000 items or more, the Bulk Offload and Bring Back screens suggest the matching command.
• SSH access. You can run a job on the server directly and watch a progress bar.
• Scheduled work. Use --limit with a cron job to work through a big library in small chunks, for example 500 attachments each night.
• Hosts that time out. Some hosts stop long admin requests or block WordPress’s internal background requests. WP-CLI does not depend on them.

Running the commands

Run the commands from your WordPress folder:

cd /path/to/wordpress
wp omnioffloader status

Or add --path from anywhere:

wp omnioffloader status --path=/path/to/wordpress

Shared behaviour

Try it first with --dry-run

Every command that changes something supports --dry-run. It lists what would happen and changes nothing: no uploads, downloads or deletes.

wp omnioffloader offload --all --dry-run
wp omnioffloader restore --all --dry-run
wp omnioffloader retention --dry-run

Pick your media with --all, --ids and --limit

• --all selects every attachment the command can work on. (retention selects them by default and has no --all.)
• --ids=12,15,42 selects specific attachments. IDs that don’t fit (not an attachment, or already in the wanted state) are skipped, and the command lists them in a warning.
• --limit=<number> stops after that many attachments.

The commands check these values before they start:

• --limit must be a positive whole number. A typo such as --limit=5O is an error. It never means “the whole library”.
• --ids and --all can’t be used together.
• offload and restore need either --all or --ids.

Confirmations and --yes

Commands that delete files ask before they start:

• restore --delete-cloud asks before it deletes cloud copies.
• retention asks before it deletes local files.

Add --yes to skip the question, for example in a script.

One job at a time

Offload, Bring Back and retention jobs never run at the same time. They read and delete the same files, so the plugin allows one job at a time. This applies to jobs started from the admin screens, the Media Library and WP-CLI.

When another job is running, the command stops with a message like this:

Error: A bulk offload started from the admin screen is running. Wait for it to finish, cancel it there, or pass --force.

While a command runs, it holds a lock. The admin screens see the lock and will not start a second job. The lock is renewed after every attachment, and while a large file is still transferring. It is released when the command ends, also when you press Ctrl-C (when PHP’s pcntl extension is available, which is common for the command line).

If a command was killed in a way that left the lock behind (for example the server restarted), the lock expires within 10 minutes. Pass --force only if you are sure nothing else is running.

Caution

--force skips the one-job-at-a-time check. Two jobs working on the same files can fail each other’s uploads or downloads. Use it only when you know the other job is gone.

Safe mode

On a staging, development or local copy of your site, Safe mode is on. Then:

• offload refuses to run (except with --dry-run).
• restore refuses to run, unless Allow Bring Back on a copy (download only) is on in Settings. Even then, --delete-cloud is never allowed.
• status shows why Safe mode is on.

Transfer Speed

The commands follow the Transfer Speed setting, just like the admin screens. A faster setting moves more files at the same time inside the same PHP process. See Transfer Speed.

Stopping on repeated failures

offload and restore watch for failures in a row. After 10 failures in a row, they check the connection to your storage provider:

• If the provider does not answer, the command stops and shows the provider’s error.
• If the provider answers, the failures come from the attachments themselves (for example files missing on disk). The command keeps going and the errors stay in each attachment’s error log. It still stops after 100 failures in a row.

Attachments that failed in an earlier run are processed last, so a restart is not held up by the same broken files.

Exit codes

Code	Meaning
0	Success.
1	An error, or some attachments failed. status also returns 1 when no provider is configured or the bucket can’t be reached, so you can use it in monitoring.
130 / 143	The command was stopped with Ctrl-C (SIGINT) or SIGTERM, and its locks were released. Needs PHP’s pcntl extension.