CLI reference

Consolidated reference for every wp ssi subcommand and flag. For task-focused workflows, see the relevant Getting Started / Troubleshooting article – this is the power-user lookup table.

All commands run with WP-CLI’s standard --path= / --user= flags etc. – those aren’t documented here.

wp help ssi lists every subcommand your edition has, with its arguments, flags and examples. A flag a subcommand does not accept is refused with exit code 1 and the list of flags it does accept, so a mistyped flag such as --wokers=2 is never ignored.

Running an import

wp ssi <import-id> [<stages>] [--file=<csv>] [--workers=<N>] [--verbose] [--delete-all] [--performance]

Positional arguments

• <import-id> – the numeric ID of the import (from wp_ssi_imports.id, or the admin UI’s import dropdown). Required.
• <stages> – optional. Run only these stages, comma-separated. The list replaces the import’s saved mode (What should this import do?) for this run: every named stage runs, even one the saved mode leaves out. Without a list, the saved mode decides. Examples:

  wp ssi 5                                                # all stages
  wp ssi 5 load-csv                                       # just one stage
  wp ssi 5 load-csv,match-existing,update-postmeta        # several stages

Stages always run in priority order regardless of the order in the list. Names are the hyphenated stage names (load-csv, not load_csv). If any name is not a stage this import has, the command stops before doing anything and exits with code 1, printing an error that names the unknown entry and lists the import’s stages in run order. A named stage that has nothing to do for the import’s configuration (for example fix-attributes with no attributes mapped) is skipped with a notice. A single utility name (save-posts, sanitize-terms, list-files) runs that utility on its own.

Flags

Examples

# Standard full import
wp ssi 5

# Re-run just upsert-relationships after a failed run
wp ssi 5 upsert-relationships

# One-off "update prices only" without changing the saved Import Mode preset
wp ssi 5 load-csv,match-existing,update-postmeta

# Create the new items on an import saved as "Only update prices" (the list replaces the saved mode)
wp ssi 5 load-csv,match-existing,insert-posts,insert-postmeta

# Import a different CSV through the same config
wp ssi 5 --file=/tmp/jan-2026-prices.csv

# Reduce workers for one run (e.g. shared hosting at peak time)
wp ssi 5 --workers=2

# Delete every product previously imported by this import config
wp ssi 5 --delete-all

Creating an import from CLI

wp ssi create <name> <template> <csv-file> [<json-config>] [--separator=<char>] [--decimal=<char>]

Creates a row in wp_ssi_imports programmatically – useful for automating environment setup or test harnesses.

Positional arguments

• <name> – human-readable name shown in the admin dropdown.
• <template> – short alias for the import template:
  • post → SuperSpeedyImports_PostTemplate
  • product → SuperSpeedyImports_WooCommerceProductTemplate
  • cpt → SuperSpeedyImports_CustomPostTypeTemplate
  • or pass the full SSI-prefixed class name for custom templates.
• <csv-file> – path to the CSV. Doesn’t have to live in the standard uploads directory. For an XML or JSON source, pass the file convert-source prepared (below).
• <json-config> (optional) – absolute path to a JSON file containing template_mappings. If omitted, the file is auto-mapped the same way as in New Import, and the command prints how many columns it mapped. Review the mapping before running.

A CSV of taxonomy terms (one row per category, tag or other term) is refused for a template that imports posts or products, and the command exits without creating anything.

Flags

Both flags are stored on the import and used to auto-map the file, so a semicolon-separated file is read as columns and a comma-decimal price column is recognised as a price:

wp ssi create "Supplier prices" product /tmp/prices.csv --separator=';' --decimal=,

Output

Import created successfully with ID: 42

Further lines follow when the file is auto-mapped or a configuration is applied. Capture the ID in scripts with sed -n 's/^Import created successfully with ID: //p'.

XML and JSON sources

