flickr-cli

Agent-friendly Flickr CLI for photo management, backup, upload, and API access.

flickr-cli is a single-binary toolkit for maintaining a Flickr library: inspect metadata, upload folders, back up originals, manage albums, use checksum dedupe, migrate from Piwigo, and call raw Flickr API methods when needed.

Highlights

• Single binary: no runtime, containers, or sidecar service required
• 47 commands across photos, albums, favorites, galleries, groups, comments, contacts, stats, URLs, checksums, cache, Piwigo import, and raw API access
• JSON-first output with a consistent envelope for scripts and agents
• Safety gates for remote mutations: --read-only, --dry-run, and --confirm
• NDJSON progress events on stderr for long uploads and backups

Why

Photo libraries need repeatable operations more than one-off browser sessions. flickr-cli keeps uploads, backups, metadata edits, and migrations scriptable while protecting remote mutations with explicit safety gates.

Quickstart

Install

Run the following on macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/thedavidweng/flickr-cli/main/install.sh | sh

Run the following on Windows:

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/thedavidweng/flickr-cli/main/install.ps1 | iex"

The installer detects Homebrew automatically and uses it when available (recommended for easy upgrades). Otherwise it downloads the binary to ~/.local/bin.

Other installation methods

Homebrew Cask (macOS/Linux):

brew install --cask thedavidweng/tap/flickr

Go:

go install github.com/thedavidweng/flickr-cli/cmd/flickr@latest

Manual download: grab the archive for your platform from the latest GitHub Release, extract it, and place the flickr binary on your PATH.

Build from source:

git clone https://github.com/thedavidweng/flickr-cli.git
cd flickr-cli
make build

Set up

flickr auth login --perms write
flickr doctor

Then try it:

flickr albums list
flickr photos upload ./vacation/ --recursive --album "Summer 2026"
flickr photos download --all --dest ./backup --layout id-dirs

Uninstall

# Homebrew Cask
brew uninstall --cask thedavidweng/tap/flickr

# install.sh
curl -fsSL https://raw.githubusercontent.com/thedavidweng/flickr-cli/main/install.sh | sh -s uninstall

# Go
rm "$(go env GOPATH)/bin/flickr"

Remove config if desired: rm -rf ~/.config/flickr-cli

Documentation

Docs are organized by the Diátaxis taxonomy — see docs/README.md for the map and writing conventions.

Tutorials — a guided first session:

• Your first library session — install to first upload, with previews at every step

How-to guides — recipes for concrete goals:

• Back up your library — full and incremental downloads of everything
• Upload without duplicates — checksum dedupe for imports and re-runs
• Organize albums — create, fill, rename, and delete albums safely
• Automate with JSON — scripting, agents, exit codes, NDJSON events
• Call any API method — raw flickr.* escape hatch
• Migrate from Piwigo — import a self-hosted gallery

Reference — exact facts, lookup-oriented:

• Command Reference — all commands with flags and safety gates
• JSON Schema — envelope format, error codes, exit-code mapping

Explanation — why it works this way:

• Safety gates — --read-only, --dry-run, --confirm, audit log
• Architecture — package layout and design decisions

Infrastructure

• CI/CD: GitHub Actions + mise
• Docs: site — landing page and documentation

License

Apache License 2.0