> ## Documentation Index
> Fetch the complete documentation index at: https://photocli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Complete photo-cli Command-Line Arguments Reference

> Complete reference for every command-line argument accepted by photo-cli, including short flags, long flags, applicable commands, and accepted values.

This page is a complete reference for all command-line arguments accepted by photo-cli. Each entry lists the short flag, the long flag, which commands accept it, and the full set of accepted values. Arguments marked **REQUIRED** must be supplied for the command to run; all others are optional.

<AccordionGroup>
  <Accordion title="Input & output">
    **`-i` / `--input`**

    Applies to: `copy`, `archive`, `info` (optional); `address` (required)

    File system path to read photos from. If you omit this argument for `copy`, `archive`, and `info`, photo-cli uses the current working directory. The source path is never modified.

    ***

    **`-o` / `--output`**

    Applies to: `copy`, `archive`, `info` (required for all three)

    File system path to write output. For `copy` and `archive`, photo-cli creates a new organized folder hierarchy at this location with renamed files. For `info`, this is the path where the CSV report is written. The folder is created automatically if it does not exist.
  </Accordion>

  <Accordion title="Folder organization (copy only)">
    **`-f` / `--process-type`** — REQUIRED for `copy`

    Controls whether photo-cli uses the original folder hierarchy or flattens photos into a single grouped folder.

    | Value | Name                                |
    | ----- | ----------------------------------- |
    | `1`   | `Single`                            |
    | `2`   | `SubFoldersPreserveFolderHierarchy` |
    | `3`   | `FlattenAllSubFolders`              |

    ***

    **`-g` / `--group-by`**

    Applies to: `copy` (cannot be combined with `SubFoldersPreserveFolderHierarchy`)

    Groups photos into subfolders by their EXIF data.

    | Value | Name               |
    | ----- | ------------------ |
    | `1`   | `YearMonthDay`     |
    | `2`   | `YearMonth`        |
    | `3`   | `Year`             |
    | `4`   | `Address`          |
    | `5`   | `AddressFlat`      |
    | `6`   | `AddressHierarchy` |

    ***

    **`-a` / `--folder-append`**

    Applies to: `copy` with `SubFoldersPreserveFolderHierarchy`. Must be combined with `--folder-append-location`.

    Appends a date or address token to the original folder name.

    | Value | Name                     |
    | ----- | ------------------------ |
    | `1`   | `FirstYearMonthDay`      |
    | `2`   | `FirstYearMonth`         |
    | `3`   | `FirstYear`              |
    | `4`   | `DayRange`               |
    | `5`   | `MatchingMinimumAddress` |

    ***

    **`-p` / `--folder-append-location`**

    Applies to: `copy`. Required when `--folder-append` is used.

    Controls whether the appended token appears before or after the original folder name.

    | Value | Name     |
    | ----- | -------- |
    | `1`   | `Prefix` |
    | `2`   | `Suffix` |
  </Accordion>

  <Accordion title="File naming (copy only)">
    **`-s` / `--naming-style`** — REQUIRED for `copy`

    The naming strategy applied to each copied photo file.

    | Value | Name                         |
    | ----- | ---------------------------- |
    | `1`   | `Numeric`                    |
    | `2`   | `Day`                        |
    | `3`   | `DateTimeWithMinutes`        |
    | `4`   | `DateTimeWithSeconds`        |
    | `5`   | `Address`                    |
    | `6`   | `DayAddress`                 |
    | `7`   | `DateTimeWithMinutesAddress` |
    | `8`   | `DateTimeWithSecondsAddress` |
    | `9`   | `AddressDay`                 |
    | `10`  | `AddressDateTimeWithMinutes` |
    | `11`  | `AddressDateTimeWithSeconds` |

    ***

    **`-n` / `--number-style`** — REQUIRED for `copy`

    The numbering strategy used for the `Numeric` naming style and for disambiguating photos that would otherwise share the same output name.

    | Value | Name                    |
    | ----- | ----------------------- |
    | `1`   | `AllNamesAreSameLength` |
    | `2`   | `PaddingZeroCharacter`  |
    | `3`   | `OnlySequentialNumbers` |
  </Accordion>

  <Accordion title="Archive: albums & source management">
    **`-y` / `--album-type`**

    Applies to: `archive`

    Whether to link archived photos to an album.

    | Value | Name                       |
    | ----- | -------------------------- |
    | `0`   | `NoAlbumLinking` (default) |
    | `1`   | `Individual`               |
    | `2`   | `DateRange`                |

    ***

    **`-a` / `--album-name`**

    Applies to: `archive`

    Name for a new album to create and link the currently archiving photos to. Use with `--album-type` set to `Individual` or `DateRange`.

    ***

    **`-p` / `--update-album`**

    Applies to: `archive`

    Existing album ID to link the currently archiving photos to. Use with `--album-type` set to `Individual` or `DateRange`.

    ***

    **`-s` / `--auto-reverse-geocode-album`**

    Applies to: `archive`

    Automatically create or update albums for each reverse geocode property level. No additional value needed.

    ***

    **`-f` / `--delete-on-source`**

    Applies to: `archive`

    Delete source photo files, companion files, and empty directories after a successful archive. No additional value needed.
  </Accordion>

  <Accordion title="Missing data handling">
    **`-t` / `--no-taken-date`**

    Action to take when a photo has no EXIF taken date. Default is `Continue` (`0`).

    For `copy`:

    | Value | Name                               |
    | ----- | ---------------------------------- |
    | `0`   | `Continue` (default)               |
    | `1`   | `PreventProcess`                   |
    | `2`   | `DontCopyToOutput`                 |
    | `3`   | `InSubFolder`                      |
    | `4`   | `AppendToEndOrderByFileName`       |
    | `5`   | `InsertToBeginningOrderByFileName` |

    For `archive` and `info`:

    | Value | Name                 |
    | ----- | -------------------- |
    | `0`   | `Continue` (default) |
    | `1`   | `PreventProcess`     |

    ***

    **`-c` / `--no-coordinate`**

    Action to take when a photo has no GPS coordinates. Default is `Continue` (`0`).

    For `copy`:

    | Value | Name               |
    | ----- | ------------------ |
    | `0`   | `Continue`         |
    | `1`   | `PreventProcess`   |
    | `2`   | `DontCopyToOutput` |
    | `3`   | `InSubFolder`      |

    For `archive` and `info`:

    | Value | Name             |
    | ----- | ---------------- |
    | `0`   | `Continue`       |
    | `1`   | `PreventProcess` |

    ***

    **`-x` / `--invalid-format`**

    Action to take when a file cannot be parsed as a valid photo format. Default is `Continue` (`0`).

    For `copy`:

    | Value | Name                 |
    | ----- | -------------------- |
    | `0`   | `Continue` (default) |
    | `1`   | `PreventProcess`     |
    | `2`   | `DontCopyToOutput`   |
    | `3`   | `InSubFolder`        |

    For `archive` and `info`:

    | Value | Name                 |
    | ----- | -------------------- |
    | `0`   | `Continue` (default) |
    | `1`   | `PreventProcess`     |

    ***

    **`-z` / `--missing-reverse-geocode`**

    Applies to: `archive`, `copy`, `info`

    Action to take when any photo has missing reverse geocode information. Default is `Continue` (`0`).

    | Value | Name                 |
    | ----- | -------------------- |
    | `0`   | `Continue` (default) |
    | `1`   | `PreventProcess`     |

    ***

    **`-w` / `--expected-day-range`**

    Applies to: `archive`, `copy`

    Maximum expected day difference between the earliest and latest photo taken dates. If exceeded, the process stops.
  </Accordion>

  <Accordion title="Reverse geocoding">
    **`-e` / `--reverse-geocode`**

    Applies to: `copy`, `archive`, `info` (optional); `address` (required)

    The third-party provider to use for resolving GPS coordinates into human-readable addresses.

    | Value | Name                      |
    | ----- | ------------------------- |
    | `0`   | `Disabled`                |
    | `1`   | `BigDataCloud`            |
    | `2`   | `OpenStreetMapFoundation` |
    | `3`   | `GoogleMaps`              |
    | `5`   | `LocationIq`              |

    ***

    **`-b` / `--bigdatacloud-key`**

    API key for BigDataCloud. Alternatively, set the environment variable `PHOTO_CLI_BIG_DATA_CLOUD_API_KEY`.

    ***

    **`-u` / `--bigdatacloud-levels`**

    Required when `BigDataCloud` is the selected provider. Space-separated integer admin level values that determine which address components to include. Run `photo-cli address` against a photo to see the full response and identify the levels you need.

    ***

    **`-k` / `--googlemaps-key`**

    API key for Google Maps. Alternatively, set the environment variable `PHOTO_CLI_GOOGLE_MAPS_API_KEY`.

    ***

    **`-m` / `--googlemaps-types`**

    Required when `GoogleMaps` is the selected provider. Space-separated Google Maps address type names. Run `photo-cli address` against a photo to see the full response.

    ***

    **`-r` / `--openstreetmap-properties`**

    Required when `OpenStreetMapFoundation` or `LocationIq` is the selected provider. Space-separated OpenStreetMap property names. Run `photo-cli address` against a photo to see the full response.

    ***

    **`-q` / `--locationiq-key`**

    API key for LocationIq. Alternatively, set the environment variable `PHOTO_CLI_LOCATIONIQ_API_KEY`.

    ***

    **`-h` / `--has-paid-license`**

    Pass this flag to bypass the free-tier rate limit when you have a paid LocationIq license. No additional value is needed.

    ***

    **`-l` / `--language`**

    Applies to: `archive`, `copy`, `info`, `address`

    Language/culture value to get localized address results from the reverse geocode provider.
  </Accordion>

  <Accordion title="Utilities">
    **`-d` / `--dry-run`**

    Applies to: `copy`, `archive`

    Simulates the full process without writing any files to the output folder. The CSV report is still generated so you can review what would happen. No additional value is needed.

    ***

    **`-v` / `--verify`**

    Applies to: `copy`

    After copying, verifies that each photo was transferred without corruption by comparing file hashes between source and destination. No additional value is needed.

    ***

    **`-a` / `--all-folders`**

    Applies to: `info`

    Scans all subfolders recursively instead of only the top-level input folder.
  </Accordion>

  <Accordion title="address command">
    **`-t` / `--type`** — REQUIRED for `address`

    Controls how much of the reverse geocode response is returned.

    | Value | Name                     |
    | ----- | ------------------------ |
    | `0`   | `AllAvailableProperties` |
    | `1`   | `SelectedProperties`     |
    | `2`   | `FullResponse`           |
  </Accordion>

  <Accordion title="list command">
    **`-t` / `--type`**

    The type of listing to display from the archive database.

    | Value | Name                |
    | ----- | ------------------- |
    | `0`   | `Summary` (default) |
    | `1`   | `Albums`            |
    | `2`   | `PhotosByAlbumId`   |
    | `3`   | `PhotosByAlbumName` |
    | `4`   | `PhotosByExactDate` |
    | `5`   | `PhotosByDateRange` |

    ***

    **`-n` / `--id`**

    Album ID to filter photos when using list type `PhotosByAlbumId`.

    ***

    **`-a` / `--name`**

    Album name to filter photos when using list type `PhotosByAlbumName`.

    ***

    **`-y` / `--year`**

    Year to filter photos when using list type `PhotosByExactDate`.

    ***

    **`-m` / `--month`**

    Month to filter photos when using list type `PhotosByExactDate`.

    ***

    **`-d` / `--day`**

    Day to filter photos when using list type `PhotosByExactDate`.

    ***

    **`-s` / `--start-date`**

    Start date (inclusive) in `yyyy-MM-dd` format for `PhotosByDateRange`.

    ***

    **`-e` / `--end-date`**

    End date (inclusive) in `yyyy-MM-dd` format for `PhotosByDateRange`.

    ***

    **`-r` / `--raw`**

    Output photo paths as plain text instead of opening them in the default viewer. No additional value needed.
  </Accordion>

  <Accordion title="mcp command">
    **`-i` / `--input`**

    Path to the archive folder containing the `photo-cli.sqlite3` database. Defaults to the current working directory.
  </Accordion>
</AccordionGroup>