Superpicky Cli

SuperPicky CLI skill: use absolute paths to scripts/install.sh and scripts/run.sh for automation; run.sh three entries (superpicky_cli, birdid_cli, --region-query) and --py; reference/cli-help-captured.txt.

yoshino-s@yoshino-s

Install

openclaw skills install @yoshino-s/superpicky

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):

#	How you invoke	Program	What it is for
1	`"${SKILL}/scripts/run.sh"` then the same args as `superpicky_cli.py`	`superpicky_cli.py`	Main pipeline: `process` / `reset` / `restar` / `info` / `burst` / `identify` (folder culling, EXIF, stars, optional auto BirdID).
2	`"${SKILL}/scripts/run.sh" --birdid` then the same args as `birdid_cli.py`	`birdid_cli.py`	Standalone BirdID: batch `identify`, `organize` by species, `reset`, `list-countries`; OSEA / eBird filters.
3	`"${SKILL}/scripts/run.sh" --region-query` then args for `ebird_region_query.py`	`ebird_region_query.py`	Code lookup only: fuzzy match place names → eBird country/region codes for use in (1) or (2) (`--birdid-country`, `--birdid-region`, `-c`, `-r`).

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):

bash

./scripts/run.sh process /photos

Automation (example):

bash

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.

text

$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
└── …

Script	Role
`scripts/install.sh`	Install into `.upstream/` + `.upstream/.venv/`
`scripts/run.sh`	Three entries: default → `superpicky_cli.py`; `--birdid` → `birdid_cli.py`; `--region-query` → `ebird_region_query.py`; helper `--py`
`scripts/ebird_region_query.py`	Fuzzy lookup (also via `run.sh --region-query`); tests: `ebird_region_query_test.py`
`scripts/capture-cli-help.sh`	Refresh `reference/cli-help-captured.txt`

Reference (minimal)

File	Use
reference/cli-help-captured.txt	Flags (`--help` dump)
reference/docs/cli-reference.md	Short bilingual CLI notes
reference/docs/manifest机制说明.md	Reset / manifest behavior
reference/docs/BIRDID_OPTIMIZATION_GUIDE.md	BirdID tuning
reference/requirements*.txt	Pip pins (mirror of upstream)
reference/SOURCE.md	Capture metadata, pip quirks
reference/README-INDEX.md	Index of `reference/`

Install

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

bash

./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"

Python 3.10–3.12 preferred; python -m venv must work.
$SKILL/.upstream/ + $SKILL/.upstream/.venv/.
Torch: macOS → base + PyPI torch; NVIDIA + nvidia-smi → requirements_cuda.txt; else requirements.txt or fallback.
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.

bash

"${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).

bash

"${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

bash

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

Upstream-only install

bash

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

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

Superpicky Cli

Install

SuperPicky CLI (skill)

Three entry modes (run.sh)

Absolute paths (required for agents / cron)

Layout

Reference (minimal)

Install

Entry details & examples

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

Refresh --help capture

Upstream-only install

superpicky_cli.py (entry 1)

birdid_cli.py (entry 2)

Agent checklist

Related skills

Three entry modes (`run.sh`)

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

Refresh `--help` capture

`superpicky_cli.py` (entry 1)

`birdid_cli.py` (entry 2)