Skip to main content

Documentation Index

Fetch the complete documentation index at: https://photocli.com/llms.txt

Use this file to discover all available pages before exploring further.

This example groups photos into a country/city/town folder hierarchy based on their GPS coordinates, and names each file with the taken date and address. The original folder structure is discarded entirely; the new structure comes from the locations embedded in the photo EXIF data.

​
Command

photo-cli copy \
  --process-type FlattenAllSubFolders \
  --group-by AddressHierarchy \
  --naming-style DayAddress \
  --reverse-geocode OpenStreetMapFoundation \
  --openstreetmap-properties country city town suburb \
  --number-style OnlySequentialNumbers \
  --no-taken-date AppendToEndOrderByFileName \
  --no-coordinate InSubFolder \
  --input photos \
  --output organized-albums

​
Key arguments

ArgumentValueWhat it does
--process-typeFlattenAllSubFoldersIgnores the original folder hierarchy and pools all photos together before grouping.
--group-byAddressHierarchyCreates nested output folders from the address components: [country]/[city]/[town].
--naming-styleDayAddressNames each file as {yyyy.MM.dd}-{address}.ext, with the date followed by the address.
--reverse-geocodeOpenStreetMapFoundationUses the OpenStreetMap Nominatim API to resolve GPS coordinates into address fields.
--openstreetmap-propertiescountry city town suburbSelects which address fields to use when building folder names and file names.
--number-styleOnlySequentialNumbersAppends -1, -2, etc. to disambiguate files that would otherwise share the same name.
--no-taken-dateAppendToEndOrderByFileNamePhotos with no taken date are appended at the end of their folder, ordered by original file name.
--no-coordinateInSubFolderPhotos with no GPS coordinate are placed in a no-address subfolder at the root of the output.

​
Before and after

Before (photos/): 
├── DSC_5727.jpg
├── GOPR6742.jpg
├── Italy album
│   ├── DJI_01732.jpg
│   ├── DJI_01733.jpg
│   ├── DSC00001.JPG
│   ├── DSC03467.jpg
│   ├── DSC_1769.JPG
│   ├── DSC_1770.JPG
│   ├── DSC_1770_(same).jpg
│   ├── DSC_1771.JPG
│   ├── GOPR7496.jpg
│   ├── GOPR7497.jpg
│   ├── IMG_0747.JPG
│   └── IMG_2371.jpg
└── Spain Journey
    ├── DSC_1807.jpg
    ├── DSC_1808.jpg
    └── IMG_5397.jpg

2 directories, 17 files
After (organized-albums/): 
├── España
│   └── Madrid
│       ├── 2015.04.10-España-Madrid-1.jpg
│       └── 2015.04.10-España-Madrid-2.jpg
├── Italia
│   ├── Arezzo
│   │   ├── 2008.10.22-Italia-Arezzo-1.jpg
│   │   ├── 2008.10.22-Italia-Arezzo-2.jpg
│   │   ├── 2008.10.22-Italia-Arezzo-3.jpg
│   │   ├── 2008.10.22-Italia-Arezzo-4.jpg
│   │   ├── 2008.10.22-Italia-Arezzo-5.jpg
│   │   ├── 2008.10.22-Italia-Arezzo-6.jpg
│   │   ├── 2008.10.22-Italia-Arezzo-7.jpg
│   │   ├── 2008.10.22-Italia-Arezzo-8.jpg
│   │   ├── 2008.10.22-Italia-Arezzo-9.jpg
│   │   └── 2008.10.22-Italia-Arezzo-10.jpg
│   └── Firenze
│       └── Quartiere 1
│           └── 2005.12.14-Italia-Firenze-Quartiere 1.jpg
├── Kenya
│   └── 2005.08.13-Kenya.jpg
├── no-address
│   ├── IMG_2371.jpg
│   └── IMG_5397.jpg
├── photo-cli-report.csv
└── United Kingdom
    └── Ascot
        └── Sunninghill and Ascot
            └── 2012.06.22-United Kingdom-Ascot-Sunninghill and Ascot.jpg

11 directories, 18 files

​
What you see in the output

Photos are organized by location, not by their original album names. All ten Arezzo photos from the Italy album land in Italia/Arezzo/, named 2008.10.22-Italia-Arezzo-1.jpg through 2008.10.22-Italia-Arezzo-10.jpg. The one Florence photo goes into Italia/Firenze/Quartiere 1/. The two Madrid photos from Spain Journey land in España/Madrid/. The folder depth matches the number of distinct address levels returned by OpenStreetMap for each location. A single photo taken in Kenya resolves to only a country, so its folder is Kenya/ with no city or town sub-level.
Two photos land in no-address/: Italy album/IMG_2371.jpg has a taken date but no GPS coordinate, and Spain Journey/IMG_5397.jpg has neither a date nor a coordinate. Both are placed in no-address/ at the root of the output because --no-coordinate InSubFolder routes GPS-less photos there. Their original file names are preserved.
Combine this strategy with --folder-append DayRange and --folder-append-location Suffix to also show date ranges on each location folder. For example, Arezzo would become Arezzo-2008.10.22-2008.10.22. This gives you both geographic and temporal context in the folder listing.