wp ssi convert-source <xml-or-json-file> [<csv-file>] [--record-path=<path>] [--repeat-separator=<char>]
wp ssi replace-source <import-id> <xml-or-json-file>

convert-source reads an XML, JSON or JSON Lines file and prepares an import from it. It detects the file’s type from its contents and copies it into the imports directory, where it stays as the import’s source.

• --record-path – the repeating element that holds one record, such as /catalogue/product for XML or /data/products for JSON. Omit it to use the detected path. A file with only one record needs it.
• --repeat-separator – joins a value that repeats inside one record. Default |.

It prints JSON with the source file, its type, the prepared CSV, the record path, the record count, the fields, any warnings, and a next line with the wp ssi create command to run on the prepared CSV. An import created that way reads the XML or JSON file again whenever its contents change.

wp ssi convert-source /tmp/catalogue.xml --record-path=/catalogue/product
wp ssi convert-source /tmp/feed.json
wp ssi create "Supplier feed" product feed.converted.csv

replace-source gives an existing XML- or JSON-backed import a new source file. The new file is read completely before anything changes, so a file that cannot be used leaves the import as it was.

The older names wp ssi xml-to-csv and wp ssi replace-xml run the same two commands. See Importing XML and JSON feeds for record paths and field names.

Exporting products / posts to CSV

wp ssi export <post-type> [<output-file>]
wp ssi export <output-file> <post-type> [--exclude-dates] [--include-lookup]

The first form is the re-importable export, the same as the Export tab. Without an output file it writes to wp-content/uploads/super-speedy-imports/exports/ under a random name and prints the path. The second form, chosen when the first argument is a file path, is a diagnostic export for diffing two sites or two runs. Both are paid-edition commands.

Flags (diagnostic form)

• --exclude-dates – strip post_date, post_modified etc. from the output. Useful for diffing exports between runs (dates always differ).
• --include-lookup – add WooCommerce’s product lookup table columns.

Examples

wp ssi export product
wp ssi export product /tmp/products-backup.csv
wp ssi export /tmp/posts.csv post --exclude-dates

See Using the Export CLI Command for what each form contains.

Import / export taxonomies

wp ssi import-taxonomies <json-file>
wp ssi export-taxonomies <post-type> [<output-file>]

Dumps/restores the taxonomy DEFINITIONS (custom post-type registrations + custom taxonomy args) – NOT the term content. Useful for migrating taxonomy schemas between sites without re-registering them in code.

# On source site:
wp ssi export-taxonomies product /tmp/woo-tax-schema.json

# On target site:
wp ssi import-taxonomies /tmp/woo-tax-schema.json

The JSON format is the same as the taxonomies.json files in the test directories.

Other subcommands

wp ssi <id> save-posts

Iterates every post imported by this import id and fires WP’s save_post action. Lets plugins that listen for save_post (Yoast, search indexers, ACF post-init logic) catch up after a bulk import that bypassed their hooks.

wp ssi 5 save-posts

Slow at scale (no batching of the action firing). Skip for first imports if you don’t have hook-listening plugins to update.

wp ssi <id> sanitize-terms

Cleans up wp_terms slugs/names after a bulk taxonomy import – handles edge cases in WP’s term sanitisation that occasionally produce mangled slugs.

wp ssi 5 sanitize-terms

Idempotent. Run if you suspect stale or corrupt term data.

wp ssi <id> list-files

Lists CSV files in the standard uploads directory that match this import template’s header signature. Useful for verifying the right CSVs are visible to SSI before kicking off a run.

wp ssi 5 list-files

wp ssi resync-image-lookup

Takes NO import id. Truncates and rebuilds the global wp_ssi_image_lookup table from existing attachment GUIDs in wp_posts. Run after you’ve manually edited the WP media library outside SSI, or after restoring from a backup, so subsequent imports can find existing attachments by URL instead of re-downloading them.

wp ssi resync-image-lookup

