CLI 命令行参考 CLI Reference

慧眼选鸟提供两个命令行入口，支持批量处理与脚本自动化： superpicky_cli.py 负责选片与评分，birdid_cli.py 是独立的鸟种识别工具。两者的 identify 共用同一套参数与识别逻辑，不会分叉。 SuperPicky ships two command-line entry points for batch processing and scripting: superpicky_cli.py for culling and rating, and birdid_cli.py as a standalone species identifier. Their identify commands share one argument set and one code path, so the two never drift apart.

00 先理解默认值 How defaults work

绝大多数可覆盖参数的 argparse 默认值是 None（哨兵）， 不是某个写死的数字。None 表示「命令行没指定」，程序会回落到 advanced_config —— 也就是图形界面用的同一份配置。所以 不带任何参数运行，行为与你在界面里设好的完全一致；显式给出参数才覆盖。 Most overridable options default to None (a sentinel), not a hard-coded number. None means "not given on the command line", and the value falls back to advanced_config — the very same config the GUI uses. So running with no options behaves exactly like your GUI settings; passing an option overrides it.

布尔开关是三态的（--x / --no-x / 不给）：不给即跟随配置。这样每个设置都有对应 flag，脚本与 agent 可以完全控制，同时人工调用又不必背默认值。 Boolean switches are tri-state (--x / --no-x / omitted): omitted means follow the config. Every setting has a flag, so scripts and agents get full control while humans don't have to memorize defaults.

01superpicky_cli.py

七个子命令： Seven subcommands:

命令 Command	作用 What it does
process	处理一个照片目录（评分 + 分类） Process one photo folder (rate + organize)
batch	递归批量处理子目录 Recursively process subfolders
reset	重置一个目录，文件移回原位、元数据清除 Reset a folder: move files back, clear metadata
batch-reset	批量重置所有已处理的子目录 Reset every processed subfolder
info	查看目录的处理状态与统计 Show a folder's processing status and stats
burst	连拍检测（默认仅预览） Burst detection (preview only by default)
identify	识别单张照片的鸟种 Identify the species in a single photo

process

# 用界面里设好的参数处理
python superpicky_cli.py process ~/Photos/Birds

# 覆盖锐度与美学阈值
python superpicky_cli.py process ~/Photos/Birds -s 600 -n 5.2

# 换技能档（驱动锐度/美学默认值）
python superpicky_cli.py process ~/Photos/Birds --skill-level master

# 开自动识鸟并限定国家
python superpicky_cli.py process ~/Photos/Birds -i --birdid-country AU

# 只评分不移动文件
python superpicky_cli.py process ~/Photos/Birds --no-organize

batch

与 process 共享全部处理参数，另有批量专属选项。 Shares every processing option with process, plus batch-only flags.

# 先看会处理哪些目录，不实际执行
python superpicky_cli.py batch ~/Photos --dry-run

# 跳过已处理过的目录，不再逐个确认
python superpicky_cli.py batch ~/Photos --skip-existing -y

批量专属 Batch-only	说明 Description
--dry-run	仅列出待处理目录，不执行 List target folders only, don't run
--skip-existing	跳过已处理的目录 Skip folders already processed
--max-depth	最大递归深度 Max recursion depth
-y, --yes	跳过确认提示 Skip the confirmation prompt
-q, --quiet	静默模式 Quiet output

reset / batch-reset

# 交互式重置单个目录
python superpicky_cli.py reset ~/Photos/Birds

# 跳过确认
python superpicky_cli.py reset ~/Photos/Birds -y

# 批量重置所有已处理的子目录
python superpicky_cli.py batch-reset ~/Photos -y

info

python superpicky_cli.py info ~/Photos/Birds

burst

# 预览连拍分组（不动文件）
python superpicky_cli.py burst ~/Photos/Birds

# 实际执行分组
python superpicky_cli.py burst ~/Photos/Birds --execute

参数 Option	默认 Default	说明 Description
-m, --min-count	4	最小连拍张数 Minimum frames per burst
-t, --threshold	250	时间阈值（毫秒） Time threshold in ms
--no-phash	—	禁用 pHash 验证（默认启用） Disable pHash verification (on by default)
--execute	—	实际执行；不给则仅预览 Actually apply; otherwise preview only

02 process / batch 的完整参数 Full options for process / batch

下表中默认值写「配置」的，即前面说的 None 哨兵——不给就跟随图形界面的设置。 Where the default column says "config", that's the None sentinel described above: omit it and the GUI setting applies.

评分阈值 Scoring thresholds

参数 Option	默认 Default	说明 Description
-s, --sharpness	配置 config	锐度阈值，跟随技能档预设 Sharpness threshold; follows the skill preset
-n, --nima-threshold	配置 config	美学阈值（TOPIQ） Aesthetics threshold (TOPIQ)
-c, --confidence	配置 config	AI 置信度阈值 0-100 AI confidence threshold, 0-100
--skill-level	配置 config	摄影水平预设，驱动上面两项的默认值： `beginner` / `intermediate` / `master` / `custom` Skill preset driving the two thresholds above: `beginner` / `intermediate` / `master` / `custom`
--min-sharpness	配置 config	0 星判定的锐度下限 Zero-star sharpness floor
--min-nima	配置 config	0 星判定的美学下限 Zero-star aesthetics floor
--picked-top	配置 config	精选旗标的 Top 百分比 Pick-flag top percentage

