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
Prerequisites
Thelist command works only on folders created by photo-cli archive. The folder must contain a photo-cli.sqlite3 database.
Arguments
Optional
string
Path to the archive folder containing the
photo-cli.sqlite3 database. Defaults to the current working directory.enum
The type of listing to display. Determines which data is queried and how results are presented.
integer
Album ID to filter photos. Required when
--type is PhotosByAlbumId. Album IDs can be found by running photo-cli list --type Albums.string
Album name to filter photos. Required when
--type is PhotosByAlbumName.integer
Year to filter photos. Used when
--type is PhotosByExactDate.integer
Month to filter photos. Used when
--type is PhotosByExactDate.integer
Day to filter photos. Used when
--type is PhotosByExactDate.string
Start date (inclusive) in
yyyy-MM-dd format. Required when --type is PhotosByDateRange.string
End date (inclusive) in
yyyy-MM-dd format. Required when --type is PhotosByDateRange.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.
string
Custom file system path directly to the SQLite database file, bypassing the default database location within the archive folder. When provided, the database is read from this exact path instead of
[archive-folder]/photo-cli.sqlite3.List types explained
Summary (default)
Shows total counts of albums, photos, and reverse geocode cache entries in the archive.Albums
Lists all albums with their ID, name, type, creation date, and configuration.Photos by album ID
Lists or opens photos belonging to a specific album, identified by its numeric ID.Photos by album name
Lists or opens photos belonging to a specific album, identified by name.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.Photos by date range
Lists or opens photos taken within an inclusive date range.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.