Agent-friendly Flickr CLI
Single-binary tool for photo management, backup, upload, and full API access.
- Single binary — no dependencies, no runtime, no containers
- 47 commands — photos, albums, favorites, galleries, groups, comments, contacts, stats, urls, checksums, cache, Piwigo import, raw API
- JSON-first —
--jsonon every command, consistent envelope, machine-parseable - Safety gates —
--read-only,--dry-run,--confirmfor destructive operations - Agent-ready — exit codes, error categories, NDJSON events stream, secret redaction
- Cross-platform — Linux, macOS, Windows (amd64/arm64)
brew install --cask thedavidweng/tap/flickrgo install github.com/thedavidweng/flickr-cli/cmd/flickr@latestDownload from Releases.
git clone https://github.com/thedavidweng/flickr-cli.git
cd flickr-cli
make build# 1. Authenticate
flickr auth login --perms write
# 2. Verify
flickr doctor
# 3. Use it
flickr albums list
flickr photos upload ./vacation/ --recursive --album "Summer 2026"
flickr photos download --all --dest ./backup --layout id-dirsflickr photos list # list your photos
flickr photos search --text "sunset" # search by text
flickr photos show 51234567890 # show metadata + sizes + albums
flickr photos download 51234567890 # download original
flickr photos set-tags 51234567890 --tag landscape --tag hdr
flickr photos set-privacy 51234567890 --privacy private
flickr photos delete 51234567890 --confirmflickr albums list --sort count
flickr albums create --title "Vacation" --primary-photo-id 12345
flickr albums photos 72157712345678901
flickr albums delete 72157712345678901 --confirm# single file
flickr photos upload photo.jpg --album "Photos"
# directory with deduplication
flickr photos upload ./photos/ --recursive --album "Import" --dedupe checksum --hash md5
# dry-run first
flickr photos upload ./photos/ --recursive --dry-run# download all photos organized by album
flickr photos download --all --dest ./backup --layout album
# download with date filter via search + download
flickr photos search --min-upload-date 2025-01-01 --privacy private --json | jq -r '.data.items[].id' | xargs flickr photos download --dest ./backup
# stable id-dirs layout (idempotent, skips existing files)
flickr photos download --all --dest ./backup --layout id-dirs --metadata both# call any Flickr method
flickr api call flickr.photos.search --param text=mountains --param per_page=5 --json
# list available methods
flickr api methods
# method documentation
flickr api method-info flickr.photos.search# JSON output for scripts
flickr albums list --json | jq '.data[] | .title'
# safe scripting with read-only mode
FLICKR_READ_ONLY=1 flickr photos list --json
# progress events on stderr, result on stdout
flickr photos upload ./photos/ --json --events| Flag | Default | Description |
|---|---|---|
--config |
Config file path | |
--profile |
default |
Credential profile |
--json |
false |
JSON envelope to stdout |
--pretty |
false |
Pretty-print JSON |
--compact |
false |
Compact output fields |
--full |
false |
Full normalized fields (overrides --compact) |
--read-only |
false |
Block all remote mutations |
--dry-run |
false |
Preview without execution |
--confirm |
false |
Confirm high-risk operations |
--timeout |
30s |
API timeout |
--retries |
3 |
Retry count for retryable failures |
--concurrency |
4 |
Parallel workers |
--events |
false |
NDJSON progress to stderr |
--no-color |
false |
Disable ANSI color |
--verbose |
false |
Diagnostics to stderr |
--debug |
false |
Debug diagnostics with secrets redacted |
--quiet |
false |
Suppress progress output |
Run flickr --help or flickr <command> --help for full flag details.
| Document | Description | |
|---|---|---|
| 📋 | Command Reference | All 47 commands with flags and examples |
| 🔧 | Architecture | Package layout and design decisions |
| 🔐 | Authentication | OAuth setup and profiles |
| 📤 | Upload | Upload workflow, flags, deduplication |
| 💾 | Backup | Three backup modes, resume, metadata |
| 🛡️ | Safety | Safety gates and audit logging |
| 📊 | JSON Schema | Envelope format, error codes, exit codes |
| 🤖 | Agent Guide | Scripting, JSON mode, exit codes |
| 🔄 | Piwigo Import | Migrate from Piwigo galleries |
| 📝 | Changelog | Version history |
| Variable | Description |
|---|---|
FLICKR_API_KEY |
Flickr API key |
FLICKR_API_SECRET |
Flickr API secret |
FLICKR_OAUTH_TOKEN |
OAuth access token |
FLICKR_OAUTH_TOKEN_SECRET |
OAuth access token secret |
FLICKR_CONFIG |
Config file path |
FLICKR_PROFILE |
Active profile name |
FLICKR_READ_ONLY |
Set 1 to block mutations |
See CONTRIBUTING.md.
git clone https://github.com/thedavidweng/flickr-cli.git
cd flickr-cli
make test