Uniform Siphon - Sitecore Migrate Command Reference

This page is the command-line reference for the transform phase of a Sitecore migration — the commands of Siphon.Migration.exe that convert the downloaded Sitecore data into Uniform serialization files: uniform-canvas (project map nodes, compositions and components) and uniform-content (content types and entries). The load-phase commands that push those files (uniform-upload-assets, uniform-push-releases, and the @uniformdev/cli scripts) are on the push reference.

The executables, configuration/environment-variable rules, logging, and the common options shared by every command are documented on the common reference. Each switch below lists its command-scoped environment variable; the global SIPHON_{PARAMETER} form works too.

If you are migrating for the first time, start with the Sitecore migration walkthrough.

Output folder is never cleaned automatically

The output folder is not cleared between runs, so you can migrate different start paths or languages into one project across several invocations. This means you must clear the output directory yourself after any change to the input data (re-running the download commands). In particular, clear the .temp folder, which caches the HTML→JSON rich-text conversions. Use --skipClearingFolders to combine runs into one folder deliberately.

Generate the Uniform Canvas — project map nodes, compositions, and component definitions — from the downloaded items and (when supplied) the presentation folder. Run it before uniform-content.

PS C:\migration> C:\siphon\Siphon.Migration.exe uniform-canvas ` --inputDir C:\migration\data\items ` --outputDir C:\migration\uniform ` --startPath /sitecore/content/Habitat/Home ` --presentationDir C:\migration\data\presentation

SIPHON_UNIFORM_CANVAS_INPUTDIR = <path> (--inputDir)
Folder of the downloaded Sitecore items.

SIPHON_UNIFORM_CANVAS_OUTPUTDIR = <path> (--outputDir)
Folder the Uniform serialization is written to.

SIPHON_UNIFORM_CANVAS_STARTPATH = <path> (--startPath)
Site root (Home) item, e.g. /sitecore/content/Habitat/Home. It must point at the real Home item — use --pagesToInclude/--pagesToExclude to scope which pages are generated, not --startPath.

SIPHON_UNIFORM_CANVAS_PRESENTATIONDIR = (empty)|<path> (--presentationDir)
Folder of download-presentation output. Supplying it lets Siphon build compositions with the real hierarchy of components (placeholders/renderings); without it, compositions are flatter.

SIPHON_UNIFORM_CANVAS_PRESENTATIONFALLBACK = off|missing|force (--presentationFallback)
Rebuild page presentation from the item export instead of a crawled presentation folder. Default off — only --presentationDir is used, exactly as before.

Use it when download-presentation is not available: no Experience Editor access on the source, credentials that only allow an item export, a site too large to crawl page by page, or a client that does not permit it. Everything the migration consumes from presentation — the placeholder tree, each rendering's type, datasource and parameters — is in the items' own layout fields.

  • force ignores --presentationDir entirely and builds every page from the item export.
  • missing uses the crawled corpus wherever it reached and the item layout for the rest, and logs how many pages fell back. Useful when a crawl came back incomplete: those pages otherwise produce no composition at all.

`missing` mixes two sources, and that has consequences

A crawled corpus records what the Experience Editor rendered; the item export records what an author authored. Mixing them per page means: --stripSingleSlotComponents becomes inconsistent (an item-derived rendering carries no rendered HTML, so it never looks like a slot-only wrapper — which disqualifies that wrapper type for the crawled pages too), and a component's slot set depends on which pages the crawl happened to reach. Prefer off or force unless you are deliberately repairing an incomplete crawl.

How the presentation is rebuilt. Sitecore stores no finished layout; it stores fragments the renderer assembles, and all three steps are replayed. Layout deltas — __Renderings and __Final Renderings are XML patches, not documents; the shared field resolves against __Standard Values, while the final field is a delta against the resolved shared layout with each inheritance level applied to it in turn, and a <r uid="…"><p:d /></r> stub deletes a rendering. SXA partial designs — a page item's layout holds only what an author dropped on it; header, footer, metadata and the scaffolding component that owns the page's placeholders come from the page design (the item's Page Design field, else the site's Presentation/Page Designs TemplatesMapping, base templates included), with each partial design's placeholders scoped as sxa-<signature> after the layout placeholder. SXA composites — Accordion, Tabs and Snippet render sections that live on the datasource or its children, carrying their own layout with relative placeholder keys, at <key>-<sectionIndex>-<DynamicPlaceholderId>.

