SuperPicky CLI (skill)

SuperPicky — bird photo AI culling (superpicky_cli.py, birdid_cli.py). This skill only covers CLI paths under $SKILL (directory containing this file).

Three entry modes (run.sh)

All user-facing commands go through ${SKILL}/scripts/run.sh (use the absolute path when cwd is not $SKILL). There are three entry modes (plus one helper):

Helper (not a separate “product” entry): --py PATH — run a script with the same venv. PATH may be absolute, or relative to .upstream/ (internally normalized to an absolute path before exec).

Absolute paths (required for agents / cron)

• install.sh / run.sh / capture-cli-help.sh: when another tool invokes them, use the full absolute path (e.g. ${SKILL}/scripts/run.sh, never rely on cd + ./scripts/run.sh).
• run.sh internals: always exec Python with absolute paths for superpicky_cli.py, birdid_cli.py, ebird_region_query.py, and the --py script (relative args become ${SKILL}/.upstream/...).

Interactive (from $SKILL):

./scripts/run.sh process /photos

Automation (example):

SKILL="$(cd /path/to/superpicky-cli && pwd)"
"${SKILL}/scripts/run.sh" process /photos
"${SKILL}/scripts/run.sh" --py "${SKILL}/.upstream/scripts/download_models.py"

Layout

$SKILL = skill root.

$SKILL/
├── SKILL.md
├── .gitignore              # .upstream/
├── reference/              # CLI help + small doc set (see table below)
└── scripts/
    ├── install.sh
    ├── run.sh              # ENTRY (+ --region-query → ebird_region_query.py)
    ├── ebird_region_query.py   # fuzzy eBird country/region code lookup
    ├── ebird_region_query_test.py
    ├── capture-cli-help.sh
    └── setup-upstream-venv.sh → install.sh

$SKILL/.upstream/           # clone (gitignored)
├── .venv/
├── superpicky_cli.py
├── birdid_cli.py
└── …

Reference (minimal)

Install

From $SKILL (or call ${SKILL}/scripts/install.sh by absolute path):

./scripts/install.sh
"${SKILL}/scripts/install.sh" --with-models
./scripts/install.sh --skip-verify
./scripts/install.sh --no-clone
PY=python3.12 "${SKILL}/scripts/install.sh"

1. Python 3.10–3.12 preferred; python -m venv must work.
2. $SKILL/.upstream/ + $SKILL/.upstream/.venv/.
3. Torch: macOS → base + PyPI torch; NVIDIA + nvidia-smi → requirements_cuda.txt; else requirements.txt or fallback.
4. verify_environment after pip unless --skip-verify / SKIP_VERIFY=1 — failures → [superpicky-cli verify] ERROR: and exit 1.

Entry details & examples

Wrapper meta-help: ${SKILL}/scripts/run.sh --help. SuperPicky top-level: ${SKILL}/scripts/run.sh -h.

"${SKILL}/scripts/run.sh" process /path/to/photos
"${SKILL}/scripts/run.sh" --birdid identify /path/to.jpg
"${SKILL}/scripts/run.sh" --py "${SKILL}/.upstream/scripts/download_models.py"
# Relative --py is OK: resolved against .upstream/, then executed as absolute path
"${SKILL}/scripts/run.sh" --py scripts/download_models.py

ebird_region_query.py (entry 3) — --region-query

Resolves country codes (e.g. AU, CN) and region codes (e.g. AU-SA, CN-31) for --birdid-country, --birdid-region, birdid_cli -c/-r, and process --birdid-*.

• Data: .upstream/birdid/data/ebird_regions.json (EN + name_cn) + codes from birdid/avonet_filter.py REGION_BOUNDS (inline # labels for entries not in JSON).
• Match: case-insensitive substring on code, English name, Chinese name; pinyin if optional pypinyin is installed in .venv (pip install pypinyin). Fuzzy: difflib ratio on tokens / whole fields; tune with --min-score (default 0.5).

"${SKILL}/scripts/run.sh" --region-query shanghai
"${SKILL}/scripts/run.sh" --region-query 广东 --limit 10
"${SKILL}/scripts/run.sh" --region-query guangdong
"${SKILL}/scripts/run.sh" --region-query AU-SA
"${SKILL}/scripts/run.sh" --region-query --list-countries --limit 60
"${SKILL}/scripts/run.sh" --region-query --list-all --limit 40
"${SKILL}/scripts/run.sh" --region-query texas --json

Direct: "${SKILL}/.upstream/.venv/bin/python" "${SKILL}/scripts/ebird_region_query.py" -h

Tests: "${SKILL}/.upstream/.venv/bin/python" "${SKILL}/scripts/ebird_region_query_test.py"

Manual: source "${SKILL}/.upstream/.venv/bin/activate" && cd "${SKILL}/.upstream" && python "${SKILL}/.upstream/superpicky_cli.py" …

Refresh --help capture

"${SKILL}/scripts/capture-cli-help.sh"

Upstream-only install

git clone https://github.com/jamesphotography/SuperPicky.git && cd SuperPicky
pip install -r requirements.txt   # or requirements_cuda.txt
python scripts/download_models.py

Repo cwd = clone root. Models needed for real process / identify, not for -h. Pip quirks: reference/SOURCE.md.

superpicky_cli.py (entry 1)

Via skill: "${SKILL}/scripts/run.sh" … (no --birdid / --region-query prefix)

Subcommands: process | reset | restar | info | burst | identify

Flags: reference/cli-help-captured.txt

process: -s sharpness, -n TOPIQ, -c confidence, --flight/--no-flight, --burst/--no-burst, --xmp/--no-xmp, --no-organize, --no-cleanup, -q, -i / --auto-identify, --birdid-*, --keep-temp-files / --no-keep-temp-files, --cleanup-days, --save-crop.

reset / restar: -y; restar needs .superpicky/report.db.

burst: preview unless --execute.

identify: single image, --top, --write-exif, etc.

birdid_cli.py (entry 2)

Via skill: "${SKILL}/scripts/run.sh" --birdid …

Subcommands: identify | organize | reset | list-countries — details in cli-help-captured.txt (search birdid_cli).

Agent checklist

1. Resolve $SKILL to an absolute directory; invoke "${SKILL}/scripts/run.sh" (and install.sh) by full path, not ./scripts/....
2. "${SKILL}/scripts/install.sh" if .upstream/.venv missing.
3. "${SKILL}/scripts/run.sh" --region-query … when the user gives a place name and you need an eBird -c / -r / --birdid-region code.
4. -y on destructive reset / restar / birdid organize|reset when appropriate.
5. Pipeline: process → optional restar; reset clears; restar needs report.db.
6. Star folder names: English + Chinese variants in upstream.