Skip to content

[00] Subset Redirects, For developers

WP-CLI commands

Every wp subset redirector command in Subset Redirects and Redirects Pro, with its options, defaults and examples as wp help prints them.

Subset Redirects adds its commands under wp subset redirector. Every change goes through the same validation as the admin screen. On multisite, pick the site with --url. The Pro commands appear once Subset Redirects Pro is active. Run wp help subset redirector <command> on your site to see the same text there.

wp subset redirector redirect add /old /new
wp subset redirector redirect list
wp subset redirector 404 list --orderby=hits
wp subset redirector settings list

redirect

Manages redirects.

redirect list

Lists redirects.

wp subset redirector redirect list [--search=<text>] [--status=<code>] [--group=<group>] [--origin=<origin>] [--enabled=<enabled>] [--fields=<fields>] [--format=<format>]
OptionDefaultWhat it does
--search=<text>NoneOnly redirects whose source, target or notes contain this text.
--status=<code>Every statusOnly this status code: 301, 302 or 410.
--group=<group>Every groupOnly this group.
--origin=<origin>Every originOnly this origin: manual, slug-change, import, migration or suggestion.
--enabled=<enabled>BothOnly enabled (true) or disabled (false) redirects.
--fields=<fields>NoneComma-separated fields to show: id, source, target, status_code, query_mode, match_type, enabled, external, group, notes, origin, hits, last_hit_at, created_at, updated_at.
--format=<format>tableOutput format: table, csv, json, yaml, ids or count.
wp subset redirector redirect list --status=302 --format=csv

redirect add

Adds a redirect.

wp subset redirector redirect add <source> [<target>] [--status=<code>] [--query-mode=<mode>] [--match-type=<type>] [--group=<group>] [--notes=<notes>] [--external] [--disabled] [--porcelain]
OptionDefaultWhat it does
<source>NoneThe URL to redirect from: a path on this site, or a full URL on this site.
<target>NoneWhere to send visitors. Not needed with --status=410.
--status=<code>301Status code: 301, 302 or 410.
--query-mode=<mode>ignoreHow the request’s query string affects matching: ignore, exact or pass-through.
--match-type=<type>exactHow the source is matched: exact (a URL), or a match type an add-on provides.
--group=<group>NoneGroup name.
--notes=<notes>NoneNotes.
--externalOffAllows a target on another site.
--disabledOffAdds the redirect switched off.
--porcelainOffPrints only the new redirect’s ID.
wp subset redirector redirect add /old /new
wp subset redirector redirect add /promo https://shop.example.com/sale --status=302 --external
wp subset redirector redirect add /discontinued --status=410

redirect update

Changes a redirect. Options you leave out keep their values.

wp subset redirector redirect update <id> [--source=<source>] [--target=<target>] [--status=<code>] [--query-mode=<mode>] [--match-type=<type>] [--group=<group>] [--notes=<notes>] [--external=<external>] [--enabled=<enabled>]
OptionWhat it does
<id>Redirect ID.
--source=<source>The URL to redirect from.
--target=<target>Where to send visitors.
--status=<code>Status code: 301, 302 or 410.
--query-mode=<mode>ignore, exact or pass-through.
--match-type=<type>exact, or a match type an add-on provides.
--group=<group>Group name. "" for none.
--notes=<notes>Notes.
--external=<external>Whether a target on another site is allowed: true or false.
--enabled=<enabled>true or false.
wp subset redirector redirect update 12 --target=/newer --status=302

redirect delete, enable and disable

Deletes redirects, or switches them on or off. Each takes one or more redirect IDs.

wp subset redirector redirect delete <id>...
wp subset redirector redirect enable <id>...
wp subset redirector redirect disable <id>...
wp subset redirector redirect delete 12 13
wp subset redirector redirect delete $(wp subset redirector redirect list --group=old --format=ids)
wp subset redirector redirect enable 12
wp subset redirector redirect disable 12

redirect test

Shows what a visit to a URL does.

wp subset redirector redirect test <url>

<url> is a path or URL on this site.

wp subset redirector redirect test /old-page

redirect import

Imports redirects from a CSV file. The columns are source, target, status_code, query_mode, enabled, group, notes and external. The first row names them, and only source is required. A row whose source already exists updates that redirect. See CSV format.

wp subset redirector redirect import <file> [--dry-run]
OptionDefaultWhat it does
<file>NoneThe CSV file, or - for standard input.
--dry-runOffShows what would happen without saving anything.
wp subset redirector redirect import redirects.csv --dry-run
wp subset redirector redirect import redirects.csv