What differs from a crawled run. Two classes appear only in the item-derived result, and neither is an error: renderings that render nothing (a missing datasource, or content the live site removed after the export), and renderings the Experience Editor does not decorate — site chrome such as headers, footers and <head> metadata — which a crawl never sees even though they render. --excludeComponents is the lever, and usually needs a few more entries when you turn the fallback on.

Inspecting what was reconstructed. With the fallback on, the synthesized trees are always written to <cacheDir>/presentation/<language>/<item path>/index.json, in the same shape a crawled presentation folder has — so "why did this page migrate like that" is a file diff against the crawled corpus rather than a rerun. It is not a substitute for a crawled corpus: it carries no CssSelector/ProductionHtml, so never point --presentationDir or the e2e tooling at it.

SIPHON_UNIFORM_CANVAS_NEXTPROJECTDIR = (empty)|<path> (--nextProjectDir)
Root of a Next.js app for experimental React component code generation.

SIPHON_UNIFORM_CANVAS_CREATEREWRITES = true|false (--createRewrites)
When generating into a Next.js app, add rewrites to next.config.js (default off).

SIPHON_UNIFORM_CANVAS_PAGESTOINCLUDE = (empty)|<list> (--pagesToInclude)
Generate compositions/nodes for only these pages. Combined with --pagesToExclude, include is applied first, then exclude.

