# ๐Ÿ“š Arguments Description --- This section describe the different arguments and flags used by the tool. - An **argument** is a modifier that is followed by any parameter. - On the other hand, a **flag** is a modifier that don't require any parameter, hence, if the flag is present the feature is enabled, otherwise, the feature is disabled. There is also a [shorter version](02-arguments-description-short.md) of this document available. > [!NOTE] > For compiled binaries, macOS now uses `PhotoMigrator.command`. Linux and Synology SSH continue using `PhotoMigrator.bin`. If you are following the examples below on macOS, replace `PhotoMigrator.bin` with `PhotoMigrator.command`. ## ๐Ÿ–ฅ๏ธ Launcher Flags These flags are handled before the normal argparse parser starts, so they are launcher controls rather than regular feature arguments. | Argument | Parameter | Type | Valid Values | Description | |----------|-----------|:----:|:------------:|------------------------------------| | `--gui` | | flag | | Force the Desktop GUI explicitly. | | `--tui` | | flag | | Force the Terminal TUI explicitly. | #### ๐Ÿงช Examples: ```bash PhotoMigrator.bin --gui PhotoMigrator.bin --tui PhotoMigrator.bin --gui --configuration-file ./Config.ini PhotoMigrator.bin --gui --configuration-file /srv/PhotoMigrator/custom.ini ``` Notes: - GUI and TUI now also read `--configuration-file` during startup so the selected interactive interface can open with a custom config path already loaded. - If `--configuration-file` is not provided, both interfaces default to `./Config.ini` in the current execution folder. ## ๐Ÿงฉ Core Arguments | Argument | Parameter | Type | Valid Values | Description | |----------------------------------------------------|------------------------------|:--------:|:--------------------------------------------------------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-h`,
`--help` | | flag | | Displays the help message and exits. | | `-v`,
`--version` | | flag | | Shows the tool version and exits. | | `-config`,
`--configuration-file` | `` | FilePath | `Any valid Configuration File` | Specify the file that contains the Configuration to connect to the different Photo Cloud Services. The same argument is also honored by GUI/TUI launch so interactive interfaces can open with that file preselected. | | `-noConfirm`,
`--no-request-user-confirmation` | | flag | | No Request User Confirmation before to execute any Feature. | | `-noLog`,
`--no-log-file` | | flag | | Disables writing to log file. | | `-logLevel`,
`--log-level` | `` | string | `VERBOSE`,
`DEBUG`,
`INFO`,
`WARNING`,
`ERROR` | Sets logging verbosity. | | `-logFormat`,
`--log-format` | `` | string | `LOG`,
`TXT`,
`ALL` | Sets log file format. | | `-fnAlbums`,
`--foldername-albums` | `` | string | `any folder name` (default: `Albums`) | Specify the folder name to store all your processed photos associated to any Album. | | `-fnNoAlbums`,
`--foldername-no-albums` | `` | string | `any folder name` (default: `ALL_PHOTOS`) | Specify the folder name to store all your processed photos (including those associated to Albums). | | `-fnLogs`,
`--foldername-logs` | `` | path | `any folder name` (default: `Logs`) | Specify the folder name to save the execution Logs. | | `-fnDuplicat`,
`--foldername-duplicates-output` | `` | path | `any folder name` (default: `Duplicates_output`) | Specify the folder name to save the outputs of 'Find Duplicates' Feature. | | `-fnExtDates`,
`--foldername-extracted-dates` | `` | path | `any folder name` (default: `Extracted_Dates`) | Specify the folder name to save the Metadata outputs of 'Extracted Dates'. | | `-exeGpthTool`,
`--exec-gpth-tool` | `` | FilePath | `GPTH binary complete path` (default: `use internal binary`) | Specify an external version of GPTH Tool binary. | | `-exeExifTool`,
`--exec-exif-tool` | `` | FilePath | `EXIF binary complete path` (default: `use internal binary`) | Specify an external version of GPTH Tool binary. | --- ## โš™๏ธ General Options Following general arguments have different purposes depending on the Execution Mode. | Argument | Parameter | Type | Valid Values | Description | |-------------------------------------------|--------------------|:-----------:|:------------------------------------------------------------------------------------:|---------------------------------------------------------| | `-i`,
`--input-folder` | `` | path | `existing path` | Folder containing assets to be processed. | | `-o`,
`--output-folder` | `` | path | `valid path` | Folder where processed assets or results will be saved. | | `-client`,
`--client` | `` | string | `google-takeout`,
`google-photos`,
`synology`,
`immich`,
`nextcloud` | Specifies the service to interact with. | | `-id`,
`--account-id` | `` | int | `1`, `2`, `3`
`(default: 1)` | ID of the configured account in `Config.ini`. | | `-from`,
`--filter-from-date` | `` | date | `yyyy-mm-dd`,
`yyyy-mm`,
`yyyy` | Filters assets from this date onward. | | `-to`,
`--filter-to-date` | `` | date | `yyyy-mm-dd`,
`yyyy-mm`,
`yyyy` | Filters assets up to this date. | | `-type`,
`--filter-by-type` | `` | string | `image`, `video`, `all`
`(default: all)` | Filters assets by type. | | `-country`,
`--filter-by-country` | `` | string | `country-name` | Filters assets by country. | | `-city`,
`--filter-by-city` | `` | string | `city-name` | Filters assets by city. | | `-person`,
`--filter-by-person` | `` | string | `person-name` | Filters assets by person name. | | `-exFolders`,
`--exclude-folders` | `` | string/list | `glob patterns` (multiple allowed) | Excludes folders matching the provided glob patterns. | | `-exFiles`,
`--exclude-files` | `` | string/list | `glob patterns` (multiple allowed) | Excludes files matching the provided glob patterns. | | `-AlbFolder`,
`--albums-folders` | `` | path | `existing path` | Creates albums for subfolders inside. | | `-rAlbAsset`,
`--remove-albums-assets` | | flag | | Removes assets inside albums when albums are removed. | #### ๐Ÿงช Examples: ```bash PhotoMigrator.bin --input-folder=/mnt/import --output-folder=/mnt/export PhotoMigrator.bin --filter-from-date=2022-01-01 --filter-to-date=2022-12-31 PhotoMigrator.bin --filter-by-type=video --log-level=debug ``` --- ## ๐Ÿš€ Automatic Migration Following arguments allow you to execute the Automatic Migration Process to migrate your assets from one Photo Cloud Service to other, or from two different accounts within the same Photo Cloud service. | Argument | Parameter | Type | Valid Values | Description | |----------------------------------------|------------|:-----------------:|:-----------------------------------------------------------------------------------:|---------------------------------------------------------| | `-source`,
`--source` | `` | path /
string | `existing path`,
`synology`,
`immich`,
`nextcloud`,
`google-photos` | Defines the source for the automatic migration process. | | `-target`,
`--target` | `` | path /
string | `existing path`,
`synology`,
`immich`,
`nextcloud`,
`google-photos` | Defines the target for the automatic migration process. | | `-move`,
`--move-assets` | `` | bool | `true`, `false`
`(default: false)` | Enable / Disables move assets instead of copying them. | | `-dashboard`,
`--dashboard` | `` | bool | `true`, `false`
`(default: true)` | Enables / Disables the live dashboard during migration. | | `-parallel`,
`--parallel-migration` | `` | bool | `true`, `false`
`(default: true)` | Enables / Disables parallel asset migration. | #### ๐Ÿงช Examples: ```bash PhotoMigrator.bin --source=immich-1 --target=synology-2 PhotoMigrator.bin --source=/mnt/photos --target=/mnt/synology --move-assets=true PhotoMigrator.bin --source=synology-1 --target=immich-1 --parallel-migration=false ``` --- ## ๐Ÿ—ƒ๏ธ Google Takeout Management In this mode, you can use more than one optional arguments and flags from the below list. If only the argument `-gTakeout, --google-takeout ` is detected, then the Tool will use the default values for the rest of the flags for this extra mode. Following arguments allow you to interact with Google Photos Takeout Folder. | Argument | Parameter | Type | Valid Values | Description | |----------------------------------------------------|--------------------|:------:|:-------------------------------------------------------------------------------------:|------------------------------------------------------------------------------------------------------------------------| | `-gTakeout`,
`--google-takeout` | `` | path | | Path to the Takeout folder (either zipped or unzipped) to process. | | `-gofs`,
`--google-output-folder-suffix` | `` | string | `(default: 'processed')` | Suffix to add to the output folder. | | `-gafs`,
`--google-albums-folders-structure` | `` | string | `flatten`,
`year`,
`year/month`,
`year-month`
`(default: flatten)` | Folder structure for . | | `-gnas`,
`--google-no-albums-folders-structure` | `` | string | `flatten`,
`year`,
`year/month`,
`year-month`
`(default: year/month)` | Folder structure for . | | `-gics`,
`--google-ignore-check-structure` | | flag | | Ignores structure check of Takeout folders. | | `-gnsa`,
`--google-no-symbolic-albums` | | flag | | Duplicates Albums assets instead of create symlinks to original asset in . (requires more HDD space) | | `-grdf`,
`--google-remove-duplicates-files` | | flag | | Removes duplicate files in the output folder. | | `-graf`,
`--google-rename-albums-folders` | | flag | | Renames albums folders based on content dates. | | `-gsef`,
`--google-skip-extras-files` | | flag | | Skips extra Google photos like edited/effects. | | `-gsma`,
`--google-skip-move-albums` | | flag | | Skips moving albums to ``. | | `-gSkipGpth`,
`--google-skip-gpth-tool` | | flag | | Skips GPTH tool processing (not recommended). | | `-gSkipPrep`,
`--google-skip-preprocess` | | flag | | Skips Pre-process Google Takeout folder (not recommended). | | `-gSkipPost`,
`--google-skip-postprocess` | | flag | | Skips Post-process Google Takeout folder (not recommended). | | `-gKeepTakeout`,
`--google-keep-takeout-folder` | | flag | | Keeps a untouched copy of your original Takeout folder. (requires double HDD space). | | `-gpthInfo`,
`--show-gpth-info` | `` | bool | `true`, `false`
`(default: true)` | Show GPTH progress messages. | | `-gpthError`,
`--show-gpth-errors` | `` | bool | `true`, `false`
`(default: true)` | Show GPTH error messages. | | `-gpthNoLog`,
`--gpth-no-log` | | flag | | Skip Save GPTH log messages into output folder. | #### ๐Ÿงช Examples: ```bash PhotoMigrator.bin --google-takeout="/home/user/Takeout" PhotoMigrator.bin --google-takeout="/home/user/Takeout" --google-remove-duplicates-files --google-skip-extras-files PhotoMigrator.bin --google-takeout="/home/user/Takeout" --google-albums-folders-structure=year/month or using short arguments, PhotoMigrator.bin -gTakeout="/home/user/Takeout" -gafs="year/month" -grdf -gsef PhotoMigrator.bin -gTakeout="/home/user/Takeout" -gnsa -gofs="cleaned" PhotoMigrator.bin -gTakeout="/home/user/Takeout" -gics -gKeepTakeout=true ``` --- ## ๐ŸŽ iCloud Takeout Management In this mode, you can use more than one optional arguments and flags from the below list. If only the argument `-iTakeout, --icloud-takeout ` is detected, then the Tool will use the default values for the rest of the flags for this extra mode. Following arguments allow you to interact with Apple iCloud Photos export folders. | Argument | Parameter | Type | Valid Values | Description | |----------------------------------------------------|--------------------------|:------:|:-------------------------------------------------------------------------------------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-iTakeout`,
`--icloud-takeout` | `` | path | | Path to the iCloud export folder (either zipped or unzipped) to process. | | `-iofs`,
`--icloud-output-folder-suffix` | `` | string | `(default: 'processed')` | Suffix to add to the iCloud processed output folder. | | `-iafs`,
`--icloud-albums-folders-structure` | `` | string | `flatten`,
`year`,
`year/month`,
`year-month`
`(default: flatten)` | Folder structure for reconstructed iCloud album folders. | | `-inas`,
`--icloud-no-albums-folders-structure` | `` | string | `flatten`,
`year`,
`year/month`,
`year-month`
`(default: year/month)` | Folder structure for `` generated from iCloud exports. | | `-insa`,
`--icloud-no-symbolic-albums` | | flag | | Duplicate reconstructed iCloud album assets instead of creating symlinks to original assets in ``. By default, `Albums` and `Memories` are built as symlinks. | | `-iMem`,
`--icloud-include-memories` | | flag | | Also reconstruct iCloud `Memories` CSV collections as folders. In the Web Interface, TUI, and GUI this option is pre-selected by default. | | `-iNExif`,
`--icloud-prefer-native-exif-writer` | | flag | | Prefer the native EXIF writer for supported iCloud photo files before falling back to `ExifTool`. In the Web Interface, TUI, and GUI this option is pre-selected by default. | #### ๐Ÿงช Examples: ```bash PhotoMigrator.bin --icloud-takeout="/home/user/iCloudExport" PhotoMigrator.bin --icloud-takeout="/home/user/iCloudExport" --icloud-no-symbolic-albums PhotoMigrator.bin --icloud-takeout="/home/user/iCloudExport" --icloud-include-memories --icloud-albums-folders-structure=year/month PhotoMigrator.bin --icloud-takeout="/home/user/iCloudExport" --icloud-prefer-native-exif-writer or using short arguments, PhotoMigrator.bin -iTakeout="/home/user/iCloudExport" -iofs="cleaned" PhotoMigrator.bin -iTakeout="/home/user/iCloudExport" -iafs="year/month" -inas="year/month" PhotoMigrator.bin -iTakeout="/home/user/iCloudExport" -insa -iMem ``` --- ## ๐Ÿ–ผ๏ธ Google Photos / Synology / Immich / NextCloud Management To use following features, it is mandatory to use the argument `--client=[synology, immich, nextcloud, google-photos]` to specify which Photo Service do you want to use. You can optionally use the argument `--id=[1-3]` to specify the account id for a particular account defined in `Config.ini`. If more than one optional arguments are detected, only the first one will be executed. Following arguments allow you to interact with Google Photos, Synology, Immich, and NextCloud. | Argument | Parameter | Type | Valid Values | Description | |----------------------------------------------------|-------------------------------------------------|:-----------------:|:-------------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-uAlb`,
`--upload-albums` | `` | path | `existing path` | Uploads albums from folders to the selected photo client. | | `-dAlb`,
`--download-albums` | `` | list | `existing album` | Downloads albums by name to the output folder. | | `-uAll`,
`--upload-all` | `` | path | `existing path` | Uploads all assets and creates albums by subfolder. | | `-prefCanAlb`,
`--prefer-canonical-album-names` | | flag | | Normalizes newly created destination album names to the preferred clean keeper form during cloud uploads and Automatic Migration, even when the target does not already contain a similar album (for example `Album_1` -> `Album`, `New_Album 1` -> `New Album`). | | `-consSimAlb`,
`--consolidate-similar-albums` | | flag | | Reuses and consolidates equivalent album families (for example `Album`, `Album_1`, `Album (2)`, `New_Album`, `New Album`, `New_Album 1`) during cloud uploads and Automatic Migration. Supported cloud targets merge redundant variants into the preferred clean keeper. `Immich`, `Synology`, and `NextCloud` then remove the redundant albums; `Google Photos` keeps them because the public API cannot delete albums. | | `-consAlbNames`,
`--consolidate-albums-names` | | flag | | Consolidates equivalent existing cloud album families directly in the target service without uploading new assets. Uses the same family-detection logic as `--consolidate-similar-albums`. `Immich`, `Synology`, and `NextCloud` remove redundant albums afterwards; `Google Photos` keeps them because the public API cannot delete albums. | | `-dAll`,
`--download-all` | `` | path | `existing path` | Downloads all albums and assets to this folder. | | `-renAlb`,
`--rename-albums` | `` `` | `string` `string` | `text / wildcard / regex` | Renames albums using a name pattern. | | `-rAlb`,
`--remove-albums` | `` | string | `text / wildcard / regex` | Removes albums matching name pattern. | | `-prevAlbAct`,
`--preview-album-actions` | | flag | | Previews rename/remove/consolidation matches and asks for confirmation. | | `-rEmpAlb`,
`--remove-empty-albums` | | flag | | Removes empty albums. | | `-rDupAlb`,
`--remove-duplicates-albums` | | flag | | Removes duplicate albums with same name/size. | | `-mDupAlb`,
`--merge-duplicates-albums` | | flag | | Merges duplicate albums (moves all assets). | | `-rAll`,
`--remove-all-assets` | | flag | | Removes all albums and assets from the client. | | `-rAllAlb`,
`--remove-all-albums` | | flag | | Removes all albums from the photo client. | | `-OTP`,
`--one-time-password` | | flag | | Enables / Disables OTP login for Synology (2FA). | #### ๐Ÿงช Examples: ```bash PhotoMigrator.bin --client=immich --upload-all=/mnt/pictures PhotoMigrator.bin --client=synology --download-albums "album1 album2 album3" --output-folder=/mnt/backup PhotoMigrator.bin --client=synology --remove-empty-albums --one-time-password or using short arguments, PhotoMigrator.bin -client=synology -uAlb="Albums" -id=1 PhotoMigrator.bin -client=immich -dAlb="Vacaciones,Navidad" -o="Backups" PhotoMigrator.bin -client=synology -rAlb="tmp_*" -rAlbAsset -OTP ``` --- ## ๐Ÿ› ๏ธ Standalone Features If more than one Feature is detected, only the first one will be executed. Following arguments can be used to execute the Tool in any of the usefully additionals Extra Standalone Features included. | Argument | Parameter | Type | Valid Values | Description | |--------------------------------------------------|------------------------|---------------|:-------------------------------------------------------------------------------------:|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-fixSym` ,
`--fix-symlinks-broken` | `` | path | `existing path` | Fixes broken album symbolic links. | | `-renFldcb`,
`--rename-folders-content-based` | `` | path | `existing path` | Renames folders based on internal dates. | | `-orgDate`,
`--organize-local-folder-by-date` | `` | path | `existing path` | Creates a processed local copy of the input folder and reorganizes its media by date. If `--output-folder` is omitted, the tool creates `__`. | | `-olfs`,
`--organize-output-folder-suffix` | `` | string | `any suffix`
`(default: processed)` | Changes the generated suffix used by `--organize-local-folder-by-date` when no explicit `--output-folder` is provided. Ignored if `--output-folder` is set. | | `-olstr`,
`--organize-folder-structure` | `` | string | `flatten`,
`year`,
`year/month`,
`year-month`
`(default: year/month)` | Selects the folder layout used by `--organize-local-folder-by-date`. | | `-omove`,
`--move-original-files` | | flag | | Used together with `--organize-local-folder-by-date`, move the original files into the destination folder instead of copying them first. | | `-findDup`,
`--find-duplicates` | ` ` | string + list | `move`, `remove`, `list`
+
`[folders]` | Finds duplicate files in the given folders and applies the specified action.