Output includes per-row timing so you can sanity-check speed on large media libraries.

Saving and loading an import’s configuration

Every edition.

wp ssi save-config <import-id> [<output-file>]
wp ssi load-config <import-id> <json-file>

save-config prints the import’s configuration as JSON: name, template, column mappings, file name, field separator, CSV headers, Additional Options, PHP functions and any remote source settings. Email alert settings are left out. Without an output file it prints to the screen. With one, it writes the file inside wp-content/uploads/super-speedy-imports/, keeps any sub-folders you name inside that folder, and adds .json when the name lacks it. A path outside that folder, or one that climbs out of it with .., is refused and nothing is written.

load-config applies a saved configuration to an import: its column mappings, Additional Options and PHP functions. The import’s name, template and source file stay as they are, and keys the file does not contain are left unchanged. Additional Options are validated before anything is written, so a file with an invalid option changes nothing. In Lite, Pro-only mappings and PHP functions in the file are dropped.

wp ssi save-config 5 supplier-feed.json
wp ssi load-config 12 wp-content/uploads/super-speedy-imports/supplier-feed.json

See How do I migrate imports between sites? for moving imports to another site.

Remote sources

Every edition.

wp ssi fetch-source <import-id>
wp ssi source-status <import-id>

These work on an import that downloads its file from a URL. Every run of such an import downloads the file first; these commands let you do that step on its own or check it.

fetch-source downloads the file immediately without running the import. The download is checked before it replaces the import’s file, so a failed or empty download leaves the current file in place. It prints JSON with changed (whether the file differs from the one it replaces), bytes, sha256, target_file and checked_at_utc. An import with no remote source exits with “That import has no recurring source configured.”

source-status prints the remote source settings as JSON: whether one is configured and enabled, the scheme, host and remote file name, the local file it writes to, and the time, size and hash of the last check. Credentials and the full URL are stored encrypted and never printed.

wp ssi fetch-source 5
wp ssi source-status 5

See Can SSI import from a URL or remote feed? for setting the URL up.

Scheduled imports (Pro)

wp ssi schedule <import-id> [once|hourly|daily|weekly] [--enabled] [--next="<Y-m-d H:i:s>"]
wp ssi schedule-list
wp ssi schedule-run <import-id>
wp ssi schedule-pause <import-id>
wp ssi schedule-resume <import-id>

These commands are not in Lite.

• schedule – saves the import’s schedule. The cadence defaults to once. The schedule is saved disabled unless you pass --enabled, so pass it every time you want the schedule to stay on. --next sets the first run in site time; quote it, because it contains a space. Without it, once is due straight away; the other cadences run at the time of day and on the days saved on the Scheduled tab (from 3.51.0), or, when none is saved for that cadence, one interval after the command runs. The command does not set a time of day or days itself. Any other cadence is refused with “cadence must be once|hourly|daily|weekly”.
• schedule-list – one line per schedule: import ID, cadence, enabled, status (idle, running or paused), next run, last run and last result.
• schedule-run – runs the import immediately through the scheduled runner, in the foreground, until it finishes. An import with no schedule gets a disabled one-off schedule for the run. If a run of the import is in progress, including a paused one, it starts nothing and exits with an error.
• schedule-pause – the run stops at its next step and keeps its place.
• schedule-resume – continues a paused run in the background.

wp ssi schedule 5 daily --enabled --next="2026-11-01 03:00:00"
wp ssi schedule-list
wp ssi schedule-run 5

See Scheduled imports and alerts for the settings screen, which also sets a time of day and the days a schedule runs on.

Change events for other plugins

Every edition.

wp ssi changes <import-id> | --import=<id> | --history=<id>
wp ssi retry-events <import-id> | --import=<id> | --history=<id> [<integration-id>]
wp ssi deliver-events <import-id> | --import=<id> | --history=<id> [<integration-id>]