SIPHON_UNIFORM_CANVAS_PAGESTOEXCLUDE = (empty)|<list> (--pagesToExclude)
Exclude pages from generation. Supports * wildcards and *!<name> ("everything at this level except <name>", e.g. /sitecore/content/Home/*!1 keeps /Home/1 and its descendants but drops the rest).

SIPHON_UNIFORM_CANVAS_DO_LANGUAGE_SPECIFIC = true|false (--do-language-specific)
Emit a unique composition and project-map node for each page–language pair instead of one localized page. Default: false.

SIPHON_UNIFORM_CANVAS_USENAMEFORPMN = true|false (--useNameForPMN)
Use the item Name (not its display name) when generating project-map nodes. Default: false.

SIPHON_UNIFORM_CANVAS_EXCLUDECOMPONENTS = (empty)|<list> (--excludeComponents)
Drop specific components from compositions and component definitions, by component ID. Delimiters , ; |.

SIPHON_UNIFORM_CANVAS_RENAMECOMPONENTS = (empty)|<list> (--renameComponents)
Rename components during migration, oldName:newName (multiple, delimited). Example: OldComponent:NewComponent|AnotherOld:AnotherNew.

SIPHON_UNIFORM_CANVAS_IGNOREPLACEHOLDERS = (empty)|<list> (--ignorePlaceholders)
Placeholder names to ignore during migration. Delimiters , ; |.

SIPHON_UNIFORM_CANVAS_REPLACEEMPTYDATASOURCEWITHCONTEXTITEM = (empty)|<list>|true|* (--replaceEmptyDatasourceWithContextItem)
Build a component's parameters from the context item (the page) when the rendering has no datasource of its own. A controller rendering whose view reads the page's fields directly otherwise migrates as an empty shell — no content parameters at all, only the migration group. Takes a component list, delimiters , ; |, matched case-insensitively against either name a call site has at hand: the Sitecore rendering name, or the generated component ID (which may carry a disambiguating suffix, e.g. Tool_Viewrendering). Spaces in a rendering name are optional, so Slide HTML and SlideHTML both match. Example: ProductDetail|ProductDetailHeader|WirelessAccessory. The switch requires a value — write --replaceEmptyDatasourceWithContextItem=<list>, not the bare flag. Default: off.

Name the components — do not turn this on for all of them

true and * still mean "every component", so an .env written when this option was a boolean keeps working. But whether a rendering should read the page item is a property of the rendering, not of the site: turned on globally, the shared layout components — reached from every page template — collect the union of all those templates' fields. Measured on one brand site, OneColumn came out with 86 parameters carrying SEO, sitemap, product-category and instructional-video fields, TwoColumnUneven with 43, and the project went from 434 content parameters to 1430. List the controller renderings that actually need it instead.

SIPHON_UNIFORM_CANVAS_STRIPSINGLESLOTCOMPONENTS = true|false (--stripSingleSlotComponents) Collapse "pass-through wrapper" renderings during migration — components whose only output is a single <UniformSlot> (or no markup at all). When enabled, such a rendering is removed and its child renderings are hoisted into the parent slot, so it never becomes its own component or composition entry. A rendering type is only collapsed when every instance across all pages is slot-only or empty; if any instance renders real markup or carries parameters, the whole type is left untouched. Turn off if a wrapper is being collapsed that should be kept. Default: false.

Sitecore reference fields can become Canvas slots (child components), blocks (inline structured values), or be left as raw JSON. These switches steer that per field or per contentTypeId:fieldId; delimiters , ; |; use * for "all".

SIPHON_UNIFORM_CANVAS_REF_SLOTS_INCLUDE_FIELDS / SIPHON_UNIFORM_CANVAS_REF_SLOTS_EXCLUDE_FIELDS = (empty)|<list> (--ref-slots-include-fields / --ref-slots-exclude-fields)
Include only / exclude these reference fields from conversion to slots and components. Default (neither set): include all — every qualifying reference field is converted (* on the include forces include-all, on the exclude forces exclude-all).

SIPHON_UNIFORM_CANVAS_REF_BLOCKS_INCLUDE_FIELDS / SIPHON_UNIFORM_CANVAS_REF_BLOCKS_EXCLUDE_FIELDS = (empty)|<list> (--ref-blocks-include-fields / --ref-blocks-exclude-fields)
Include only / exclude these reference fields from conversion to blocks. Default (neither set): include all — every qualifying reference field is converted (* on the include forces include-all, on the exclude forces exclude-all).

SIPHON_UNIFORM_CANVAS_REF_BLOCKS_SLOTS_INCLUDE_FIELDS = (empty)|<list> (--ref-blocks-slots-include-fields)
On denormalized reference-field slot components (e.g. FeaturedCardGrid_EventDetailPage), also deconstruct these ref fields into blocks so they match the page-root treatment (e.g. topics → topicsBlock). Empty (default) leaves them as raw JSON.

SIPHON_UNIFORM_CANVAS_USELEGACYREFFIELDSSLOTS = true|false (--useLegacyRefFieldsSlots)
Use the legacy reference-field-to-slots algorithm. Default: false.

SIPHON_UNIFORM_CANVAS_RELEASES = true|false (--releases)
Analyze publish restrictions on items and generate Uniform releases (push them later with uniform-push-releases). Default: false.

SIPHON_UNIFORM_CANVAS_TRYMIGRATEPERSONALIZATIONRULES = true|false (--tryMigratePersonalizationRules)
Attempt to migrate Sitecore personalization rules. Default: false.

SIPHON_UNIFORM_CANVAS_CACHECOMPONENTS = true|false (--cacheComponents)
Cache generated component definitions to speed up re-runs on the same data. Default: false.

SIPHON_UNIFORM_CANVAS_CACHEMEDIAINDEX = true|false (--cacheMediaIndex)
Cache the media index across runs on the same data. Default: false.

SIPHON_UNIFORM_CANVAS_THREADS = (empty)|<int> (--threads)
Number of parallel processing workers. Default: 4.

SIPHON_UNIFORM_CANVAS_STOPONERROR = true|false (--stopOnError)
Abort the migration on the first error instead of collecting errors and continuing. Default: false.

SIPHON_UNIFORM_CANVAS_SKIPCLEARINGFOLDERS = true|false (--skipClearingFolders)
Do not clear the Canvas output sub-folders (e.g. $(OutputDir)/compositions) before writing — use it when combining several runs into one folder. Default: false.

SIPHON_UNIFORM_CANVAS_CACHEDIR = (empty)|<path> (--cacheDir)
Folder for the component and media-index caches; defaults to --inputDir.

uniform-canvas also builds the content model

uniform-canvas runs the same content-model build as uniform-content, so it also accepts every uniform-content option below (scope & filtering, reference-field handling, rich text, output shaping, …) — use the SIPHON_UNIFORM_CANVAS_ prefix for the command-scoped variable. The content-only switches --dataSourceId, --excludePages, --excludePaths and --ref-as-json-fields do not apply to uniform-canvas.

uniform-content#

Transform Sitecore content items into Uniform content types and entries in the data source you name with --dataSourceId.

PS C:\migration> C:\siphon\Siphon.Migration.exe uniform-content ` --inputDir C:\migration\data\items ` --outputDir C:\migration\uniform ` --startPath /sitecore/content/Habitat/Home ` --dataSourceId content ` --excludePages

SIPHON_UNIFORM_CONTENT_INPUTDIR = <path> (--inputDir)
Folder of the downloaded Sitecore items.

SIPHON_UNIFORM_CONTENT_OUTPUTDIR = <path> (--outputDir)
Folder the entries and content types are written to.

SIPHON_UNIFORM_CONTENT_STARTPATH = <path> (--startPath)
Site root item.

SIPHON_UNIFORM_CONTENT_DATASOURCEID = <string> (--dataSourceId)
The Uniform Content data source the generated content types/entries belong to, e.g. content.

These options apply to uniform-canvas too

Every option below is also accepted by uniform-canvas (which builds the same content model). For its command-scoped variable, swap the prefix to SIPHON_UNIFORM_CANVAS_.

SIPHON_UNIFORM_CONTENT_EXCLUDEPAGES = true|false (--excludePages)
Exclude Sitecore pages from entries. Use it whenever you also migrate pages with uniform-canvas, so a page is not duplicated as both a composition and an entry. Default: false.

SIPHON_UNIFORM_CONTENT_CONTENTROOTPATHS = (empty)|<list> (--contentRootPaths)
Extra roots for content/datasources beyond --startPath. Delimiters , ; |. Example: /sitecore/content/Habitat/Global|/sitecore/content/Habitat/Settings.

SIPHON_UNIFORM_CONTENT_EXCLUDEPATHS = (empty)|<list> (--excludePaths)
Paths to exclude from migration. Delimiters , ; |.

SIPHON_UNIFORM_CONTENT_FILTERBYTEMPLATE = (empty)|<string> (--filterByTemplate)
Migrate only items of a given Sitecore template (name or ID).

SIPHON_UNIFORM_CONTENT_TEMPLATESTOEXCLUDE = (empty)|<list> (--templatesToExclude)
Templates (by Name) to not generate as compositions. Delimiters , ; |.

SIPHON_UNIFORM_CONTENT_TEMPLATESTOINCLUDE = (empty)|<list> (--templatesToInclude)
Templates (by Name) to generate as entries even if they wouldn't be by default.

SIPHON_UNIFORM_CONTENT_EXCLUDEFIELDS = (empty)|<list> (--excludeFields)
Fields to drop from generated content types, entries and Canvas components. field drops it everywhere; owner.field drops it only under an item/template named owner. Excluded fields are never registered as ref fields (so this beats the --ref-*-include-fields switches). Delimiters , ; |.

SIPHON_UNIFORM_CONTENT_INCLUDESYSTEMFIELDS = true|false (--includeSystemFields)
Migrate Sitecore system fields (ItemID, etc.), which are dropped by default.

SIPHON_UNIFORM_CONTENT_SKIPGROUPS = (empty)|<list> (--skipGroups)
Field groups to not migrate. Delimiters , ; |.

SIPHON_UNIFORM_CONTENT_SKIPDATASOURCES = true|false (--skipDatasources)
Skip datasource items. Default: false.

SIPHON_UNIFORM_CONTENT_REF_DROPDOWNS_EXCLUDE_FIELDS = (empty)|<list> (--ref-dropdowns-exclude-fields)
Exclude reference fields from automatic conversion to drop-downs (select/multi-select). Default (empty): include all — every qualifying field is auto-converted; use * to disable the feature entirely. Conversion is automatic when the referenced template is a simple lookup shape (one custom field, or two with one named value); on the canvas it takes precedence over ref-slots/ref-blocks, on the content stage it replaces the contentReference migration of the field. Per field or contentTypeId:fieldId; delimiters , ; |.

SIPHON_UNIFORM_CONTENT_REF_AS_JSON_FIELDS = (empty)|<list> (--ref-as-json-fields)
Migrate these reference fields as raw JSON. Per field or contentTypeId:fieldId. (content only)

SIPHON_UNIFORM_CONTENT_FIELDS_OVERRIDES = (empty)|<list> (--fields-overrides)
Override the ref-field type for simple single-field types: {fieldName}:{type} (or contentTypeId:fieldId), delimited.

SIPHON_UNIFORM_CONTENT_REFDEPTH = (empty)|<int> (--refDepth)
Depth to which references are expanded when a reference is migrated as a JSON value. Default: 2.

SIPHON_UNIFORM_CONTENT_SKIPEXTRALINKFIELDS = true|false (--skipExtraLinkFields)
Do not generate the extra {link}_Anchor, {link}_Title, {link}_QueryString fields for general-link fields. Default: false.

SIPHON_UNIFORM_CONTENT_AVOIDINTERNALLINKS = true|false (--avoidInternalLinks)
Migrate internal links as a plain url type instead of a projectMapNode link. Default: false.

SIPHON_UNIFORM_CONTENT_SKIPPAGEREFERENCES = true|false (--skipPageReferences)
For multi-reference fields, skip targets that are pages instead of emitting a dangling entry reference (pages become projectMapNode/composition, never entries). Default off (legacy keeps them).

SIPHON_UNIFORM_CONTENT_CHILDRENREFERENCESTYPES = (empty)|<list> (--childrenReferencesTypes)
For entries of these content types, add a childrenReferences field pointing at the item's Sitecore children. Delimiters , ; |.

SIPHON_UNIFORM_CONTENT_CHILDRENSLOTSTYPES = (empty)|<list> (--childrenSlotsTypes)
(canvas stage) For components whose ID matches, synthesize a children ref field listing the datasource item's Sitecore children, so the ref-slots pass turns them into a children slot with one component per child.

SIPHON_UNIFORM_CONTENT_PROCESSDATASOURCECHILDREN = true|false (--processDatasourceChildren)
Add a datasourceChildren field (references to Sitecore children) to every datasource item. Default: false.

SIPHON_PRODUCTIONHOST = (empty)|<host> (--productionHost)
Production host to strip from absolute external general-link URLs so they become site-relative (https://www.example.com/search → /search). Matches ignoring scheme, a leading www., and any port; give it with or without a scheme.

Rich text#

SIPHON_UNIFORM_CONTENT_RICHTEXTMODE = (empty)|json|html (--richTextMode)
Migrate rich-text (RTE) fields as Uniform structured RTE (json) or as raw HTML (html). Default: json.

SIPHON_UNIFORM_CONTENT_HTMLFIELDTYPE = (empty)|<string> (--htmlFieldType)
When --richTextMode=html, the Uniform field type used for the HTML field.

SIPHON_UNIFORM_CONTENT_TEMPDIR = (empty)|<path> (--tempDir)
Temp directory used by the rich-text conversion service (the .temp cache).

SIPHON_UNIFORM_CONTENT_VERSIONEDIMGDEFAULTLANGUAGE = (empty)|<string> (--versionedImgDefaultLanguage)
Migrate all versioned images using the value from this one language for every language version.

SIPHON_UNIFORM_CONTENT_REMOVEEMPTYFIELDS = true|false (--removeEmptyFields)
Remove field/parameter definitions that have no values across all entries/compositions. Default: false.

SIPHON_UNIFORM_CONTENT_PERSISTEMPTYTYPES = true|false (--persistEmptyTypes)
Keep content types or components that are used zero times. Default: false.

SIPHON_UNIFORM_CONTENT_PERSISTEMPTYSLOTS = true|false (--persistEmptySlots)
Keep slots of components not used in any composition. Default: false.

SIPHON_UNIFORM_CONTENT_PERSISTUNUSEDCOMPONENTS = true|false (--persistUnusedComponents)
Keep components not used in any composition. Default: false.

SIPHON_UNIFORM_CONTENT_TYPENAMESCONFIG = (empty)|<list> (--typeNamesConfig)
Rename generated types: OldType_hash:NewName pairs, delimited. Example: LinkList_98ce…:CustomLinkList|PromoCard_b30d…:PromoCard.

SIPHON_UNIFORM_CONTENT_CACHEMODELS = true|false (--cacheModels)
Cache the generated models to speed up re-runs on the same data. Default: false.

SIPHON_UNIFORM_CONTENT_MISSINGITEMSFILENAME = (empty)|<string> (--missingItemsFileName)
Override the name of the _missing-items-and-media-{timestamp}.json report.

SIPHON_UNIFORM_CONTENT_MISSINGREFERENCESFILENAME = (empty)|<string> (--missingReferencesFileName)
Override the name of the _missing-reference-items-{timestamp}.json report.

SIPHON_UNIFORM_CONTENT_THREADS = (empty)|<int> (--threads)
Number of parallel processing workers. Default: 4.

SIPHON_UNIFORM_CONTENT_STOPONERROR = true|false (--stopOnError)
Abort the migration on the first error instead of collecting errors and continuing. Default: false.

SIPHON_UNIFORM_CONTENT_SKIPCLEARINGFOLDERS = true|false (--skipClearingFolders)
Do not clear the output sub-folders before writing — use it when combining several runs into one folder. Default: false.

SIPHON_UNIFORM_CONTENT_CACHEDIR = (empty)|<path> (--cacheDir)
Folder for the model caches; defaults to --inputDir.

Plus the common options (--languages, --defaultLanguage, logging).

Extract the Sitecore Scriban rendering-variant templates (SXA) from the downloaded items into .scriban files under a Scriban/ folder, so they can be inspected or ported to the front end. Not part of the normal migration flow.

SIPHON_EXTRACT_SCRIBAN_INPUTDIR = <path> (--inputDir)
required; the downloaded items folder.

SIPHON_EXTRACT_SCRIBAN_OUTPUTDIR = <path> (--outputDir)
required; folder under which the Scriban/ directory is created.

SIPHON_EXTRACT_SCRIBAN_RETRYCOUNT = (empty)|<int> (--RetryCount)
Retry attempts for each item before it is recorded as unsuccessful. Default: 3.

SIPHON_EXTRACT_SCRIBAN_TIMEOUT = (empty)|<int> ms (--Timeout)
Timeout for each request, in milliseconds. Default: 60000 (must be > 100).

SIPHON_EXTRACT_SCRIBAN_STOPONERROR = true|false (--stopOnError)
Abort the run on the first error instead of collecting errors and continuing. Default: false.

SIPHON_EXTRACT_SCRIBAN_SKIPCLEARINGFOLDERS = true|false (--skipClearingFolders)
Do not clear the output sub-folders before writing — use it when combining several runs into one folder. Default: false.

SIPHON_EXTRACT_SCRIBAN_CACHEDIR = (empty)|<path> (--cacheDir)
Folder for the caches; defaults to --inputDir.

Plus the common options (--languages, --defaultLanguage, logging).

Last modified
Next
Models