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.

photo-cli list queries the SQLite database created by photo-cli archive and displays photo metadata or opens matching photos directly in your default viewer. You can filter by album, exact date, or date range.

​
Synopsis

photo-cli list [options]

​
Prerequisites

The list command works only on folders created by photo-cli archive. The folder must contain a photo-cli.sqlite3 database.

​
Arguments

​
Optional

​
--input, -i
string
Path to the archive folder containing the photo-cli.sqlite3 database. Defaults to the current working directory.
​
--type, -t
enum
The type of listing to display. Determines which data is queried and how results are presented.
NameValue
Summary (default)0
Albums1
PhotosByAlbumId2
PhotosByAlbumName3
PhotosByExactDate4
PhotosByDateRange5
​
--id, -n
integer
Album ID to filter photos. Required when --type is PhotosByAlbumId. Album IDs can be found by running photo-cli list --type Albums.
​
--name, -a
string
Album name to filter photos. Required when --type is PhotosByAlbumName.
​
--year, -y
integer
Year to filter photos. Used when --type is PhotosByExactDate.
​
--month, -m
integer
Month to filter photos. Used when --type is PhotosByExactDate.
​
--day, -d
integer
Day to filter photos. Used when --type is PhotosByExactDate.
​
--start-date, -s
string
Start date (inclusive) in yyyy-MM-dd format. Required when --type is PhotosByDateRange.
​
--end-date, -e
string
End date (inclusive) in yyyy-MM-dd format. Required when --type is PhotosByDateRange.
​
--raw, -r
boolean
Output photo paths as plain text (one per line) instead of opening them in the default OS viewer. Useful for piping to other tools. No extra value required — pass the flag alone.

​
List types explained

​
Summary (default)

Shows total counts of albums, photos, and reverse geocode cache entries in the archive. 
photo-cli list --input archive-folder

​
Albums

Lists all albums with their ID, name, type, creation date, and configuration. 
photo-cli list --input archive-folder --type Albums

​
Photos by album ID

Lists or opens photos belonging to a specific album, identified by its numeric ID. 
photo-cli list --input archive-folder --type PhotosByAlbumId --id 1

​
Photos by album name

Lists or opens photos belonging to a specific album, identified by name. 
photo-cli list --input archive-folder --type PhotosByAlbumName --name "Italia"

​
Photos by exact date

Lists or opens photos filtered by year, month, and/or day. All date parameters are optional — you can filter by year alone, year and month, or all three. 
photo-cli list --input archive-folder --type PhotosByExactDate --year 2008 --month 10

​
Photos by date range

Lists or opens photos taken within an inclusive date range. 
photo-cli list --input archive-folder --type PhotosByDateRange --start-date 2025-09-21 --end-date 2026-01-30

​
Photo viewing behavior

On macOS, matching photos are opened directly in the Preview app. On Windows and Linux, photo file paths are printed to the console (one per line) since there is no universal default photo viewer. You can pipe these paths to your preferred viewer. Use the --raw flag on any platform to force plain-text path output instead of opening the viewer.
Instead of option names (e.g., PhotosByExactDate), you can use the numeric values (e.g., 4). You can also use relative folder paths — if your working directory is the archive folder, you can omit the --input argument entirely.