redirect import-from

Imports redirects from another redirect plugin. It reads that plugin’s data from the database, so the plugin needn’t be active. Redirects that already exist are skipped, and ones that conflict with an existing redirect are reported and left alone. Redirects Subset Redirects can’t do, such as regular expressions and conditions, are reported and skipped.

wp subset redirector redirect import-from <plugin> [--dry-run]
OptionDefaultWhat it does
<plugin>NoneWhere from: redirection, yoast or rank-math.
--dry-runOffShows what would happen without saving anything.
wp subset redirector redirect import-from redirection --dry-run
wp subset redirector redirect import-from rank-math

redirect export

Exports redirects as CSV.

wp subset redirector redirect export [<file>] [--search=<text>] [--group=<group>] [--origin=<origin>]
OptionDefaultWhat it does
<file>Standard outputWhere to write the CSV.
--search=<text>NoneOnly redirects whose source, target or notes contain this text.
--group=<group>Every groupOnly this group.
--origin=<origin>Every originOnly this origin.
wp subset redirector redirect export redirects.csv
wp subset redirector redirect export --group=blog > blog.csv

404

Works with the 404 log.

404 list

Lists logged 404s.

wp subset redirector 404 list [--status=<status>] [--search=<text>] [--orderby=<field>] [--limit=<number>] [--fields=<fields>] [--format=<format>]
OptionDefaultWhat it does
--status=<status>openOnly this status: open, ignored, resolved or all.
--search=<text>NoneOnly URLs or referrers containing this text.
--orderby=<field>last_seenSort by url, hits, first_seen or last_seen.
--limit=<number>100At most this many. 0 for all.
--fields=<fields>NoneComma-separated fields to show: id, url, hits, referrer, user_agent, first_seen, last_seen, status.
--format=<format>tableOutput format: table, csv, json, yaml, ids or count.
wp subset redirector 404 list --orderby=hits --limit=20
wp subset redirector 404 list --status=all --format=json

404 ignore, resolve and reopen

These do what the Ignore, Resolve and Reopen actions on the 404 log screen do. Each takes one or more entry IDs from 404 list. Ignored entries stay in the log, and their URLs aren’t logged again. To find entries to reopen, list them with 404 list --status=all.

wp subset redirector 404 ignore <id>...
wp subset redirector 404 resolve <id>...
wp subset redirector 404 reopen <id>...
wp subset redirector 404 ignore 12 15
wp subset redirector 404 ignore $(wp subset redirector 404 list --search=/feed --format=ids)
wp subset redirector 404 resolve 12
wp subset redirector 404 reopen 12

404 delete

Deletes logged 404s. A URL that 404s again is logged again. To stop that, ignore it instead.

wp subset redirector 404 delete <id>... [--yes]
OptionDefaultWhat it does
<id>...NoneEntry IDs, from 404 list.
--yesOffDoesn’t ask for confirmation.
wp subset redirector 404 delete 12 15 --yes

404 clear

Clears the 404 log. By default it keeps ignored entries, because they’re what stops their URLs being logged again.

wp subset redirector 404 clear [--all] [--yes]
OptionDefaultWhat it does
--allOffClears ignored entries too.
--yesOffDoesn’t ask for confirmation.
wp subset redirector 404 clear --yes

404 prune

Deletes entries not seen within the retention period, as the daily cron job does.

wp subset redirector 404 prune

404 ignore-patterns

Manages the paths that aren’t logged as 404s. These are the log_ignored_paths setting. * matches anything, and matching ignores case.

wp subset redirector 404 ignore-patterns list [--format=<format>]
wp subset redirector 404 ignore-patterns add <pattern>
wp subset redirector 404 ignore-patterns remove <pattern>
SubcommandOptionsWhat it does
list--format: table (default), csv, json, yaml or countLists the ignored path patterns.
add<pattern>: a path, where * matches anything. Quote it so the shell doesn’t expand *.Stops logging URLs that match. Open entries that already match are ignored too, as Ignore a pattern on the 404 log screen does.
remove<pattern>: exactly as ignore-patterns list shows itStarts logging URLs that match again. Entries already ignored stay ignored. Reopen them with 404 reopen.
wp subset redirector 404 ignore-patterns add '/old-feed/*'
wp subset redirector 404 ignore-patterns list
wp subset redirector 404 ignore-patterns remove '/xmlrpc.php'

