Every command lives under wp legacy-redirector. For the full flag reference on any of
them, run wp help legacy-redirector <command> — this page covers the things wp help
cannot tell you: which command to reach for, and how to string them together.
| Command | What it does |
|---|---|
create |
Add a single redirect |
get |
Show a single redirect |
list |
List, filter, and export redirects |
update |
Change the destination and/or status of one or more redirects |
delete |
Delete one or more redirects |
enable / disable |
Start or stop serving one or more redirects |
validate |
Check redirects' stored details for problems, and record what is found |
test |
Check redirects live: whether the destination responds and the source redirects |
import |
Bulk import from a CSV file or STDIN |
import-from-meta |
Create redirects from a post meta field |
find-domains |
List the domains destinations point at |
migrate |
Bring 1.x redirect data up to the 2.0 storage format |
Every command that takes an existing redirect accepts either form and works out which it has been given, so you rarely need to look an ID up:
wp legacy-redirector get /old-page
wp legacy-redirector get 123update, delete, enable, disable, validate, and test take any number of them
in one call, mixing the two forms freely:
wp legacy-redirector disable /old-page 456 /another-old-pageAny redirect named that is not found, or cannot be acted on, gets a warning naming it, and
the command exits with status 1 once the rest are done; validate and test still print
what they found for the others. A single redirect that fails gets one error instead.
delete looks the redirects up before asking for confirmation, and names the redirect it
is about to delete when there is one.
The pre-2.0 wp wpcom-legacy-redirector namespace is still registered for the commands
that existed before 2.0, so existing scripts keep reaching them:
find-domainsandimport-from-metarun as before, with a deprecation warning naming thewp legacy-redirectorequivalent. The warning goes to STDERR, so--formatoutput piped through the old namespace stays clean on STDOUT. Note thatimport-from-metaflags are now kebab-case.insert-redirect,import-from-csv, andexport-to-csvwere removed in 2.0. Calling one fails with an error that names its replacement.
Commands added in 2.0, such as create and list, are only available under
wp legacy-redirector. The old namespace will be removed in a future major version.
Redirects created by 1.x will not fire under 2.0 until they have been migrated. This happens automatically in small batches on ordinary page loads (never on WP-CLI commands), but on a site with a large redirect set it is better to do it in one pass. Either form walks the entire redirect set, so on a site with millions of redirects expect the dry run to take minutes:
# See what will change, without writing anything.
wp legacy-redirector migrate --dry-run
# Do it.
wp legacy-redirector migrateOn a network, run it per site:
wp site list --field=url | xargs -I % wp --url=% legacy-redirector migrateWhile it runs, the command prints a progress line for each percent of the set it gets through, with the time elapsed and an estimate of the time left. If an earlier run was interrupted, it says so and carries on from where that run stopped.
At the end it reports how many redirects were changed, how many needed no change, how many were left alone because someone edited them after the upgrade began, and how many could not be written. It then breaks the changes down: published, source path rewritten, trashed as duplicates, destination made relative.
If any redirect could not be written, the command lists each one with the database's
reason and exits with an error. Those redirects are left exactly as they were, and are
remembered: once the cause is fixed, run wp legacy-redirector migrate again and it
retries just those, without walking the rest of the set again. That works even after the
migration has otherwise completed. A database error partway through, or an interrupted
run, is also safe to rerun: the command carries on from the batch it was working on.
Where two redirects end up with the same source but different destinations, for example
/old and /old/, only one can answer. The one already at that source stays live, and
the other is disabled rather than deleted, for you to decide. The run lists the first 20,
marks any that never fired under 1.x, and says how to settle each. To see every one,
whenever you like, list the duplicate sources:
wp legacy-redirector list --duplicates
wp legacy-redirector list --duplicates --format=csv > duplicates.csvEach row shows the disabled redirect, in the spelling 1.x stored, beside the live redirect
with the same source, both with their destinations. never_fired is yes where no browser
could ever have requested the disabled spelling, so disabling it changed nothing for
visitors. For each one, decide which destination is right:
# Keep the live redirect's destination
wp legacy-redirector delete <disabled ID>
# Keep the disabled one's destination
wp legacy-redirector update <live ID> --to=<destination>
wp legacy-redirector delete <disabled ID>Use the IDs: a source path the two share is refused, since it can't say which one you mean. A disabled duplicate can't be enabled or edited in place while the live redirect has its source. Once it's deleted or trashed, it drops off the list. The admin's Duplicate sources view on the Redirects screen shows the same list, with the same choices.
See UPGRADING.md for what each of those passes changes and why.
The CSV takes one redirect per row, with the source, the destination, and an optional status, in that order:
/old/legacy/path,/shiny/new/path
/another-legacy-path,https://other-domain.example.com/other-path
/a-third-path,123
/staged-for-later,/new-page,disabledThe destination can be a path, an absolute URL, or the ID of a post on this site. The
third column is optional and accepts enabled or disabled; omitted, new redirects are
created enabled. Any other value is an error for that row, so a typo cannot quietly put a
redirect live.
A first row that has a from or a to cell is a header instead, and the columns are found
by name rather than position: from and to are required, status is optional, and any
other column is ignored. That is the shape list --format=csv writes, so an export imports
back unedited whichever --fields it used, in any order (see
Export and back up). A header without from or without to stops
the import before any row is read, naming the missing column.
Preview first, then import. The preview validates each row as the import would, so a row the import will refuse is shown as an error rather than as one it would create:
wp legacy-redirector import redirects.csv --dry-run
wp legacy-redirector import redirects.csvWhere the export needs reshaping, transform it on the way in rather than writing an
intermediate file — - reads from STDIN:
# Old export is "id,source,target,notes"; we want columns 2 and 3.
cut -d, -f2,3 old-export.csv | wp legacy-redirector import -Re-running an import is safe. In the default create mode, a row whose source already has
a redirect with the same destination and status is skipped, so re-importing an unchanged
CSV changes nothing. A row whose source already redirects somewhere else, or with a
different status, is an error that suggests --mode=upsert, so a corrected CSV is never
silently left unapplied. Destinations are compared in their stored form, so
https://your-site.example/b and /b are the same destination. To make the CSV
authoritative instead — updating destinations that have changed and creating the rest —
use --mode=upsert:
wp legacy-redirector import redirects.csv --mode=upsertOnly errors are reported by default. Add --verbose to see every row.
A live import exits with status 1 if any row fails, after importing the rows that succeeded, and names how many failed; a clean run, including one where every row was skipped as unchanged, exits 0. A dry run fails only when every row fails.
find-domains lists what your destinations actually point at, which is the quickest way
to spot a domain you no longer own:
wp legacy-redirector find-domainslist --search matches source paths, not destinations, so repointing everything aimed at
one domain means exporting and filtering:
wp legacy-redirector list --limit=100000 --fields=ID,to --format=csv \
| grep 'old-brand\.example\.com' \
| cut -d, -f1 \
| xargs -r wp legacy-redirector update --to=/new-homeRemember that an external destination only works if its host is allowed via the
allowed_redirect_hosts filter. Creating or updating a redirect to a host the site does
not allow is an error naming the domain. See configuration.md.
For everything the plugin checks, and when and where, see
redirect-health.md. This section covers the command line, where two
commands do the checking: validate reads each redirect's stored details, and test tries
redirects live.
validate reports the redirects that no longer go anywhere: a destination post that has
since been deleted, trashed, or unpublished; a relative path whose post has gone the same
way; an external destination whose host is no longer in allowed_redirect_hosts; a row
whose stored data is corrupt. It also warns about possible loops (a destination that is
itself another redirect's source, with the hops leading back to where they started) and
about sources on a path WordPress itself serves, such as /wp-admin. create, update,
and import give the same warnings as they write.
With no redirects named, validate checks every redirect, enabled and disabled: the same
check the site runs in the background, run now. It requests nothing, so it is safe at any
size, and on a very large site it is the way to run a full check off-peak. It records what
it finds, so the admin "Has issues" view and the menu badge update, and list --has-issues
lists the redirects it flagged:
wp legacy-redirector validate
wp legacy-redirector list --has-issuesName redirects to see what is wrong with each, and what to do about it. This also updates their flags, so re-checking one after a fix that WordPress does not announce, such as a host allowed in code, takes it off the list:
wp legacy-redirector validate /old-page 123
wp legacy-redirector list --has-issues=problem --limit=100000 --format=ids | xargs -r wp legacy-redirector validateThe -r matters here: with nothing flagged, GNU xargs would otherwise run a bare
validate, which checks every redirect.
test checks named redirects live: it requests the destination where only a request can
judge it (a URL, or a path that resolves to no post), and requests the source to see
whether visiting it redirects there. It records nothing. --only=destination or
--only=source runs one of the two. To check whether every external destination still
responds:
wp legacy-redirector test /old-page
wp legacy-redirector list --destination-type=url --limit=100000 --format=ids | xargs -r wp legacy-redirector test --only=destinationA request that cannot get an answer (a timeout, a refused connection), or gets a server error, is reported as inconclusive: the host may simply be slow or briefly down. On WordPress VIP the request helper also stops calling a host for a short while after a few slow responses, so one slow host can fail every check to it in a run. Test again before treating one of these as broken.
Neither command changes a redirect. Almost no problem has a fix the plugin can safely apply (restoring a post, repointing a redirect, and allowing a host are decisions for a person), so each finding says what to do instead. To switch off the redirects with problems, do it explicitly:
wp legacy-redirector list --has-issues=problem --limit=100000 --format=ids | xargs -r wp legacy-redirector disableA disabled redirect is still checked, so it stays on the list until it is repaired or deleted.
# Everything, with a header import reads its columns from.
wp legacy-redirector list --limit=100000 --format=csv > redirects.csv--limit defaults to 100, so an export without it gives you the first hundred rows.
--format=table warns you when it has truncated the list; the machine-readable formats do
not, so an export is the one place this bites. Pass a number larger than your redirect set
— wp legacy-redirector list --format=count tells you what that is, and reports the true
total regardless of --limit.
Restore it as is. import finds the from, to, and status columns by the header and
ignores the rest, such as ID and type, so an export with other --fields works too as
long as it includes from and to:
wp legacy-redirector import redirects.csv --mode=upsert--format=ids pipes into any of the commands that take multiple redirects. As with an
export, pass a --limit larger than the set, or only the first hundred are acted on:
# Delete every disabled redirect.
wp legacy-redirector list --status=disabled --limit=100000 --format=ids \
| xargs -r wp legacy-redirector delete --yes
# Disable everything pointing at a post rather than a URL.
wp legacy-redirector list --destination-type=post --limit=100000 --format=ids \
| xargs -r wp legacy-redirector disableWhere a migration left the old URL on the post it now lives at, import-from-meta turns
those into redirects. The meta value is the source; the post holding it is the
destination:
wp legacy-redirector import-from-meta --meta-key=legacy-urlWork through a large set in slices with --start and --end, which count the key's rows
in the order they were added, and preview with --dry-run. A dry run checks each row as the import would, so a source that already has
a redirect, or a destination post that is not published, is reported rather than promised:
wp legacy-redirector import-from-meta --meta-key=legacy-url --start=0 --end=1000 --dry-run--skip-dupes passes over sources that already have a redirect, which makes re-runs
cheap. Without it, each source that already has a redirect is a failed row. A live run
with any failed row exits with status 1 after importing the rest, naming how many failed.
--porcelain prints just the ID, for scripting:
id=$(wp legacy-redirector create /old-page /new-page --porcelain)
wp legacy-redirector disable "$id"Everything takes --url:
wp legacy-redirector create /old-page /new-page --url=site2.example.com
wp legacy-redirector list --format=count --url=site2.example.comNote that a source path is read relative to that site's home URL. On a subsite at
example.com/blog, a source of /old-page means example.com/blog/old-page, and the
/blog prefix is not part of the stored source. The same applies to a plain single site
installed below the domain root. See the README section on site-relative source paths.
Machine-readable formats print only the data. With --format=json, csv, yaml,
ids, or count, STDOUT carries the structured value and nothing else: an empty JSON
result is [], and an empty count is 0. Headings, summaries, and "nothing found"
sentences are for the table format; warnings and errors go to STDERR whatever the format.
get shows one redirect the way wp post get shows one post: --format=json and yaml
print a single object, not a list, and table and csv print Field,Value rows.
Imports are deliberately paced. import and import-from-meta pause for a second
every 100 rows and flush caches, to keep a large import from overwhelming the database.
Budget roughly a second per 100 redirects: a 50,000-row file takes at least eight
minutes. A dry run writes nothing, so it flushes caches but does not pause.
Destinations are validated by default. create and import check the destination
before storing it. --skip-validation turns that off, which is occasionally needed when
importing redirects to content that has not been published yet, but it means a broken
destination is stored without complaint. Follow up with validate, which names what to do.
Creating a redirect for a URL that currently works does nothing visible. Redirects only fire on requests that would otherwise 404, so a redirect whose source is still a live page stays dormant until that page goes away.