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.

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. Examples: bash 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.

Flags

Flag	Effect
--file=<absolute-path>	Override the configured CSV file for this run. The config’s saved path is ignored. Useful for incremental imports against the same template config, or for testing.
--workers=<N>	Override the configured parallel worker count for this run. Default comes from Performance Options. Note: the import-taxonomies stage is forced to a single worker regardless of this value (race-safety; parallelism here measured only ~7% gain — since 2.55.8).
--verbose	Echo every SQL query and per-row processing detail. Floods the terminal — pipe to a file.
--delete-all	Skip CSV loading + worker spawning. Run ONLY the process-deletes stage, which deletes every post imported by previous runs of this import. Force-delete (skips trash). One-shot — does not re-import.
--performance	Append a per-function timing table at the end of the run. Useful for diagnosing where CPU goes inside a slow stage.

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

# 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 → SSI_PostTemplate
• product → SSI_WooCommerceProductTemplate
• cpt → SSI_CustomPostTypeTemplate
• or pass the full SSI-prefixed class name for custom templates.
• <csv-file> — absolute path to the CSV. Doesn’t have to live in the standard uploads directory.
• <json-config> (optional) — absolute path to a JSON file containing template_mappings. If omitted, the import is created with no mappings (configure later via admin).

Flags

Flag	Default	Effect
--separator=<char>	,	Field separator. Use --separator=$'\t' for TSV.
--decimal=<char>	.	Decimal separator. Some European feeds use ,.

Output

Import created successfully with ID: 42

Capture the ID with grep -oE '[0-9]+$' in scripts.

Exporting products / posts to CSV

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

Exports the current WP state (not an import config) to a CSV. Used by the test harness for diffing imported vs expected, but also handy for backups / one-off data dumps.

Positional arguments

• <output-file> — absolute path where the CSV will be written.
• <post-type> (optional) — what to export. Defaults to product.

Flags

• --exclude-dates — strip post_date, post_modified etc. from the output. Useful for diffing exports between runs (dates always differ).

Examples

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

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.

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 (ssi_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:

Constant	Default	Effect
SSI_COLLATION	(WP default)	Override the MySQL collation used when creating per-import staging tables. Useful if your WP default is utf8mb4_general_ci but you want utf8mb4_unicode_520_ci for better Unicode handling.
SSI_AUTH_ENFORCE	undefined (soft mode)	If defined and true, every import requires a verified auth token. Used in security-sensitive multi-user setups.

Note: hierarchy-level assignment is no longer controlled by a constant. It’s now 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.

Exit codes

wp ssi follows WP-CLI conventions:

• 0 — success.
• 1 — error during the import (typically a stage aborted). Stderr has the message.
• 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.