Utility commands

This page covers commands that do not fit the main sync/migrate/backup groups.

copy

sb-mig copy stories \
  --from 12345 \
  --to 67890 \
  --source blog/post-1 \
  --destination imported

sb-mig copy stories \
  --from 12345 \
  --to 67890 \
  --source blog \
  --destination imported \
  --with-assets

sb-mig copy assets \
  --from 12345 \
  --to 67890 \
  --all

sb-mig copy assets \
  --from 12345 \
  --to 67890 \
  --asset hero.jpg

sb-mig copy assets \
  --from 12345 \
  --to 67890 \
  --assetFolder Marketing/Heroes

sb-mig copy assets \
  --from 12345 \
  --to 67890 \
  --referenced-by-stories \
  --source blog

sb-mig copy assets \
  --from 12345 \
  --to 67890 \
  --all \
  --dry-run \
  --outputPath sbmig/copy-plans/assets-copy.json

copy stories copies a source story or folder tree into a target folder. copy assets copies or plans all assets and asset folders. Apply mode writes asset folders and assets to the target space, finalizes asset uploads, and stores durable source-to-target manifests under .sb-mig/copy/<source>/<target>/.

Strategies

Options

Legacy story-copy aliases still work: --sourceSpace for --from, --targetSpace for --to, --what for --source, and --where for --destination.

--source must resolve to an existing story or folder. --destination must resolve to an existing folder in the target space unless it is omitted, /, or root. copy stories writes copied stories to the target space unless --dry-run is passed and writes story ID/UUID manifests under .sb-mig/copy/<source>/<target>/ during apply. It also rewrites mapped asset and story references in copied target story content after manifests exist. copy stories --with-assets scans the selected stories with source component schemas, copies referenced assets and their asset-folder ancestors first, then uses the manifests to relink copied story asset fields to target asset IDs and filenames. Dry-run output classifies asset references as mapped, planned, or unresolved and separates reference occurrences from unique assets in the JSON assetReferenceSummary. It also reports foreign Storyblok asset space IDs detected from asset URLs without trying to copy from those spaces. With --with-assets, referenced assets and folders are marked as match when an existing manifest mapping can be reused. Without --with-assets, run copy assets first when copied stories should point to target-space assets. copy assets writes target asset folders/assets unless --dry-run is passed. It supports --all, --asset, --assetFolder, and --referenced-by-stories. --asset includes the selected asset's folder ancestors. --assetFolder includes the selected folder, its descendants, ancestor folders, and assets inside the selected subtree. --referenced-by-stories requires --source; it scans the selected story or folder scope with source component schemas and copies only source-space assets referenced by that scope. copy assets matches by manifest first, then by safe target folder path or unique target asset file name before creating. --all paginates through source assets and asset folders before planning or applying, so large spaces are not limited to the first Storyblok Management API page. Apply mode writes JSONL manifests under .sb-mig/copy/<source>/<target>/.

Resilience and failure reporting

copy stories apply mode processes the whole selected tree even when individual stories fail. If a story update is rejected — for example a 422 when the target space schema does not allow a component used in the story — the command records the failure, keeps copying the remaining stories, and then exits non-zero at the end with a summary of every story that failed. A failing parent keeps its already-created target shell, so its descendants are still copied under it. One broken story no longer aborts a large copy.

Failed story updates identify the offending component in place: the component name, the field it sits in, its parent component, its _uid, and its path in the story content (for example content.body[3].tabs[1]), together with the source and target story IDs, so the exact blok can be located.

Predicting schema rejections in dry-run

copy stories --dry-run validates every source component against the target space component schema before you apply. The JSON report adds a componentCompatibility block and a summary.componentIssues count, and the plan warns when a component would be rejected at write time:

Each finding records the component, the reason, the source story full_slug, the field, the parent component, the _uid, and the content path. Tag-based field whitelists are skipped to avoid false positives, and the check is skipped entirely when the target space returns no components.

discover

Components

sb-mig discover components --all
sb-mig discover components --all --write
sb-mig discover components --all --write --file all-components

Without --write, the command prints discovered component metadata. With --write, it creates or overwrites the component list file.

Migrations

sb-mig discover migrations --all

Prints discovered migration config filenames. This command is read-only.

migrations recognize

sb-mig migrations recognize --from 3.4.0
sb-mig migrations recognize --from 3.4.0 --to 4.0.0

This command is specific to Backpack upgrade flows. It compares a previous Backpack version with a target version and prints recommended migrate content and migrate presets commands.

The command reads applied-backpack-migrations.json when present and reads package.json when --to is omitted. It does not call Storyblok and does not write files.

init project

sb-mig init project \
  --spaceId 12345 \
  --oauthToken xxx \
  --region eu

sb-mig init project \
  --spaceId 12345 \
  --oauthToken xxx \
  --region us \
  --gtmToken GTM-XXXX

init project creates a local .env and updates the Storyblok space preview domain.

The generated .env includes region URLs, access token, OAuth token, preview secret, space ID, translation strategy, and GTM ID. The preview domain is set to https://localhost:3000/api/preview/preview?secret=<secret>&slug=.

debug

sb-mig debug

Prints resolved Storyblok config, sb-mig version, dependency versions, the consumer @ef-global/backpack version when available, and whether the consumer package is ESM or CommonJS. It reads local config and package metadata only.