Archive Command Reference

photo-cli archive copies photos into a fixed /year/month/day/ folder hierarchy, embeds a SHA1 hash in every file name to detect duplicates, and records all metadata — date taken, GPS coordinates, and reverse geocode address — into a photo-cli.sqlite3 database in the output folder root. Running the command again on new photos adds only the files that are not already present; duplicates are skipped automatically.

Synopsis

photo-cli archive [options]

How archive differs from copy

Unlike photo-cli copy, the archive command uses a fixed output structure and naming scheme that you cannot override:

Folder structure: always /year/month/day/ — for example, 2008/10/22/.
File names: always yyyy.MM.dd_HH.mm.ss-{sha1hash}.ext — for example, 2008.10.22_16.28.39-5d66eec547469a1817bda4abe35c801359b2bb55.jpg.
Deduplication: two files with the same SHA1 hash are treated as the same photo. The second one is skipped and a warning is printed to the console.
SQLite index: every archived photo is recorded in photo-cli.sqlite3, including all EXIF and geocode fields, so you can query your archive with standard SQL tools.

Because duplicates are detected by file hash rather than file name, you can safely run photo-cli archive repeatedly as you import new photos. Only genuinely new files will be added to the output folder and the SQLite database.

Arguments

Required

--output, -o

string

required

File system path to the archive folder. Created automatically if it does not exist. All year/month/day subfolders and the photo-cli.sqlite3 database will be placed here.

Optional

--input, -i

string

File system path to read photos from. Defaults to the current working directory. No files in this path are ever modified.

--dry-run, -d

boolean

Simulate the archive process without writing any files to disk. No extra value required — pass the flag alone.

--no-taken-date, -t

enum

Action to take when a photo has no EXIF date taken. Photos without a date are placed in a no-photo-taken-date folder named with only the SHA1 hash when Continue is selected.

Name	Value
Continue (default)	0
PreventProcess	1

--no-coordinate, -c

enum

Action to take when a photo has no GPS coordinate.

Name	Value
Continue (default)	0
PreventProcess	1

--expected-day-range, -w

integer

Maximum expected day difference between the earliest and latest photo taken dates. If the range exceeds this value, the process stops before archiving. Useful for preventing accidental archiving of unrelated photo sets.

--album-type, -y

enum

Whether to link archived photos to an album.

Name	Value
NoAlbumLinking (default)	0
Individual	1
DateRange	2

--album-name, -a

string

Name for a new album to create and link the currently archiving photos to. Use with --album-type set to Individual or DateRange.

--update-album, -p

integer

Existing album ID to link the currently archiving photos to. Use with --album-type set to Individual or DateRange. Album IDs can be listed with photo-cli list --type Albums.

--auto-reverse-geocode-album, -s

boolean

Automatically create or update albums for each reverse geocode property level. For example, if you use country city as reverse geocode properties, albums are created for each country and city found. No extra value required — pass the flag alone.

--delete-on-source, -f

boolean

Delete source photo files, companion files, and empty directories after a successful archive operation. No extra value required — pass the flag alone.

This is a destructive operation. Source files are permanently deleted after archiving completes successfully.

--missing-reverse-geocode, -z

enum

Action to take when any photo has missing reverse geocode information.

Name	Value
Continue (default)	0
PreventProcess	1

--language, -l

string

Language/culture value to get localized address results from the reverse geocode provider. See your provider’s documentation for supported values.

--invalid-format, -x

enum

Action to take when a file cannot be parsed as a valid photo format.

Name	Value
Continue (default)	0
PreventProcess	1

--reverse-geocode, -e

enum

Third-party provider used to resolve GPS coordinates into a human-readable address. See reverse geocoding overview for provider setup and API key details.

Name	Value
Disabled (default)	0
BigDataCloud	1
OpenStreetMapFoundation	2
GoogleMaps	3
LocationIq	5

--openstreetmap-properties, -r

string

Space-separated OpenStreetMap address property names used to build the address string. Required when --reverse-geocode is OpenStreetMapFoundation or LocationIq.

--bigdatacloud-levels, -u

string

Space-separated BigDataCloud admin level numbers. Required when --reverse-geocode is BigDataCloud.

--bigdatacloud-key, -b

string

API key for BigDataCloud. Also configurable via the PHOTO_CLI_BIG_DATA_CLOUD_API_KEY environment variable or the BigDataCloudApiKey setting.

--googlemaps-types, -m

string

Space-separated Google Maps address component types. Required when --reverse-geocode is GoogleMaps.

--googlemaps-key, -k

string

API key for Google Maps. Also configurable via the PHOTO_CLI_GOOGLE_MAPS_API_KEY environment variable or the GoogleMapsApiKey setting.

