photo-cli copy reads photos from an input folder, renames and reorganizes them into a new output folder using each photo’s EXIF date taken and optional GPS reverse geocode address, then writes a CSV report summarizing every file processed. Your source folder is never touched.
Synopsis
Key behavior
- Reads all photos from the input folder (or the current directory if
--inputis omitted). - Copies each photo to the output folder with a new name and folder structure derived from EXIF metadata.
- Photos with missing dates or coordinates are handled according to the
--no-taken-dateand--no-coordinateflags rather than silently dropped. - Generates
photo-cli-report.csvin the output folder root after every run. - Never modifies, moves, or deletes files in the input folder.
Add
--dry-run (-d) to simulate the entire process without writing any files to disk. A separate photo-cli-dry-run.csv report is produced so you can review what would happen before committing.Required arguments
File system path where the new organized folder will be created. The folder is created automatically if it does not already exist.
Controls how photos are read from the input folder and how the output folder hierarchy is structured.
Number formatting used when
--naming-style is Numeric or when disambiguating photos that share the same generated name.Optional arguments
File system path to read photos from. Defaults to the current working directory. No files in this path are ever modified.
Simulate the copy process without writing any files to the output folder. No extra value required — pass the flag alone.
Groups photos into date- or address-based subfolders. Cannot be used when
--process-type is SubFoldersPreserveFolderHierarchy.Appends date range or address information to folder names cloned from the source hierarchy. Must be combined with
--folder-append-location. Only applies when --process-type is SubFoldersPreserveFolderHierarchy.Controls whether the appended string is placed before or after the original folder name. Must be combined with
--folder-append.Verifies every copied file by comparing its SHA1 hash against the original. All hashes are also written to
sha1.lst in the output folder so you can re-verify later with sha1sum --check sha1.lst.Maximum expected day difference between the earliest and latest photo taken dates. If the range exceeds this value, the process stops before copying.
Third-party provider used to resolve GPS coordinates into a human-readable address. See reverse geocoding overview for provider setup and API key details.
Space-separated OpenStreetMap address property names used to build the address string. Required when
--reverse-geocode is OpenStreetMapFoundation or LocationIq. Example: country city town suburb. Use photo-cli address to discover available property names for a given photo.Space-separated BigDataCloud admin level numbers used to build the address string. Required when
--reverse-geocode is BigDataCloud.API key for BigDataCloud. You can also set this via the
PHOTO_CLI_BIG_DATA_CLOUD_API_KEY environment variable or the BigDataCloudApiKey setting.Space-separated Google Maps address component types. Required when
--reverse-geocode is GoogleMaps.API key for Google Maps. You can also set this via the
PHOTO_CLI_GOOGLE_MAPS_API_KEY environment variable or the GoogleMapsApiKey setting.API key for LocationIq. You can also set this via the
PHOTO_CLI_LOCATIONIQ_API_KEY environment variable or the LocationIqApiKey setting.Language/culture value to get localized address results from the reverse geocode provider. See your provider’s documentation for supported values.
Example
The following command preserves your existing folder hierarchy, renames each file with its date and address, prefixes each folder with the date range of photos inside it, and routes photos with missing data into dedicated subfolders.Console output
Folder structure before and after
CSV report
After every run,photo-cli-report.csv is created in the output folder root. It contains one row per photo with the following columns:
You can open this file in any spreadsheet application (Excel, Google Sheets, LibreOffice Calc, Apple Numbers) or import it into Google My Maps or Google Earth for location exploration.