CLI Reference

One binary, many tools. psf-guard --help lists everything and every subcommand has a detailed --help; this page is the guided tour.

Serving the grader UI

# Serve (registers the DB in the shared registry on first run)
psf-guard server <database> <image-dirs...> [--port 3000]

# TOML config for server knobs (port, cache, pre-generation, worker ratios)
psf-guard server --config psf-guard.toml

# Throwaway session that doesn't touch your real registry
psf-guard server --registry /tmp/scratch.json <db> <dirs...>

# Bind localhost only (default binds 0.0.0.0)
psf-guard server --host 127.0.0.1 <db> <dirs...>

Multiple image directories are scanned in priority order (first hit wins). The server manages every database in the registry, not just the one passed on the command line — see Configuration.

Quality screening

psf-guard screen-fits ./lights                        # per-frame verdicts
psf-guard screen-fits ./lights --annotate ./diag      # diagnostic PNGs
psf-guard screen-fits ./lights --regrade-db my-db --dry-run
psf-guard screen-fits ./lights --format json          # or table, csv

Details and tuning: Quality Screening.

Reject archival

psf-guard move-rejects --db <slug> [--dry-run] [--project NAME] [--target NAME]
psf-guard restore-rejects --db <slug> [--all] [--image-id N] [--dry-run]

Details: Rejects & Sync.

Two-database sync

psf-guard sync pull --from telescope.sqlite --to my-db
psf-guard sync grades --from my-db --to telescope.sqlite

Details: Rejects & Sync.

Star detection & PSF analysis

# Detect stars and compare against database values
psf-guard analyze-fits image.fits [--detector nina|hocusfocus] [--compare-all]

# Annotated star map
psf-guard annotate-stars image.fits [--max-stars 50]

# PSF fit residuals — single star or a grid
psf-guard visualize-psf image.fits [--star-index N]
psf-guard visualize-psf-multi image.fits [--num-stars 25]

# PSF fitting performance benchmark
psf-guard benchmark-psf image.fits

FITS utilities

psf-guard stretch-to-png image.fits -o output.png    # MTF auto-stretch
psf-guard read-fits image.fits                       # header/metadata dump

Database queries & manual grading

psf-guard list-projects -d database.sqlite
psf-guard list-targets "Project Name" -d database.sqlite
psf-guard dump-grading -d database.sqlite [--project NAME]
psf-guard show-images <IDS> -d database.sqlite
psf-guard update-grade <ID> rejected -d database.sqlite
psf-guard regrade database.sqlite [--dry-run]        # statistical re-grading

Batch commands also support statistical outlier detection (--enable-statistical): per-target/filter HFR and star-count distribution analysis plus sequence-based cloud detection. Details in docs/STATISTICAL_GRADING.md.