CLI Reference
Description
One-way sync engine for the iCloud Photos Library into the native file system with archiving capabilities.
Synopsis
icloud-photos-sync [options] [command]
Use icloud-photos-sync help [command] for information on a specific command. The following commands are available:
Options
data-dir
OPTIONAL | string
Directory to store local copy of library.
- Long Option:
--data-dir - Short Option:
-d - Environment Variable:
DATA_DIR - Default:
/opt/icloud-photos-library
download-threads
OPTIONAL | number
Sets the number of concurrent download threads (Infinity will remove all limitations).
- Long Option:
--download-threads - Short Option:
-t - Environment Variable:
DOWNLOAD_THREADS - Default:
5
download-timeout
OPTIONAL | number
Sets the timeout (in minutes) for downloading assets, because downloads sometimes hang. Should be increased on slower connections and/or if there are large assets in the library (Infinity will remove the timeout).
- Long Option:
--download-timeout - Environment Variable:
DOWNLOAD_TIMEOUT - Default:
10
enable-crash-reporting
OPTIONAL | boolean
Enables automatic collection of errors and crashes, see https://icloud-photos-sync.steilerdev.de/user-guides/error-reporting/ for more information.
- Long Option:
--enable-crash-reporting - Environment Variable:
ENABLE_CRASH_REPORTING - Default:
false
enable-network-capture
OPTIONAL | boolean
Enables network capture, and generate a HAR file for debugging purposes. Written to .icloud-photos-sync.har in the data dir.
- Long Option:
--enable-network-capture - Environment Variable:
ENABLE_NETWORK_CAPTURE - Default:
false
export-metrics
OPTIONAL | boolean
Enables the export of sync metrics to a file using the Influx Line Protocol. Written to .icloud-photos-sync.metrics in the data dir.
- Long Option:
--export-metrics - Environment Variable:
EXPORT_METRICS - Default:
false
fail-on-mfa
OPTIONAL | boolean
If a MFA is necessary, exit the program.
- Long Option:
--fail-on-mfa - Environment Variable:
FAIL_ON_MFA - Default:
false
force
OPTIONAL | boolean
Force the execution of the operation, independent of an existing lock on the library. USE WITH CAUTION!
- Long Option:
--force - Environment Variable:
FORCE - Default:
false
legacy-login
OPTIONAL | boolean
Enables plain text legacy login method.
- Long Option:
--legacy-login - Environment Variable:
LEGACY_LOGIN - Default:
false
log-level
OPTIONAL | level
Set the log level.
- Long Option:
--log-level - Short Option:
-l - Environment Variable:
LOG_LEVEL - Default:
info - Choices:
debug,info,warn,error
log-to-cli
OPTIONAL | boolean
Disables logging to file and logs everything to the console.
- Long Option:
--log-to-cli - Environment Variable:
LOG_TO_CLI - Default:
false
max-retries
OPTIONAL | number
Sets the number of maximum retries upon a sync error (Infinity means that it will always retry).
- Long Option:
--max-retries - Short Option:
-r - Environment Variable:
MAX_RETRIES - Default:
10
metadata-rate
OPTIONAL | interval
Limits the rate of metadata fetching in order to avoid getting throttled by the API. Expects the format <numberOfRequests|Infinity>/<timeInMs>, e.g. 1/20 to limit requests to one request in 20ms.
- Long Option:
--metadata-rate - Environment Variable:
METADATA_RATE - Default:
Infinity/0
password
OPTIONAL | string
AppleID password. Omitting the option will result in the CLI to ask for user input before startup.
- Long Option:
--password - Short Option:
-p - Environment Variable:
APPLE_ID_PWD
port
OPTIONAL | number
Port to listen on when awaiting MFA input.
- Long Option:
--port - Short Option:
-P - Environment Variable:
PORT - Default:
80
refresh-token
OPTIONAL | boolean
Invalidate any stored trust token upon startup.
- Long Option:
--refresh-token - Environment Variable:
REFRESH_TOKEN - Default:
false
region
OPTIONAL | string
Changes the iCloud region.
- Long Option:
--region - Environment Variable:
REGION - Default:
world - Choices:
world,china
remote-delete
OPTIONAL | boolean
If this flag is set, delete non-favorite photos in the iCloud Photos backend upon archiving.
- Long Option:
--remote-delete - Environment Variable:
REMOTE_DELETE - Default:
false
schedule
OPTIONAL | cron-string
In case this app is executed in daemon mode, it will use this cron schedule to perform regular sync operations.
- Long Option:
--schedule - Short Option:
-S - Environment Variable:
SCHEDULE - Default:
0 2 * * *
silent
OPTIONAL | boolean
Disables all output to the console.
- Long Option:
--silent - Short Option:
-s - Environment Variable:
SILENT - Default:
false
suppress-warnings
OPTIONAL | boolean
Non critical warnings will not be displayed in the UI. They will still go into the log.
- Long Option:
--suppress-warnings - Environment Variable:
SUPPRESS_WARNINGS - Default:
false
trust-token
OPTIONAL | string
The trust token for authentication. If not provided, the trust token is read from the .icloud-photos-sync resource file in data dir. If no stored trust token could be loaded, a new trust token will be acquired (requiring the input of an MFA code).
- Long Option:
--trust-token - Short Option:
-T - Environment Variable:
TRUST_TOKEN
username
OPTIONAL | string
AppleID username. Omitting the option will result in the CLI to ask for user input before startup.
- Long Option:
--username - Short Option:
-u - Environment Variable:
APPLE_ID_USER
version
OPTIONAL | boolean
output the version number
- Long Option:
--version - Short Option:
-V
Commands
archive
Archives a given folder. Before archiving, it will first perform a sync, to make sure the correct state is archived.
Usage:
icloud-photos-sync [options] archive [arguments]
Arguments:
path(REQUIRED): Path to the folder that should be archived
daemon
Starts the synchronization in scheduled daemon mode - continuously running based on the provided cron schedule.
Usage:
icloud-photos-sync [options] daemon
sync
Fetches the remote state and persist it to the local disk once.
Usage:
icloud-photos-sync [options] sync
token
Validates the current trust token, fetches a new one (if necessary) and prints it to the CLI.
Usage:
icloud-photos-sync [options] token