quickstart.mdx

title	Get Started with photo-cli: Archive Photos in Minutes
description	Run your first photo-cli archive command to lay your photos out by year/month/day, hash-stamp every file, deduplicate, index everything in a local SQLite database, and expose the archive to AI assistants over MCP.
sidebarTitle	Quick Start

This guide walks you through installing photo-cli, running your first archive command, and connecting the resulting archive to an AI assistant over MCP. By the end, you will have a [year]/[month]/[day]/ folder of hash-stamped photos, a SQLite index, one album per country/city — and an MCP server for your AI assistant to query & open photos conversationally.

Follow the [Installation](/installation) guide, then verify:

```bash
photo-cli --version
```

```bash photo-cli archive \ --input /path/to/source \ --output /path/to/archive \ --reverse-geocode OpenStreetMapFoundation \ --openstreetmap-properties country city \ --auto-reverse-geocode-album \ ```

<Frame caption='Executing photo-cli archive in the macOS terminal'>
  <img src='/images/screenshots/macos/execute.png' alt='photo-cli archive executing on macOS' />
</Frame>

The command discovers photos and their companion files, reads EXIF metadata (date + GPS), and reverse-geocodes coordinates via OpenStreetMap with in-memory deduplication. It then organizes files into a year/month/day/ layout with SHA1-stamped names, deduplicating identical content and routing dateless photos to a fallback folder.

After copying, it verifies each file by re-hashing, indexes everything (paths, dates, coordinates, addresses, SHA1) into completely local file based database, and builds per-location albums from the geocoded address levels. Open the archive folder. You will find photos laid out as [year]/[month]/[day]/yyyy.MM.dd_HH.mm.ss-{sha1}.ext, byte-for-byte duplicates skipped automatically, photos with no taken date in a no-photo-taken-date/ subfolder, and a photo-cli.sqlite3 database at the root indexing every photo, address, and album.

<Frame caption='The resulting archive in Finder'>
  <img src='/images/screenshots/macos/finder.png' alt='Archive folder open in macOS Finder' />
</Frame>

Query the SQLite index to open photos by date or list every album that was created:

```bash
photo-cli list --input /path/to/archive --type PhotosByDate --year 2008 --month 10
```

On macOS matches open in Preview; on Linux/Windows paths are printed to stdout so you can pipe them to your viewer of choice (e.g., `xargs xdg-open` on Linux).

<Frame caption='photo-cli list opening the October 2008 photos in macOS Preview'>
  <img src='/images/screenshots/macos/viewing-in-preview-app.png' alt='Photos from October 2008 opened in macOS Preview by photo-cli list' />
</Frame>

`photo-cli mcp` starts a [Model Context Protocol](https://modelcontextprotocol.io/) stdio server that exposes the archive's SQLite database to AI assistants. Tools like Claude Code, Claude Desktop, and VS Code can then search by date, location, album, or proximity to a GPS coordinate — and even open matching photos in your default viewer. See the [mcp command reference](/commands/mcp) for the full tool list.

Once connected, ask the assistant things like *'What cities and when did I went to Italy?'*, *'show me everything taken within 5 km of 43.78, 11.23'*, or *'open all photos in the Italia-Firenze album'*.

<Frame caption='MCP integration with Claude Desktop showing a query for photos'>
  <img src='/images/screenshots/mcp/query.png' alt='MCP integration' />
</Frame>

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. Today this is wired up for macOS only — 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.

<Frame caption='Photos opened in macOS Preview after an MCP open_photos_by_album_name call'>
  <img src='/images/screenshots/mcp/view.png' alt='Album photos opened in macOS Preview via the MCP open_photos tool' />
</Frame>

What's next

Explore all commands: copy, archive, list, info, address, settings, and mcp. Install photo-cli on macOS, Windows, or Linux in under a minute. See real before-and-after examples for common organization strategies. Every argument the `archive` command accepts.