--locationiq-key, -q

string

API key for LocationIq. Also configurable via the PHOTO_CLI_LOCATIONIQ_API_KEY environment variable or the LocationIqApiKey setting.

--has-paid-license, -h

boolean

Bypass the free-tier rate limit when using LocationIq with a paid license.

Example

The following example archives photos with a user-defined album, auto-creates reverse geocode albums, and deletes source files on success.

photo-cli archive \
  --input photos \
  --output archive-folder \
  --album-type DateRange \
  --album-name My-Album \
  --auto-reverse-geocode-album \
  --expected-day-range 7300 \
  --delete-on-source \
  --reverse-geocode OpenStreetMapFoundation \
  --openstreetmap-properties country city

Output folder structure

archive-folder/
├── 2005/
│   ├── 08/
│   │   └── 13/
│   │       └── 2005.08.13_09.47.23-5842c73cfdc5f347551bb6016e00c71bb1393169.jpg
│   └── 12/
│       └── 14/
│           └── 2005.12.14_14.39.47-03cb14d5c68beed97cbe73164de9771d537fcd96.jpg
├── 2008/
│   ├── 07/
│   │   └── 16/
│   │       └── 2008.07.16_11.33.20-90d835861e1aa3c829e3ab28a7f01ec3a090f664.jpg
│   └── 10/
│       └── 22/
│           ├── 2008.10.22_16.28.39-5d66eec547469a1817bda4abe35c801359b2bb55.jpg
│           └── 2008.10.22_17.00.07-a0ab699f5f99fce8ff49163e87c7590c2c9a66eb.jpg
├── 2012/
│   └── 06/
│       └── 22/
│           └── 2012.06.22_19.52.31-bb649a18b3e7bb3df3701587a13f833749091817.jpg
├── 2015/
│   └── 04/
│       └── 10/
│           ├── 2015.04.10_20.12.23-3907fc960f2873f40c8f35643dd444e0468be131.jpg
│           └── 2015.04.10_20.12.23-9f4e6d352ec172e1059571250655e376769080fe.jpg
├── 2025/
│   └── 06/
│       └── 03/
│           ├── 2025.06.03_13.53.36-8a45af72730474e22582afbe72f53685d705a72c.heic
│           └── 2025.06.03_13.53.36-8a45af72730474e22582afbe72f53685d705a72c.mov
├── no-photo-taken-date/
│   └── cf756397cc3ca81b2650c8801fd64e172504015a.jpg
└── photo-cli.sqlite3

Companion files (like .mov from iPhone Live Photos) are automatically copied alongside their parent photo with the same base name. The 2025/06/03 entry above shows a .heic photo with its companion .mov file.

Listing albums after archiving

After archiving with --album-name and --auto-reverse-geocode-album, you can list the created albums:

photo-cli list --input archive-folder --type Albums

This shows both the user-defined album (My-Album) and auto-created reverse geocode albums for each location property level (e.g., Italia, Firenze, Venezia, United Kingdom).

SQLite database

photo-cli.sqlite3 is created in the output folder root and updated on every run. Each row represents one archived photo. You can query it with any SQLite client.

Column	Description
`Id`	Auto-incremented integer primary key
`Path`	Relative path to the archived file within the output folder
`CreatedAt`	UTC timestamp when this record was inserted
`DateTaken`	EXIF date and time the photo was taken
`ReverseGeocodeFormatted`	Human-readable address string
`Latitude`	GPS latitude
`Longitude`	GPS longitude
`Year`	Year component of the taken date
`Month`	Month component of the taken date
`Day`	Day component of the taken date
`Hour`	Hour component of the taken date
`Minute`	Minute component of the taken date
`Seconds`	Seconds component of the taken date
`Address1`–`Address8`	Individual address components from the reverse geocode provider
`Sha1Hash`	SHA1 hash of the file, used for deduplication
`IsDeleted`	Whether the photo has been marked as deleted
`ModifiedAt`	UTC timestamp when this record was last modified

Get Started

Reverse Geocoding

Commands

Copy Examples

Configuration

Reference

Archive Command Reference

Synopsis

How archive differs from copy

Arguments

Required

Optional

Example

Output folder structure

Listing albums after archiving

SQLite database

Get Started

Reverse Geocoding

Commands

Copy Examples

Configuration

Reference

Documentation Index

​Synopsis

​How archive differs from copy

​Arguments

​Required

​Optional

​Example

​Output folder structure

​Listing albums after archiving

​SQLite database

Synopsis

How archive differs from copy

Arguments

Required

Optional

Example

Output folder structure

Listing albums after archiving

SQLite database