[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>]
| Option | Default | What it does |
|---|---|---|
--search=<text> | None | Only redirects whose source, target or notes contain this text. |
--status=<code> | Every status | Only this status code: 301, 302 or 410. |
--group=<group> | Every group | Only this group. |
--origin=<origin> | Every origin | Only this origin: manual, slug-change, import, migration or suggestion. |
--enabled=<enabled> | Both | Only enabled (true) or disabled (false) redirects. |
--fields=<fields> | None | Comma-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> | table | Output 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]
| Option | Default | What it does |
|---|---|---|
<source> | None | The URL to redirect from: a path on this site, or a full URL on this site. |
<target> | None | Where to send visitors. Not needed with --status=410. |
--status=<code> | 301 | Status code: 301, 302 or 410. |
--query-mode=<mode> | ignore | How the request’s query string affects matching: ignore, exact or pass-through. |
--match-type=<type> | exact | How the source is matched: exact (a URL), or a match type an add-on provides. |
--group=<group> | None | Group name. |
--notes=<notes> | None | Notes. |
--external | Off | Allows a target on another site. |
--disabled | Off | Adds the redirect switched off. |
--porcelain | Off | Prints 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>]
| Option | What 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]
| Option | Default | What it does |
|---|---|---|
<file> | None | The CSV file, or - for standard input. |
--dry-run | Off | Shows 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]
| Option | Default | What it does |
|---|---|---|
<plugin> | None | Where from: redirection, yoast or rank-math. |
--dry-run | Off | Shows 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>]
| Option | Default | What it does |
|---|---|---|
<file> | Standard output | Where to write the CSV. |
--search=<text> | None | Only redirects whose source, target or notes contain this text. |
--group=<group> | Every group | Only this group. |
--origin=<origin> | Every origin | Only 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>]
| Option | Default | What it does |
|---|---|---|
--status=<status> | open | Only this status: open, ignored, resolved or all. |
--search=<text> | None | Only URLs or referrers containing this text. |
--orderby=<field> | last_seen | Sort by url, hits, first_seen or last_seen. |
--limit=<number> | 100 | At most this many. 0 for all. |
--fields=<fields> | None | Comma-separated fields to show: id, url, hits, referrer, user_agent, first_seen, last_seen, status. |
--format=<format> | table | Output 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]
| Option | Default | What it does |
|---|---|---|
<id>... | None | Entry IDs, from 404 list. |
--yes | Off | Doesn’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]
| Option | Default | What it does |
|---|---|---|
--all | Off | Clears ignored entries too. |
--yes | Off | Doesn’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>
| Subcommand | Options | What it does |
|---|---|---|
list | --format: table (default), csv, json, yaml or count | Lists 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 it | Starts 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]
| Subcommand | Options | What it does |
|---|---|---|
list | --format: table (default), json, csv or yaml | Lists every setting, its value and its source: default, saved, filter or constant. |
get | --format: plain (default) or json | Prints one setting’s value. |
set | None | Changes 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 confirmation | Removes 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>]
| Option | Default | What it does |
|---|---|---|
<redirect-id> | None | Shows one redirect’s hits per day. |
--days=<days> | 30 | How many days back, including today. |
--not-hit=<days> | None | Without 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> | table | Output 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>]
| Option | Default | What it does |
|---|---|---|
--dry-run | Off | Lists every chain and what would happen to it, without changing anything. |
--format=<format> | table | With --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>]
| Option | Default | What it does |
|---|---|---|
--min-score=<score> | 1 | Only suggestions scoring at least this much, out of 100. |
--fields=<fields> | None | Comma-separated fields to show: id, url, hits, target, score, reason. |
--format=<format> | table | Output 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>]
| Option | Default | What it does |
|---|---|---|
<id>... | None | Logged 404 IDs, from suggestions list. |
--all | Off | Accepts every open 404’s suggestion scoring at least --min-score. |
--min-score=<score> | 80 | With --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