If action is `list`, only the output CSV will be generated and no file will be touched. | | `-procDup`,
`--process-duplicates` | `` | path | `path to .csv` | Processes duplicate file actions from CSV and applies what the action set in Action column for each file. | #### ๐Ÿงช Examples: ```bash PhotoMigrator.bin --fix-symlinks-broken="/mnt/albums" PhotoMigrator.bin --rename-folders-content-based="/mnt/albums" PhotoMigrator.bin --organize-local-folder-by-date="/mnt/unsorted" --organize-folder-structure=year/month PhotoMigrator.bin --organize-local-folder-by-date="/mnt/unsorted" --output-folder="/mnt/organized" PhotoMigrator.bin --organize-local-folder-by-date="/mnt/unsorted" --move-original-files --organize-output-folder-suffix=archive PhotoMigrator.bin --find-duplicates list "/mnt/folder1" "/mnt/folder2" PhotoMigrator.bin --process-duplicates revised_duplicates.csv ``` --- ## ๐Ÿงช Examples description: Below you can find a short description of above examples ### โš™๏ธ General Options ```bash PhotoMigrator.bin --input-folder=/mnt/import --output-folder=/mnt/export Process input folder to fix metadatas and save the result in output folder. ``` ```bash PhotoMigrator.bin --filter-from-date=2022-01-01 --filter-to-date=2022-12-31 Filters assets from 2022 only. ``` ```bash PhotoMigrator.bin --filter-by-type=video --log-level=debug Processes only video files and shows debug logs. ``` --- ### ๐Ÿš€ Automatic Migration ```bash PhotoMigrator.bin --source=immich-1 --target=synology-2 Migrates all content from Immich account 1 to Synology account 2. ``` ```bash PhotoMigrator.bin --source=/mnt/photos --target=/mnt/synology --move-assets=true Migrates local folder to target and removes files from the source. ``` ```bash PhotoMigrator.bin --source=synology-1 --target=immich-1 --parallel-migration=false Uses sequential migration instead of parallel. ``` --- ### ๐Ÿ—ƒ๏ธ Google Takeout Management ```bash PhotoMigrator.bin --google-takeout="/home/user/Takeout" Processes Google Takeout folder using default options. ``` ```bash PhotoMigrator.bin --google-takeout=/home/user/Takeout --google-remove-duplicates-files --google-skip-extras-files Removes duplicates and skips extra photos like effects. ``` ```bash PhotoMigrator.bin --google-takeout=/home/user/Takeout --google-albums-folders-structure=year/month Organizes albums by year and month structure. ``` --- ### ๐Ÿ–ผ๏ธ Synology / Immich Management ```bash PhotoMigrator.bin --client=immich --upload-all=/mnt/pictures Uploads all photos to Immich, organizing by subfolder albums. ``` ```bash PhotoMigrator.bin --client=synology --download-albums "album1 album2 album3" --output-folder=/mnt/backup Downloads selected albums from Synology. ``` ```bash PhotoMigrator.bin --client=synology --remove-empty-albums --one-time-password Removes all empty albums from Synology. ``` --- ### ๐Ÿ› ๏ธ Other Standalone Features ```bash PhotoMigrator.bin --fix-symlinks-broken="/mnt/albums" Fix symbolic links found in the given folder ``` ```bash PhotoMigrator.bin --rename-folders-content-based="/mnt/albums" Renames album folders based on content creation dates. ``` ```bash PhotoMigrator.bin --organize-local-folder-by-date="/mnt/unsorted" --organize-folder-structure=year/month Creates a processed copy of the input folder and organizes media into a year/month structure. ``` ```bash PhotoMigrator.bin --organize-local-folder-by-date="/mnt/unsorted" --output-folder="/mnt/organized" Creates the organized library directly in the explicit output folder, without generating a suffix/timestamp folder name. ``` ```bash PhotoMigrator.bin --organize-local-folder-by-date="/mnt/unsorted" --move-original-files --organize-output-folder-suffix=archive Moves the original files into a generated '_archive_' output folder before reorganizing them by date. ``` ```bash PhotoMigrator.bin --find-duplicates list "/mnt/folder1" "/mnt/folder2" Lists duplicate files across multiple folders. ``` ```bash PhotoMigrator.bin --process-duplicates revised_duplicates.csv Processes duplicates based on a CSV file with actions. ``` --- ## ๐Ÿ  [Back to Main Page](../README.md) --- ## ๐ŸŽ–๏ธ Credits: I hope this can be useful for any of you. Enjoy it! (c) 2024-2026 by Jaime Tur (@jaimetur).