Import and export site archives containing metadata XML on B2C Commerce instances using the b2c CLI. Use this skill whenever the user needs to import a site archive directory or zip to an instance, apply an ordered set of archives idempotently, export site configuration as XML, structure a site archive folder (sites/site_template/meta/), write or debug metadata XML files (system-objecttype-extensions.xml, custom-objecttype-definitions.xml, preferences.xml), or push custom attributes, custom object types, or site preferences to a sandbox via site import. Also use when an import job fails with schema validation errors โ even if they just say "push metadata to the sandbox" or "import my XML files".
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Import and export site archives containing metadata XML on B2C Commerce instances using the b2c CLI. Use this skill whenever the user needs to import a site archive directory or zip to an instance, apply an ordered set of archives idempotently, export site configuration as XML, structure a site archive folder (sites/site_template/meta/), write or debug metadata XML files (system-objecttype-extensions.xml, custom-objecttype-definitions.xml, preferences.xml), or push custom attributes, custom object types, or site preferences to a sandbox via site import. Also use when an import job fails with schema validation errors โ even if they just say "push metadata to the sandbox" or "import my XML files".
Site Import/Export Skill
Use the b2c CLI plugin to import and export site archives on Salesforce B2C Commerce instances.
Tip: If b2c is not installed globally, use npx @salesforce/b2c-cli instead (e.g., npx @salesforce/b2c-cli job import).
Configuration & Authentication
The CLI auto-discovers the target instance and credentials from SFCC_* environment variables, dw.json in the current or parent directories, ~/.mobify, package.json, and configuration plugins. Flags like --server, --client-id, --client-secret, --username, and --password are usually unnecessary โ only pass them to override what's auto-detected.
Run b2c setup inspect to see the resolved configuration and which source provided each value (use --json for scripting, --unmask to reveal secrets). For precedence rules and troubleshooting, see the b2c-cli:b2c-config skill.
Import Commands
Import Local Directory
# Import a local directory as a site archive (waits for completion by default)
b2c job import ./my-site-data
# Import and return immediately without waiting
b2c job import ./my-site-data --no-wait
# Import a local zip file
b2c job import ./export.zip
# Keep the archive on the instance after import
b2c job import ./my-site-data --keep-archive
# Show job log if the import fails
b2c job import ./my-site-data --show-log
Import Remote Archive
# Import an archive that already exists on the instance (in Impex/src/instance/)
b2c job import existing-archive.zip --remote
Apply an Ordered, Idempotent Import Set
Use job import-set when a directory contains multiple site archives that must be applied in order and skipped after the instance records their successful import. This section is the canonical import-set workflow.
Each immediate child directory or .zip file is one item. Hidden entries and other files are ignored, and item names are sorted lexically:
Name every item YYYYMMDDTHHmmss-description, using UTC for cross-time-zone teams. The timestamp supplies ordering and makes receipt-name collisions across projects extremely unlikely.
# Show pending and already-applied items without writing anything
b2c job import-set --dry-run
# Apply the default ./migrations directory
b2c job import-set
# Apply a different directory
b2c job import-set ./data-migrations
# Keep uploaded archives for inspection
b2c job import-set --keep-archive
Important semantics:
The CLI writes a durable receipt on the target instance after each successful import. Receipt identity is based only on the item name, so that name is skipped on later runs, including runs from other machines.
A missing or invalid receipt always causes another import. If the import succeeds and the process crashes before its receipt is written and verified, the next run imports that item again. Make archives safe to reapply.
Never edit an item after it has a valid receipt. Instances that already applied that name continue to skip it; add a new, later-sorting item for the next change.
Projects sharing an instance-wide receipt namespace must use distinct item names. UTC timestamps plus descriptive suffixes make accidental cross-project collisions unlikely.
Only one runner applies a given history at a time. Waiting runners re-check receipts after acquiring the lock.
A lock becomes stale after 30 minutes by default. Adjust this with --stale-lock-seconds; use --break-lock only after confirming the old owner has stopped.
--timeout applies to each archive import, --poll-interval controls job polling, and --lock-poll-interval controls lock waiting.
The default directory is ./migrations. Receipt and lock identity use the fixed instance-wide migrations namespace, regardless of the local path. Most users should omit --set-id; use it only when intentionally creating an independent history or preserving a legacy namespace.
Import Archives Larger Than the Instance Limit
An instance rejects a single import archive above its size limit (typically 200 MB). Use --split on a directory import to import the data in multiple smaller parts:
# Split a large directory import into multiple archive parts
b2c job import ./big-site-data --split# Tune the per-archive size limit (default 190mb; bare number is MiB)
b2c job import ./big-site-data --split --max-size 150mb
How splitting works:
Metadata/XML is imported first, kept together in one archive when it fits (so internal references and dependency ordering resolve within a single import). If the XML alone is too large, it splits at top-level data-unit boundaries (catalogs, libraries, sites, meta, โฆ) in dependency order โ never splitting a single unit.
Static assets (files under a static/ folder) are deferred into later archive parts, packed by compressed size. They attach to the catalogs/libraries created by the metadata import.
Parts import sequentially; the command stops on the first failure.
If a single file, or a single data unit's XML, is larger than --max-size on its own, the command errors (a file is never split across archives). A normal directory import that exceeds the limit warns and recommends --split. --split cannot be combined with --remote, subset paths, or --no-wait.
Export Commands
# Export global metadata (waits for completion by default)
b2c job export --global-data meta_data
# Export a site with specific data units
b2c job export --site RefArch --site-data content,site_preferences
