Uniform Siphon - Sitecore Command Reference (common)

This page covers the concepts that apply to every Uniform Siphon command: the executables, how configuration is resolved (command-line arguments, environment variables, and the .env file), logging, and the options that are shared across all commands. The per-command pages (download, migrate, push) only document what is specific to each command and link back here for the rest.

If you are migrating for the first time, start with the Sitecore migration walkthrough — it explains when and why to run each command. Use these reference pages as the lookup for what each command and parameter does.

Executables#

A Sitecore migration is driven by three separate command-line tools, each responsible for one phase of the Extract-Transform-Load pipeline:

The siphon / siphon.ps1 wrapper on your PATH (see the installation guide) forwards to the appropriate executable, so siphon download-items and siphon download download-items are equivalent to C:\siphon\Siphon.Download.exe download-items. The siphon uniform-canvas and siphon migration uniform-canvas are equivalent to C:\siphon\Siphon.Migration.exe uniform-canvas. The wrapper also provides the interactive configure-download wizard.

Configuring commands#

Every parameter can be supplied in one of three ways. When the same parameter is set in more than one place, the higher source wins:

1. A command-line argument — --parameterName value. Always wins.
2. An environment variable — real OS environment variables, and variables loaded from a .env file (see below).
3. A default baked into the command, if any.

Environment variables are the recommended way to drive a migration: they keep secrets out of your shell history, and they let you keep one reproducible configuration for the whole pipeline.

Environment-variable names#

Siphon turns SIPHON_-prefixed environment variables into command-line arguments for the verb you run. A variable is only applied if you did not already pass that option on the command line (so an explicit argument always overrides the environment). Two forms exist, and the more specific one wins:

• Command-scoped — SIPHON_{COMMAND}_{PARAMETER}. Applies only to that one command. Wins over the global form.
• Global — SIPHON_{PARAMETER}. Applies to every command that has that parameter.

The {COMMAND} and {PARAMETER} tokens are derived by upper-casing the name and replacing every - with _. So the command download-items becomes DOWNLOAD_ITEMS, and the option --outputDir becomes OUTPUTDIR:

Throughout the per-command pages, each switch lists its command-scoped variable (for example, --root on download-items shows SIPHON_DOWNLOAD_ITEMS_ROOT). The global SIPHON_{PARAMETER} form always works too.

The .env file#

