--- title: SEOPress & WP-CLI url: "https://www.seopress.org/support/guides/seopress-wp-cli/" lang: en-US updated: 2026-09-29 --- # SEOPress & WP-CLI Manage SEOPress from the command line with WP-CLI. Run commands in the correct WordPress installation, or pass WP-CLI’s `--path` option. Back up the database before imports, deletions or migrations. Replace the example IDs and server paths with your own values. The custom settings, AI, content-analysis, license and redirection commands require SEOPress PRO and SEOPress Free. The `wp post meta`, `wp term meta` and `wp option` commands are provided by WordPress WP-CLI. Insights commands require SEOPress Insights. ## Export settings to a private JSON file ``` wp seopress settings export --destination='/home/example/private/seopress-settings.json' --exclude=license,api_keys ``` Create the private destination directory first and make it writable by the command’s user. `--destination` accepts a JSON filename or a directory. A directory uses `seopress-settings.json`. Without this option, the current working directory is used. Public destinations, including the web root and uploads, and symbolic-link destinations are refused. An existing export at the same path is overwritten. Without exclusions, exports can contain the license key and API credentials. Use `--exclude=license,api_keys` for a reusable configuration without these categories. Other categories include `knowledge_graph`, `social_profiles`, `analytics_ids` and `verification_codes`. Running `wp seopress settings export --exclude` displays the available category names as a validation error and does not export a file. Extensions can add categories. ## Import global settings ``` wp seopress settings import --from='/home/example/private/seopress-settings.json' ``` `--from` accepts a JSON file or a directory containing `seopress-settings.json`. Without it, the command looks in the current directory, then the uploads directory for compatibility with older exports. Prefer an explicit private path. Import applies global settings; review the destination configuration afterwards. It is not a complete WordPress database or post-metadata backup. ## Read, update and delete SEO metadata These examples read a post title, replace it and delete the custom value. Deletion lets the usual SEOPress defaults apply. Run only the operation you need. ``` wp post meta get 123 _seopress_titles_title wp post meta update 123 _seopress_titles_title "Example SEO title" wp post meta delete 123 _seopress_titles_title ``` For taxonomy terms, use the term ID with the same metadata key: ``` wp term meta get 45 _seopress_titles_title wp term meta update 45 _seopress_titles_title "Example category title" wp term meta delete 45 _seopress_titles_title ``` ## Generate titles, descriptions and alternative text Configure an AI provider in SEOPress PRO before running generation. Metadata commands use post IDs; alt-text commands use media attachment IDs. Results are printed for each ID. Generation can consume provider credits and is saved by default. ``` wp seopress ai metadata --id=123,124 --meta=desc --language=en_US wp seopress ai alt_text --id=456,457 --language=en_US ``` For metadata, `--meta=title` generates the title, `--meta=desc` the description; omit `--meta` to generate both. `--language` defaults to `en_US`; use a locale such as `fr_FR` or `es_ES`. For metadata, omit `--autosave` to keep the default saving behavior; `--autosave=0` generates without saving. Treat `alt_text` as a writing command: its `--autosave` argument does not provide a reliable preview mode. It can also generate and save the attachment caption and description. By default it can replace existing values. Use `--update_empty_alt_text=0` to restrict updates to empty fields. Test on a backed-up attachment before processing a list. ``` wp seopress ai metadata --id=123 --meta=title --autosave=0 wp seopress ai alt_text --id=456 --update_empty_alt_text=0 ``` ## Read and change global options ``` wp option get seopress_titles_option_name --format=json wp option patch update seopress_titles_option_name seopress_titles_home_site_title "Example homepage title" ``` The first command reads the option; the second changes only the nested homepage-title field. To delete the entire Titles and metas option, use the following command deliberately after a backup. This removes the whole option, not only the homepage title. ``` wp option delete seopress_titles_option_name ``` ## Manage the PRO license | Command | Effect | | --- | --- | | `wp seopress-pro license activate` | Activate the stored key; `--key` can supply a key. A defined `SEOPRESS_LICENSE_KEY` takes precedence. | | `wp seopress-pro license deactivate` | Deactivate the current site license. | | `wp seopress-pro license status` | Show stored status, expiry and masked key information. | | `wp seopress-pro license reset` | Clear stored license settings and update caches; does not remove a constant from wp-config.php. | | `wp seopress-pro license update` | Check and install an available PRO update; a valid license is needed to obtain licensed updates. | ## Import redirections in batches Put the export on the server in a readable location. List the formats supported by the installed version, then run a dry run before the actual import. A dry run prepares and checks the file without creating redirections. ``` wp seopress-pro redirections sources wp seopress-pro redirections import '/home/example/private/redirects.csv' --dry-run wp seopress-pro redirections import '/home/example/private/redirects.csv' --batch=1000 wp seopress-pro redirections import '/home/example/private/rankmath.json' --source=rankmath ``` `--source` accepts `csv`, `redirections_plugin`, `yoast`, `rankmath`, `rankmath_csv`, `slimseo`, `aioseo` and `smartcrawl`. A CSV without an explicit source is treated as SEOPress CSV. A JSON file requires its source because the extension alone cannot identify the exporter. `--separator` accepts `auto` (default), `comma`, `semicolon`, `tab` or `pipe`. `--batch` controls the number of redirections written per slice. If an import is interrupted, resume the saved job without starting a new file: ``` wp seopress-pro redirections import --resume ``` ## Refresh content analysis in the background ``` wp seopress content-analysis run wp seopress content-analysis status wp seopress content-analysis cancel ``` Enable Site Audit first. The run command queues background batches and returns before completion. WP-Cron, or a system scheduler executing due WordPress events, must work. The configured batch size and exclusions apply. Check status for progress and the last worker error. Cancel stops the shared Site Audit queue and keeps stored scores. Without `--post_type`, the existing audit scope is preserved. Supplying the option changes the saved Site Audit post-type setting; it is not a temporary override. Use registered public post types supported by the audit. Only one audit can run at a time. ``` wp seopress content-analysis run --post_type=post,page ``` ## Migrate SEOPress Insights data With SEOPress Insights 3.0, migration moves historical rankings and backlinks from post metadata to dedicated tables. These commands belong to Insights, not Free or PRO. Without `--full`, each command processes one batch. ``` wp seopress-insights migrate-backlinks wp seopress-insights migrate-backlinks --full wp seopress-insights migrate-rankings wp seopress-insights migrate-rankings --full ``` For rankings, `--force` resets the saved offset and status and restarts migration. Use it only to abandon the saved migration state after a database backup. ``` wp seopress-insights migrate-rankings --full --force ``` ## Troubleshooting commands If a custom command is unknown, confirm the correct site and required plugins are loaded and check the installed version’s help with `wp help seopress` or `wp help seopress-pro`. An export needs direct WordPress filesystem access and a writable private destination. A queued audit with no progress requires checking scheduled events and its status error. For core command syntax, see the [WP-CLI command reference](https://developer.wordpress.org/cli/commands/). See the [SEOPress metadata reference](https://www.seopress.org/support/guides/list-of-all-post-metas-generated-by-seopress/) for additional post and term keys.