# Uniform Siphon - Sitecore Command Reference (common)

> Shared concepts for the Uniform Siphon Sitecore CLI — executables, configuration, environment variables, logging, and the options common to every command

Source: https://docs.uniform.app/docs/guides/migration/sitecore/common-reference

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](https://docs.uniform.app/docs/guides/migration/sitecore/download-reference), [migrate](https://docs.uniform.app/docs/guides/migration/sitecore/migrate-reference), [push](https://docs.uniform.app/docs/guides/migration/sitecore/push-reference)) 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](https://docs.uniform.app/docs/guides/migration/sitecore/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:

| Tool | Phase | Responsibility |
| --- | --- | --- |
| `Siphon.Download.exe` | Extract | Pull items, media and presentation out of the live Sitecore instance. |
| `Siphon.Migration.exe` | Transform | Convert the downloaded Sitecore data into Uniform Canvas and Content files, upload assets, and create releases. |
| `@uniformdev/cli` (via `npm run`) | Load | Push the generated Uniform files to your Uniform project. |

The `siphon` / `siphon.ps1` wrapper on your `PATH` (see the [installation guide](https://docs.uniform.app/docs/guides/migration/sitecore/install)) 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`](https://docs.uniform.app/docs/guides/migration/sitecore/download-reference#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`:

```powershell
# global: --outputDir for ANY command that has it
$env:SIPHON_OUTPUTDIR = 'C:\migration\data\items'

# command-scoped: --outputDir for `download-items` only (wins over the global one)
$env:SIPHON_DOWNLOAD_ITEMS_OUTPUTDIR = 'C:\migration\data\items'

# a hyphenated option, e.g. --ref-slots-exclude-fields on uniform-canvas
$env:SIPHON_UNIFORM_CANVAS_REF_SLOTS_EXCLUDE_FIELDS = 'contenttype|topics'
```

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.

> **Boolean switches via environment variables:**
>
> A flag set to `false` in the environment (e.g. `SIPHON_FORCE=false`) is **ignored** — it behaves exactly the same as not setting it at all. This is because the mere presence of a `--flag` on the command line turns it on. To enable a boolean switch through the environment, set it to `true`; to keep it off, omit it (or leave it `false`). Every boolean switch is **off (`false`) by default**.

### 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](https://docs.uniform.app/docs/guides/migration/sitecore/download#configure-siphon) 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):

```
C:\migration\
  ├── ...
  ├── .siphon.log.debug.txt
  ├── .siphon.log.info.txt
  ├── .siphon.log.warn.txt
  ├── .siphon.log.error.txt
  └── ... other files
```

Verbosity is controlled by [`--logLevel`](#common-options) (`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](#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](https://docs.uniform.app/docs/guides/migration/sitecore/download-reference#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](https://docs.uniform.app/docs/guides/migration/sitecore/download#always-download-en-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`](https://docs.uniform.app/docs/guides/migration/sitecore/migrate-reference#uniform-content)).

### Item folders

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

```
content=/sitecore/content;media=/sitecore/media library;core=/sitecore/templates,/sitecore/system/languages,/sitecore/layout;other=*
```

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:

```
items/
  _languages.json            every registered language (stays at the root)
  .folders.json              the rule set this export was written with
  content/<language>/...     /sitecore/content
  media/<language>/...       /sitecore/media library
  core/<language>/...        templates, language definitions, layout
  other/<language>/...       everything else
```

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.

> **Existing exports keep working:**
>
> An export written before this option existed — `items/<language>/...` with a single index per language — is read as one unnamed folder and loads exactly as it always did, including the older `<language>_index.json` spelling that sat beside the language directory rather than inside it. Nothing has to be converted or downloaded again.
>
> To split an export you already have, move the item files into their folders and run `reindex`, which rebuilds each folder's index from the files that are actually there.

### 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

- [Download commands reference](https://docs.uniform.app/docs/guides/migration/sitecore/download-reference): Siphon.Download.exe — download-items, download-media, download-presentation (extract phase)
- [Migrate commands reference](https://docs.uniform.app/docs/guides/migration/sitecore/migrate-reference): Siphon.Migration.exe — uniform-canvas, uniform-content (transform phase)
- [Push commands reference](https://docs.uniform.app/docs/guides/migration/sitecore/push-reference): uniform-upload-assets, uniform-push-releases and the @uniformdev/cli push scripts (load phase)