Install

macOS and Linux

Terminal

curl -fsSL https://raw.githubusercontent.com/baney75/stillport/main/install.sh | sh

The installer puts stillport in ~/.local/bin, verifies the release's SHA-256 checksum and checks the binary before replacing an existing install. Add export PATH="$HOME/.local/bin:$PATH" to your shell profile if needed. Set STILLPORT_INSTALL_DIR to change the location or STILLPORT_VERSION=vX.Y.Z to pin a release.

Windows

PowerShell

Invoke-WebRequest https://raw.githubusercontent.com/baney75/stillport/v0.2.0/install.ps1 -OutFile install.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -Version v0.2.0

The installer picks x64 or ARM64, verifies the checksum, installs to %LOCALAPPDATA%\Programs\Stillport and adds it to your user PATH. It needs no administrator rights.

Check the install

Terminal

stillport --version
stillport doctor
stillport capabilities

Choose a source

Your photos are…	Start with	What Stillport can do
In Photos on a Mac	`stillport status --source apple`	Native search, previews, rendered or original exports.
In Google Photos	`stillport google pick --open`	A person picks items in Google's Picker; Stillport retrieves only those.
In an extracted Google Takeout archive	`stillport takeout import '/path/to/Google Photos'`	Local index of filenames, captions, dates and folders.

Search Apple Photos

Terminal

stillport search "dogs at the beach" --source apple --limit 10
stillport list --source apple --after 2026-07-01 --before 2026-08-01
stillport albums --source apple
stillport preview 'PHOTO_ID' --source apple --out ./previews
stillport export 'PHOTO_ID' --source apple --original --out ./photos

Queries go to Photos' own search scripting command, so results depend on macOS, Photos and its indexing. On first use, macOS asks you to let your terminal or agent host control Photos under System Settings › Privacy & Security › Automation. Stillport never reads Photos' private database and exposes no editing or deletion. preview makes JPEG stills up to 1600 pixels; export --original may need an iCloud download.

Use the Google Photos Picker

Google no longer lets apps search a user's whole library. Stillport uses the supported Photos Picker API with your own Google Cloud OAuth Desktop client.

Terminal

stillport auth google --client-json ./desktop-client.json
stillport google pick --open
stillport google items 'SESSION_ID'
stillport export 'PHOTO_ID' --source google --session 'SESSION_ID' --out ./photos
stillport google close 'SESSION_ID'

Open the returned Picker link, search and select in Google Photos, then finish. Only selected items are accessible, and sessions expire. Credentials stay in the operating system's credential store.

Index Google Takeout

Terminal

stillport takeout import '/path/to/extracted/Takeout/Google Photos'
stillport search 'beach' --source takeout
stillport gallery --source takeout --query "harbor" --limit 40 --out ./galleries

Stillport reads media and JSON sidecars into a private SQLite index and leaves the archive unchanged. Search covers filenames, captions and folder names; it cannot reproduce Google's people, object or text recognition. If an archive moves, stillport takeout archives lists unavailable folders and stillport takeout forget ARCHIVE_ID removes only that index.

Connect an agent

MCP

Use the absolute path from command -v stillport:

JSON

{
  "mcpServers": {
    "stillport": { "command": "/absolute/path/to/stillport", "args": ["mcp"] }
  }
}

The server exposes provider discovery, search, listing, albums, metadata, previews, exports, galleries, archive recovery and Picker sessions. It does not expose credential management, self-update or archive import. Authenticate Google once with the CLI first.

Codex plugin

Terminal

codex plugin marketplace add baney75/stillport --ref v0.2.0
codex plugin add stillport@stillport-marketplace

Output contract

JSON by default, including errors. --human pretty-prints.
stillport schema describes every command; stillport capabilities explains each source's limits.
Bounded pages with opaque IDs and nextCursor.
Each export goes to a new private folder; nothing is overwritten or uploaded.
Exit codes: 0 success, 1 failure, 2 input, 3 permission or platform, 4 not found, 5 temporary provider failure.

Update and roll back

Terminal

stillport update --check
stillport update

The updater verifies checksums and replaces the binary atomically, keeping the previous one as stillport.previous. To roll back on macOS or Linux, copy stillport.previous over stillport. Checksums verify release integrity; they are not publisher signatures, and the macOS binaries are not notarized.