检测开关（三态） Detection toggles (tri-state)

参数 Option	说明 Description
--flight / --no-flight	飞版检测。不给则跟随配置（界面默认关） Flight detection; omitted follows config (GUI default: off)
--burst / --no-burst	连拍检测。不给则跟随配置（界面默认关） Burst detection; omitted follows config (GUI default: off)
--exposure / --no-exposure	曝光检测。不给则跟随配置（界面默认关） Exposure check; omitted follows config (GUI default: off)
--exposure-threshold	曝光阈值 0.05–0.20 Exposure threshold, 0.05–0.20

元数据与目录布局 Metadata & folder layout

参数 Option	取值 Values	说明 Description
--arw-write-mode	sidecar / embedded / inplace / auto	ARW 写入策略 ARW write strategy
--metadata-mode	embedded / sidecar / none	元数据写入模式 Metadata write mode
--folder-layout	species-first / rating-first	分目录布局 Folder organization
--name-format	default / avilist / clements / birdlife / scientific	鸟种英文名格式 Species name format
--xmp / --no-xmp	—	兼容旧写法，等价于 `--arw-write-mode sidecar` Legacy alias for `--arw-write-mode sidecar`
--no-organize	—	不移动文件到分类文件夹 Don't move files into folders
--no-cleanup	—	不清理临时 JPG Keep temporary JPGs
--cleanup-days	30	自动清理周期（天），0 = 永久保留。仅 `process` Auto-cleanup age in days, 0 = keep forever. `process` only
--keep-temp-files	—	保留临时预览图 Keep temporary preview images
--save-crop	—	保留 bird / debug 裁剪图到 `.superpicky/cache/debug` Keep bird/debug crops under `.superpicky/cache/debug`

自动识鸟 Auto bird ID

参数 Option	说明 Description
-i, --auto-identify	识别 2★ 以上照片的鸟种并按鸟种分目录（默认关） Identify species for 2★+ photos and file them by species (off by default)
--ebird / --no-ebird	eBird 地区过滤，默认开 eBird regional filtering, on by default
--birdid-country	国家代码，如 `AU` / `CN` / `US` Country code, e.g. `AU` / `CN` / `US`
--birdid-region	区域代码，如 `AU-SA` Region code, e.g. `AU-SA`
--birdid-threshold	识别置信度阈值 Identification confidence threshold

03birdid_cli.py

独立的鸟种识别工具，四个子命令：identify、organize、 reset、list-countries。 Standalone species identifier with four subcommands: identify, organize, reset, list-countries.

identify

# 单张
python birdid_cli.py identify ~/Photos/bird.jpg

# 批量（支持通配符），简化输出
python birdid_cli.py identify ~/Photos/*.jpg --batch

# 指定地区过滤
python birdid_cli.py identify ~/Photos/*.jpg --country AU --region AU-SA

# 换 OSEA 模型并开 TTA
python birdid_cli.py identify bird.NEF --model osea --tta

# 识别并写入 EXIF
python birdid_cli.py identify ~/Photos/*.jpg --write-exif

参数 Option	默认 Default	说明 Description
-t, --top	5	返回前 N 个候选 Return top N candidates
-m, --model	birdid2024	`birdid2024` 或 `osea` `birdid2024` or `osea`
--tta	—	启用 TTA，仅 OSEA 模型有效，更准但更慢 Enable TTA (OSEA only): more accurate, slower
--no-yolo	—	禁用 YOLO 裁剪 Disable YOLO cropping
--no-gps	—	禁用 GPS 自动检测 Disable GPS auto-detection
--no-ebird	—	禁用 eBird 区域过滤 Disable eBird regional filtering
-c, --country	—	国家代码 Country code
-r, --region	—	区域代码 Region code
-w, --write-exif	—	写入 EXIF（Title、Caption、Keywords） Write EXIF (Title, Caption, Keywords)
--threshold	70	写入 EXIF 的置信度阈值（%） Confidence threshold for writing EXIF (%)
-b, --batch	—	批量模式，简化输出 Batch mode with condensed output

superpicky_cli.py identify 用的是同一套参数，差别只有一个：它接单张 image，因此没有 --batch。 superpicky_cli.py identify takes the same options, with one difference: it accepts a single image, so there's no --batch.

organize

# 识别并按鸟种分目录
python birdid_cli.py organize ~/Photos/Birds

# 跳过确认，并写入 EXIF
python birdid_cli.py organize ~/Photos/Birds -y --write-exif

可用参数：--threshold（默认 70）、--no-ebird、 -c/--country、-r/--region、-w/--write-exif、 -y/--yes。目录结构示例： Options: --threshold (default 70), --no-ebird, -c/--country, -r/--region, -w/--write-exif, -y/--yes. Resulting layout:

Birds/
├── 彩虹蜂虎_Rainbow Bee-eater/
│   ├── DSC_0001.NEF
│   └── DSC_0002.NEF
├── 笑翠鸟_Laughing Kookaburra/
│   └── DSC_0003.NEF
└── .birdid_manifest.json

reset / list-countries

# 把分类后的照片移回原位（依据 .birdid_manifest.json）
python birdid_cli.py reset ~/Photos/Birds -y

# 列出支持的国家代码
python birdid_cli.py list-countries

← 返回首页 ← Back to home