A walkthrough of the five things photo-cli is built to do — archive, copy, list/open, export to CSV, and map your photos — each shown end to end with a real command, before/after folders, and what happens behind the scenes.
A few things to note about this set: DSC_1770.JPG and DSC_1770_(same).jpg are byte-for-byte duplicates, Italy album/IMG_2371.jpg has a taken date but no GPS, Spain Journey/IMG_5397.jpg has neither, and IMG_1979.mov / IMG_1979.xmp / IMG_O1979.aae are companion files for the IMG_1979.HEIC Live Photo.
1. Archive into an indexed folder backed by SQLite
The archive command is built for long-term, incremental storage. It always lays photos out as [year]/[month]/[day]/, embeds a SHA1 hash in every file name to prevent duplicates, records every photo (and the albums it belongs to) in a local SQLite database, and — when asked — deletes the source files after verifying every copy. See the archive command reference for every supported argument.
Discovery. photo-cli walked the source folder and found 18 photos and 1 companion file (IMG_1979.mov, the Live Photo clip that travels with IMG_1979.HEIC).
EXIF extraction. For each photo it read the taken date and GPS coordinates.
Reverse geocoding. Coordinates were sent to OpenStreetMap and an address was built from the requested administrative levels (country city). Repeated coordinates were deduplicated in memory so the rate-limited API was only called once per unique location.
Day-range guard.--expected-day-range 7300 rejects archives whose photos span more than ~20 years. This is a safety net to catch a mis-pointed source folder before any copy happens.
Year/month/day layout. Every photo lands in [year]/[month]/[day]/ derived from its EXIF date — for example /2008/10/22/.
SHA1 in the file name. Files are renamed to yyyy.MM.dd_HH.mm.ss-{sha1}.ext (e.g. 2008.07.16_11.33.20-90d835861e1aa3c829e3ab28a7f01ec3a090f664.jpg). Companion files keep their own extension but share the SHA1 stem of their main photo.
Automatic deduplication.DSC_1770.JPG and DSC_1770_(same).jpg hash identically — only one is copied; the other is logged as skipped.
No-date fallback.Spain Journey/IMG_5397.jpg has no taken date, so it goes into no-photo-taken-date/ and is named with only its SHA1.
Copy verification. After copying, photo-cli re-hashes every output file and compares it to the source. A disk error during the copy would be surfaced immediately.
SQLite indexing. All metadata — path, taken date, coordinates, formatted address, individual Address1..Address8 levels, SHA1 — is written to photo-cli.sqlite3 at the root of the archive.
Albums.--album-name My-Album --album-type DateRange creates a user-defined date-range album spanning the earliest and latest photo. --auto-reverse-geocode-album additionally creates one album per geocoded level (e.g. Italia, Italia-Firenze, Venezia, United Kingdom) so you can later open every photo from a country, city, or region without remembering exact dates.
Source cleanup.--delete-on-source removes the source photos, companion files, and now-empty directories — but only after the verification step in step 9 succeeded.
Statistics. A summary table is printed to the terminal: photos found vs. copied vs. skipped, geocode requests sent vs. served from cache, albums created, and so on.
[17:07:27] Searching photo main files: started[17:07:27] Searching photo main files: finished. 18 photo(s) found.[17:07:27] Searching photo companion files: started[17:07:27] Searching photo companion files: finished. 1 companion file(s) found.[17:07:27] No coordinate found on `Gps` directory. Path:</test-photographs/Spain Journey/IMG_5397.jpg>[17:07:27] No coordinate found on `Gps` directory. Path:</test-photographs/Italy album/IMG_2371.jpg>[17:07:28] Calculating file hashes: started[17:07:28] Calculating file hashes: finished.[17:07:28] This OpenStreetMapFoundation provider is using rate limit of 1 second(s) between each request[17:07:28] Reverse Geocoding: started[17:07:31] Requested address types: City on index #2, not found on OpenStreetMap's response. Available types found:{'country_code':'gb','country':'United Kingdom','postcode':'SL4 2DR','suburb':'Sunninghill and Ascot','road':'Windsor Road'}. Path:</test-photographs/GOPR6742.jpg>[17:07:47] Reverse Geocoding: finished.[17:07:47] Directory grouping: started[17:07:47] Directory grouping: finished.[17:07:47] Processing target folder: started[17:07:47] Photo is skipped due to same photo has already been archived. Same photo paths: <test-photographs/Italy album/DSC_1770.JPG>, </test-photographs/Italy album/DSC_1770_(same).jpg>[17:07:47] Processing target folder: finished.[17:07:47] Verified all photo files copied successfully by comparing file hashes from original photo files.[17:07:47] Archiving photos to SQLite: started[17:07:47] Archiving photos to SQLite: finished.[17:07:47] Saving new date range album: started[17:07:47] Saving new date range album: finished.[17:07:47] Saving reverse geocode albums: started[17:07:47] Saving reverse geocode albums: finished.[17:07:47] Deleting source files: started[17:07:47] Deleting source files: finished.[17:07:47] Deleting empty directories: started[17:07:47] Deleting empty directories: finished. Statistics┌────────────────────────────────────────────────┬───────┐│ Statistic │ Count │├────────────────────────────────────────────────┼───────┤│ File System Error(s) │ 0 ││ Photo(s) found │ 18 ││ Photo(s) copied │ 17 ││ Photo(s) existed on the output │ 0 ││ Photo(s) are skipped, they have the same photo │ 1 ││ Directory/directories created │ 8 ││ │ ││ Companion file(s) found │ 1 ││ Companion file(s) copied │ 1 ││ Companion file(s) existed on the output │ 0 ││ │ ││ Source photo file(s) deleted │ 17 ││ Source companion file(s) deleted │ 1 ││ Source empty directory(ies) deleted │ 1 ││ │ ││ User defined album created │ 1 ││ User defined album updated │ 0 ││ Auto address album created │ 15 ││ │ ││ Reverse geocode request sent │ 14 ││ Reverse geocode evaluated from memory │ 2 ││ Reverse geocode evaluated from database │ 0 ││ Photo(s) has taken date and coordinate │ 16 ││ Photo(s) has taken date but no coordinate │ 1 ││ Photo(s) has coordinate but no taken date │ 0 ││ Photo(s) has no taken date and coordinate │ 1 ││ │ ││ Photo(s) has unknown/invalid format │ 0 ││ Photo(s) caused unexpected error internally │ 0 │└────────────────────────────────────────────────┴───────┘[17:07:47] Archive process completed successfully
The archive layout is intentionally fixed — [year]/[month]/[day]/ with SHA1-stamped names — so the same archive folder can be safely re-targeted by future archive runs. New photos slot in cleanly, and any duplicate of a previously archived photo is detected and skipped.
The same archive command runs on macOS, Windows, Linux, and inside a container. Each tab shows the terminal executing the command, the resulting folder in the native file manager, and a tree listing of the archive.
The copy command is the flexible one. Unlike archive, it is configurable end-to-end: you choose the folder structure, the file naming style, whether to flatten or preserve the original hierarchy, what to do with photos missing a date or GPS, and whether to verify the copy. See the copy command reference and the examples gallery for more strategies.
--process-type SubFoldersPreserveFolderHierarchy keeps the same folder layout as the source — Italy album/ stays Italy album/, Spain Journey/ stays Spain Journey/.
--folder-append DayRange --folder-append-location Prefix prefixes each subfolder with the earliest and latest photo dates inside it: Italy album becomes 2005.12.14-2025.06.03-Italy album.
--naming-style DateTimeWithSecondsAddress renames every photo with its taken date plus its reverse-geocoded address: GOPR6742.jpg becomes 2012.06.22_19.52.31-United Kingdom.jpg.
--number-style PaddingZeroCharacter appends -1, -2, … when two photos share the same timestamp-and-address — that is why both Spain photos and both 17:00:07 Italy photos get a numeric suffix.
--no-coordinate InSubFolder / --no-taken-date InSubFolder keeps photos that are missing data — IMG_2371.jpg (no GPS) lands in Italy album/no-address/, IMG_5397.jpg (no GPS, no date) lands in Spain Journey/no-address-and-no-photo-taken-date/.
--verify re-hashes every copied file against its source, then writes the per-file SHA1 list to sha1.lst so you can re-verify later with sha1sum --check sha1.lst.
photo-cli-report.csv is written into the output folder. It lists every photo’s original path, new path, taken date, formatted address, latitude/longitude, and the individual address levels — see the example below.
[17:07:28] Searching photo main files: started[17:07:28] Searching photo main files: finished. 18 photo(s) found.[17:07:28] Searching photo companion files: started[17:07:28] Searching photo companion files: finished. 1 companion file(s) found.[17:07:28] No coordinate found on `Gps` directory. Path:</Users/ac/src/photo-cli/docs/test-photographs/Spain Journey/IMG_5397.jpg>[17:07:28] No coordinate found on `Gps` directory. Path:</Users/ac/src/photo-cli/docs/test-photographs/Italy album/IMG_2371.jpg>[17:07:28] This OpenStreetMapFoundation provider is using rate limit of 1second(s) between each request[17:07:28] Reverse Geocoding: started[17:07:29] Requested address types: City on index #2, not found on OpenStreetMap's response. Available types found:{'country_code':'gb','country':'United Kingdom','postcode':'SL4 2DR','suburb':'Sunninghill and Ascot','road':'Windsor Road'}. Path:</Users/ac/src/photo-cli/docs/test-photographs/GOPR6742.jpg>[17:07:44] Reverse Geocoding: finished.[17:07:44] Directory grouping: started[17:07:44] Directory grouping: finished.[17:07:44] Processing target folder: started[17:07:45] Processing target folder: finished.[17:07:45] Verified all photo files copied successfully by comparing file hashes from original photo files.[17:07:45] All files SHA1 hashes written into file: sha1.lst. You may verify yourself with `sha1sum --check sha1.lst` tool in Linux/macOS.[17:07:45] Writing csv report: started[17:07:45] Writing csv report: finished. Statistics┌────────────────────────────────────────────────┬───────┐│ Statistic │ Count │├────────────────────────────────────────────────┼───────┤│ File System Error(s) │ 0 ││ Photo(s) found │ 18 ││ Photo(s) copied │ 18 ││ Photo(s) existed on the output │ 0 ││ Photo(s) are skipped, they have the same photo │ 0 ││ Directory/directories created │ 4 ││ │ ││ Companion file(s) found │ 1 ││ Companion file(s) copied │ 1 ││ Companion file(s) existed on the output │ 0 ││ │ ││ Source photo file(s) deleted │ 0 ││ Source companion file(s) deleted │ 0 ││ Source empty directory(ies) deleted │ 0 ││ │ ││ User defined album created │ 0 ││ User defined album updated │ 0 ││ Auto address album created │ 0 ││ │ ││ Reverse geocode request sent │ 14 ││ Reverse geocode evaluated from memory │ 2 ││ Reverse geocode evaluated from database │ 0 ││ Photo(s) has taken date and coordinate │ 16 ││ Photo(s) has taken date but no coordinate │ 1 ││ Photo(s) has coordinate but no taken date │ 0 ││ Photo(s) has no taken date and coordinate │ 1 ││ │ ││ Photo(s) has unknown/invalid format │ 0 ││ Photo(s) caused unexpected error internally │ 0 │└────────────────────────────────────────────────┴───────┘[17:07:45] Copy process completed successfully
The copy command never touches the source folder, even with --verify. If you also want the source removed, that is what the archive command’s --delete-on-source is for.
Once you have an archive (from feature 1), the list command can query the SQLite database to find or open photos by date, location, or album. See the list command reference for every filter.
4. Query your photo archive with AI assistants over MCP
The mcp command starts a Model Context Protocol stdio server that exposes your archive’s SQLite database to AI assistants. Once connected, tools like Claude Code, Claude Desktop, and VS Code can search by date, location, album, or proximity to a GPS coordinate — and on macOS, open matching photos directly in Preview. See the mcp command reference for the full tool list and per-client setup.
This launches a stdio MCP server pointing at the archive’s photo-cli.sqlite3. You usually don’t run it by hand — your AI client launches it from its MCP config.
Once connected, ask questions like “What cities and when did I go to Italy?”, “Show me everything taken within 5 km of 43.78, 11.23”, or “Open all photos in the Italia-Firenze album”. The assistant picks the right MCP tool, fills in the parameters, and photo-cli answers from the SQLite index.
Each exposed MCP tool is a typed query against the archive database — list_photos_by_date_range, find_near_location, list_albums, open_photos_by_album_name, and so on. The MCP Inspector view below shows the available tools and their input schemas, which is exactly what the assistant sees when deciding how to answer your question:
When you ask the assistant to open photos rather than just list them, the MCP server hands the matching files off to your OS image viewer. This is wired up for macOS today — matches open directly in Preview. On Linux and Windows the open_photos_* tools are not active yet; use the list_photos_* tools and pipe the returned paths to your viewer of choice.
The info command does no copying at all. It scans a folder, extracts the EXIF data, optionally reverse-geocodes, and writes a single CSV report you can open in Excel, Numbers, LibreOffice, or Google Sheets. See the info command reference.
photo-cli info \ --all-folders \ --output photo-info.csv \ --reverse-geocode OpenStreetMapFoundation \ --openstreetmap-properties country city \ --no-taken-date Continue \ --no-coordinate Continue \ --missing-reverse-geocode Continue
--no-taken-date Continue and --no-coordinate Continue mean photos missing data still appear in the report — just with empty cells in the affected columns.
[17:07:33] Searching photo main files: started[17:07:33] Searching photo main files: finished. 18 photo(s) found.[17:07:33] No coordinate found on `Gps` directory. Path:</Users/ac/src/photo-cli/docs/test-photographs/Spain Journey/IMG_5397.jpg>[17:07:33] No coordinate found on `Gps` directory. Path:</Users/ac/src/photo-cli/docs/test-photographs/Italy album/IMG_2371.jpg>[17:07:33] Reverse Geocoding: started[17:07:33] Requested address types: City on index #2, not found on OpenStreetMap's response. Available types found:{'country_code':'gb','country':'United Kingdom','postcode':'SL4 2DR','suburb':'Sunninghill and Ascot','road':'Windsor Road'}. Path:</Users/ac/src/photo-cli/docs/test-photographs/GOPR6742.jpg>[17:07:49] Reverse Geocoding: finished.[17:07:49] Writing csv report: started[17:07:49] Writing csv report: finished. Statistics┌────────────────────────────────────────────────┬───────┐│ Statistic │ Count │├────────────────────────────────────────────────┼───────┤│ File System Error(s) │ 0 ││ Photo(s) found │ 18 ││ Photo(s) copied │ 0 ││ Photo(s) existed on the output │ 0 ││ Photo(s) are skipped, they have the same photo │ 0 ││ Directory/directories created │ 0 ││ │ ││ Companion file(s) found │ 0 ││ Companion file(s) copied │ 0 ││ Companion file(s) existed on the output │ 0 ││ │ ││ Source photo file(s) deleted │ 0 ││ Source companion file(s) deleted │ 0 ││ Source empty directory(ies) deleted │ 0 ││ │ ││ User defined album created │ 0 ││ User defined album updated │ 0 ││ Auto address album created │ 0 ││ │ ││ Reverse geocode request sent │ 14 ││ Reverse geocode evaluated from memory │ 2 ││ Reverse geocode evaluated from database │ 0 ││ Photo(s) has taken date and coordinate │ 16 ││ Photo(s) has taken date but no coordinate │ 1 ││ Photo(s) has coordinate but no taken date │ 0 ││ Photo(s) has no taken date and coordinate │ 1 ││ │ ││ Photo(s) has unknown/invalid format │ 0 ││ Photo(s) caused unexpected error internally │ 0 │└────────────────────────────────────────────────┴───────┘
6. Navigate your photo locations on Google Maps-Earth
Both the copy and info commands produce a CSV with a row per photo and lat/long columns. That CSV can be imported directly into Google’s mapping tools to navigate your photos on a real map.