Some plugins are told about what an import changed after it completes, such as Back In Stock Notifier for WooCommerce (integration ID back-in-stock-notifier-for-woocommerce). The import records those changes as events and delivers them after the import. These commands report and finish that delivery. Each takes an import ID or a history ID (one run in Import History). --import= and --history= say which you mean. A bare number is accepted when it is only one of the two; when it is both an import ID and the history ID of another import’s run, the command refuses and asks you to choose. Each command prints which it used.

• changes – per integration, the count of events in each status and the number still outstanding. A stalled queue is marked STALLED with the retry-events command to run.
• retry-events – puts failed events back in the queue and delivers the queue, then prints what remains outstanding. Limit it to one integration by passing its ID.
• deliver-events – delivers every pending event for the import until none remain, and prints how many were delivered and coalesced (repeat events for the same item merged into one). It is safe to run more than once, and at the same time as another delivery: each run claims its own events.

wp ssi changes 841
wp ssi retry-events 841 back-in-stock-notifier-for-woocommerce

See Using Back In Stock Notifier with Super Speedy Imports.

Worker invocation (internal)

There is no worker subcommand. Workers are just ordinary wp ssi <import-id> invocations with extra flags – worker mode is triggered by the presence of --from-row (CSV-segmented stages) or --from-id (ID-segmented stages):

wp ssi <import-id> --stage=<name> [--from-row=N] [--to-row=N] [--byte-offset=N] [--from-id=N] [--to-id=N] [--history-id=N] [--stage-number=N]

Used internally by SSI when spawning parallel workers via proc_open. NOT meant to be called directly by users – the orchestrator (superspeedyimports_build_worker_command in run-import.php) constructs the right argument set per worker. Documented here for completeness; you should never need to invoke this manually.

Environment variables / constants

SSI checks a few PHP constants at runtime. Define these in wp-config.php if relevant:

Tables that SSI creates copy their character set and collation from wp_posts.post_name, so no collation constant is needed.

Note: hierarchy-level assignment is the per-import Additional Option assign_all_hierarchy_levels (“Assign every category level”) – when on, hierarchical taxonomy paths assign EVERY level (parent + grandparent + …) to the post, not just the deepest. Defaults ON for new imports. No PHP constant controls it.

Exit codes

wp ssi follows WP-CLI conventions:

• 0 – success.
• 1 – error during the import (typically a stage aborted), or a refused command: an import ID that does not exist, a stage name the import does not have, an unknown flag, or a --file that is missing or lacks the import’s columns. Stderr has the message, and a refused command changes nothing.
• 255 – fatal PHP error before the import could start.

Cron jobs and CI scripts can check $? to know whether the import succeeded.

Diagnostics

Quick CLI one-liners for common questions:

# List every import with last-run date
wp db query "SELECT i.id, i.import_name, i.csv_file_name, MAX(h.start_time) AS last_run
             FROM wp_ssi_imports i LEFT JOIN wp_ssi_import_history h ON h.import_id = i.id
             GROUP BY i.id ORDER BY last_run DESC"

# Show stage breakdown for the last run of import N
wp db query "SELECT stage_name, duration, end_time FROM wp_ssi_import_history_stages
             WHERE history_id = (SELECT MAX(id) FROM wp_ssi_import_history WHERE import_id = N)
             ORDER BY stage_number"

# Count rows in the per-import batch table
wp db query "SELECT COUNT(*) FROM wp_super_speedy_imports_batch_N"

# Count rows that match-existing didn't find (would be INSERTed in a normal run)
wp db query "SELECT COUNT(*) FROM wp_super_speedy_imports_batch_N WHERE post_id IS NULL"

What’s next

• How imports work – the stage pipeline – for the conceptual model behind the CLI.
• Stage selection presets – for saving the equivalent of a comma-separated stage list on the import config.
• Scheduling automated imports with cron – for wiring the CLI into automated workflows.

Written for Super Speedy Imports 3.63.0.