Usage¶
sproutpal [--sync] [--update] [--full] [--batchsize N] [--maxbatches N] [--gps LAT,LON] [--dry-run]
At least one of --sync and --update is required.
Credentials¶
Credentials come from flags or from environment variables. Use the
environment variables: flags are visible to other users in ps.
| Variable | Flag |
|---|---|
SPROUTPAL_SPROUTEMAIL |
--sproutemail |
SPROUTPAL_SPROUTPSWD |
--sproutpswd |
SPROUTPAL_IMMICHSERVER |
--immichserver |
SPROUTPAL_IMMICHKEY |
--immichkey |
Keep them in a file only you can read, for example
~/.config/sproutpal/sproutpal.env (chmod 600), one NAME=value per line.
The systemd units load that file.
Immich API key¶
Create a key in Immich (Account Settings → API Keys) with exactly these permissions:
asset.read: find media already in Immich by file name. Without it, sproutpal downloads everything to compare checksums.asset.upload: uploads and the duplicate check.asset.update: date, description and location.tag.create,tag.asset: tags.user.read: optional, a startup check of who owns the key.
Warning: do not grant "all" permissions.
Options¶
| Option | What it does |
|---|---|
--sync |
Upload media that Immich does not have yet, with date, description and tags. |
--update |
Rewrite date, description and tags on media already in Immich, including copies saved from your phone. |
--full |
Scan every batch. Without it, the run stops at the first batch with nothing new to upload. Media are newest first, so everything older is already in Immich. |
--batchsize N |
Media per batch (default 100). Each batch is downloaded, uploaded, tagged, and deleted from disk before the next one. |
--maxbatches N |
Stop after N batches. Use it for test runs. |
--gps LAT,LON |
Set this location on every asset, in decimal degrees. |
--dry-run |
Read only. Print what would change and write nothing. |
--version |
Print the version and exit. |
Exit codes¶
| Code | Meaning |
|---|---|
0 |
The run finished and nothing failed. |
1 |
One or more items failed, or a hard error stopped the run. The next run tries the failed items again. |
2 |
Usage error: a flag or a credential is missing or wrong. |
Examples¶
# First look: one small batch, nothing written
sproutpal --sync --dry-run --maxbatches 1 --batchsize 10
# First full sync
sproutpal --sync --full
# Regular run: new media only, stops early
sproutpal --sync
# Refresh descriptions and tags on everything, including phone copies
sproutpal --sync --update --full