settings

Lists, reads and changes the plugin’s settings. Only known names are accepted, and values are cleaned the same way the settings screen cleans them. A setting pinned by a constant in wp-config.php can’t be changed here either.

wp subset redirector settings list [--format=<format>]
wp subset redirector settings get <name> [--format=<format>]
wp subset redirector settings set <name> <value>
wp subset redirector settings reset [--yes]
SubcommandOptionsWhat it does
list--format: table (default), json, csv or yamlLists every setting, its value and its source: default, saved, filter or constant.
get--format: plain (default) or jsonPrints one setting’s value.
setNoneChanges one setting. Booleans take true/false, yes/no, on/off or 1/0. Lists take a JSON array or comma-separated values.
reset--yes skips the confirmationRemoves every saved setting, so each goes back to its default. A setting pinned by a constant keeps the constant’s value.

The settings are case_insensitive, trailing_slash, auto_redirect, auto_redirect_terms, auto_redirect_410, auto_redirect_post_types, auto_redirect_taxonomies, log_mode, log_sample_rate, log_retention_days, log_max_rows, log_rate_limit, log_ignore_bots, log_ignored_paths and delete_on_uninstall.

wp subset redirector settings list
wp subset redirector settings set log_retention_days 90

stats (Pro)

Shows how often redirects are used. With a redirect ID, it prints that redirect’s hits per day. Without one, it lists every redirect with its hits over the last --days days, its hits ever, and when it was last used.

wp subset redirector stats [<redirect-id>] [--days=<days>] [--not-hit=<days>] [--format=<format>]
OptionDefaultWhat it does
<redirect-id>NoneShows one redirect’s hits per day.
--days=<days>30How many days back, including today.
--not-hit=<days>NoneWithout a redirect ID: only redirects at least this many days old that haven’t been hit in that time, the ones you can probably remove.
--format=<format>tableOutput format: table, csv, json, yaml, ids or count.
wp subset redirector stats 42 --days=7
wp subset redirector stats --not-hit=180 --format=ids

chains (Pro)

chains flatten points each redirect chain straight at the page its visitors end up on, as the Chains tab does. Where visitors land doesn’t change. Chains that loop, pass through a temporary (302) redirect, or depend on the visitor’s query string are left alone.

wp subset redirector chains flatten [--dry-run] [--format=<format>]
OptionDefaultWhat it does
--dry-runOffLists every chain and what would happen to it, without changing anything.
--format=<format>tableWith --dry-run, the output format: table, csv, json, yaml or count.
wp subset redirector chains flatten --dry-run
wp subset redirector chains flatten

suggestions (Pro)

Lists and accepts the redirects Pro suggests for open 404s, as the 404 Log screen does.

suggestions list

Lists open 404s that have a suggested redirect, busiest first. Suggestions are worked out in the background every hour, so a 404 logged since then has none yet.

wp subset redirector suggestions list [--min-score=<score>] [--fields=<fields>] [--format=<format>]
OptionDefaultWhat it does
--min-score=<score>1Only suggestions scoring at least this much, out of 100.
--fields=<fields>NoneComma-separated fields to show: id, url, hits, target, score, reason.
--format=<format>tableOutput format: table, csv, json, yaml, ids or count.
wp subset redirector suggestions list --min-score=80 --format=csv

suggestions accept

Accepts suggestions: it creates each suggested redirect, which resolves its 404. The target is worked out again first, from the post or term, in case it moved or started redirecting since. A suggestion that no longer holds is dropped, to be looked at again.

wp subset redirector suggestions accept [<id>...] [--all] [--min-score=<score>]
OptionDefaultWhat it does
<id>...NoneLogged 404 IDs, from suggestions list.
--allOffAccepts every open 404’s suggestion scoring at least --min-score.
--min-score=<score>80With --all, the lowest score to accept, out of 100.
wp subset redirector suggestions accept 12 15
wp subset redirector suggestions accept --all --min-score=90

server-rules (Pro)

Prints the site’s redirects as rules for Apache (.htaccess) or nginx (a server block). The rules only match requests in the form WordPress stores redirects, and anything else still reaches WordPress. Comments in the output say what differs, and list the redirects left out and why. Nothing is written to the server’s configuration.

wp subset redirector server-rules <format>

<format> is the server: apache or nginx.

wp subset redirector server-rules apache > redirects.htaccess.txt
wp subset redirector server-rules nginx > redirects.nginx.conf