Rather than exporting variables by hand, put them in a .env file (one KEY=value per line; lines starting with # are comments). On startup Siphon loads, without overwriting variables that are already set, from up to two locations:

1. The directory that contains the Siphon executable — loaded first.
2. The current working directory — loaded second (skipped if it is the same folder).

Because already-set variables are never overwritten, the effective precedence is: real OS environment variable → executable-folder .env → working-directory .env. Set SIPHON_DOTENV=false (or 0) to skip .env loading entirely.

Two helpers generate a .env for you:

• siphon configure-download — an interactive wizard (part of the siphon wrapper) that asks for the download-phase settings and writes a ready-to-use .env. See the download guide for a sample session.
• siphon generate-dot-env — writes a .env template into the current directory listing every supported SIPHON_ key, ready to fill in.

Special variables#

• SIPHON_COMMAND — its value is appended as the verb, letting you select the command itself from the environment.
• SIPHON_DOTENV — set to false/0 to disable .env loading.
• SIPHON_PATH_OVERRIDE — point the siphon wrapper at a specific build folder instead of the version on the PATH.

Logging#

Siphon ships with a built-in Serilog logger that writes several log files to the log directory (the current directory by default):

Verbosity is controlled by --logLevel (debug | info | warn | error, default info). Keep the default info for a normal run and switch to debug only when troubleshooting — the debug log is what the Uniform migration team will ask for. All the logging switches are listed under common options below.

Common options#

The logging and language options below are accepted by (essentially) every command, so the per-command pages don't repeat them — they document only the command-specific switches and link here. Each option's global environment variable is SIPHON_{NAME} (upper-cased, -→_); the command-scoped SIPHON_{COMMAND}_{NAME} form works too.

Performance and reliability switches (--threads, --RetryCount, --Timeout, --stopOnError, --skipClearingFolders, --cacheDir) are not universal — availability and meaning differ per command — so they are documented on each command's own page, under the command that uses them. The download commands additionally report their own throughput and can have their thread count changed, or auto-tuned, while they are running — see monitoring and tuning a running download.

Logging & diagnostics#

SIPHON_LOGLEVEL = (empty)|debug|info|warn|error (--logLevel)
Verbosity of the log files and console output (unless --consoleLogLevel overrides it). Default: info.

SIPHON_CONSOLELOGLEVEL = (empty)|debug|info|warn|error (--consoleLogLevel)
Verbosity of the console output, independent of the file logs. Defaults to --logLevel when unset — useful to keep the console quiet (warn) while still writing a full debug file.

SIPHON_LOGFILEPREFIX = (empty)|<string> (--logFilePrefix)
Override the log file name prefix (default .siphon.log{timestamp}).

SIPHON_LOGSDIR = (empty)|<path> (--logsDir)
Directory where log files are written (default: current working directory).

SIPHON_NO_TIMESTAMPS = true|false (--no-timestamps)
Drop timestamps from log lines (handy for diffing two runs' logs). Default: false.

SIPHON_SORTLOGENTRIESBYTHREADID = true|false (--sortLogEntriesByThreadId)
Post-process the log files to group entries by thread ID within each scope block, so a multi-threaded run reads in order. Default: false.

Languages#

SIPHON_LANGUAGES = (empty)|<list> (--languages)
Restrict processing to a subset of languages; empty (the default) means all registered languages. Delimiters: , ; |. Use the Sitecore Language item Name (find them in _languages.json in the download folder). Example: en|ja-JP|da.

Whenever you restrict this list, keep en in it and download it first — some template and language definition items data exist only in en in majority of Sitecore solutions, so a download without it yields broken template inheritance and gaps in localization.

SIPHON_DEFAULTLANGUAGE = (empty)|<string> (--defaultLanguage)
The migrated language Siphon treats as the canonical / base locale, used in both phases. Given as the Sitecore Language item Name (same identifier as --languages), e.g. en; default en. During download it is the context language for fetching the Sitecore language list and for resolving media items (download-media) and single-item lookups (debug-get-item). During migration it selects the base item version when building content types, entries, compositions and the project map, resolves non-localized/fallback field values, and its locale is written to Uniform with IsDefault: true as the project's default locale.

Resolution rule: when you migrate a single language this value is ignored and that language is used; when you migrate several, --defaultLanguage must name one of them, otherwise Siphon aborts with "Default language was not found. Set --defaultLanguage."

It also seeds the deterministic id of non-versioned assets — the Uniform asset id is hash(itemId + defaultLanguage) — so changing --defaultLanguage changes those asset ids (versioned media instead use the item's own version language, overridable with --versionedImgDefaultLanguage).

Item folders#

SIPHON_ITEMFOLDERS = (empty)|<rules> (--itemFolders)
How the item export is split into top-level folders. Default:

Each rule is name=/path[,/path], rules are separated by ;, and exactly one folder must claim * — it takes whatever no other rule matched. An item matching no rule, with no fallback to land in, would be silently lost, so a rule set without * is rejected at start-up rather than at the item that needed it.

The longest matching path wins, regardless of the order the rules are written in, so /sitecore/system/languages beats a broader /sitecore/system rule either way round. Matching is case-insensitive and stops at a path boundary: /sitecore/contentmanagement is not under /sitecore/content.

With the default rules a download writes:

Each folder carries its own _index.json, and that is the point of the split. download-media is a download-items pass before it is a binary fetch, so while every item shared one index per language it read-merge-wrote the same file the content download had just produced — tens to hundreds of megabytes, rewritten in place. Any other process reading the export at that moment could see a partly written index, and no content tree could be published until the media tree had finished. With one index per folder the two downloads touch disjoint trees and can run at the same time.

Reading needs no configuration at all: the migrate and push commands enumerate whatever folders are on disk and merge their indexes, so this option only ever affects the command doing the writing. An export produced with one rule set therefore loads fine under another.

Always available#

--help (--help) — Print the full, authoritative option list for the command (this reference is generated from the same source). (no environment variable.)

--version (--version) — Print the Siphon version. (no environment variable.)

Commands by phase#