Docs · CLI & output formats

The command-line interface

Power users can script everything with rapid-stacker-cli. Its defaults match the GUI’s recommended surface (PSF-signal weighting, local normalization, quality gate, distortion correction, astrometry on), and every stage is available — no license needed. Run any subcommand with --help for the full flag list.

Getting the CLI

Every installer includes rapid-stacker-cli beside the app:

InstallerRunning it from a terminal
Windows .msi / .exeThe installer adds the install folder to your PATH. Open a new terminal and run rapid-stacker-cli. Uninstalling removes it again.
macOS .dmgThe tool is inside rapid-stacker.app. Open Settings → Command-line tool and click Install command-line tool to link it into /usr/local/bin (macOS may ask for your password). Launch the app from Applications first, not from the disk image.
Linux .debInstalled as /usr/bin/rapid-stacker-cli, already on your PATH.
Linux AppImageThe AppImage can't expose it. Download the CLI only .tar.gz from the download section, extract it, and run ./rapid-stacker-cli. It includes the CUDA fast path and needs no GUI libraries.

Settings → Command-line tool in the app always shows the exact path to your copy.

Subcommands

SubcommandWhat it does
build-mastersBuild master bias/dark/flat(/dark-flat) files from a folder of raw cal frames. Key flags: --flats-per-session, --min-frames, --dark-flat-max-exptime-s, --output-format xisf|fits|fits-fz|fits-fz-rice, and for a shared calibration library --flats-only + --calibration-library <dir>.
stackRun the full grouped pipeline — one master per (panel, camera, binning, filter, exposure) group, XISF by default. Key flags: --rejection <algo>, --weights <scheme>, --drizzle --drizzle-scale 2.0, --backend auto|cpu|wgpu|cuda, --gaia-db <folder>, --flat-masters <dir>, --combine-exposures, --cross-group-align --auto-crop, --output-format xisf|fits|fits-fz|fits-fz-rice, --mosaic, opt-outs like --no-quality-gate, --no-local-normalize, --no-astrometry, --no-panel-split.
measureReport a master’s quality metrics: FWHM, eccentricity, star count, background σ, SNR proxy.
compare / compare-matchedCompare two masters; compare-matched triangle-matches the same physical stars in both, so it stays fair across different crops or drizzle scales.
renderWrite screen-stretched PGM previews of one or two masters under a shared stretch for visual A/B comparison.
patch-xisfOne-shot repair of XISF files written by very old versions (pre-1.x block-structure fixes). Not part of a normal workflow.
mosaicRe-assemble an existing set of plate-solved panel masters into a mosaic without restacking — e.g. after tuning --feather-px or --gradient-degree.

Example — a full stack from the shell (Windows syntax):

rapid-stacker-cli stack --input F:\M17\Lights --masters F:\M17\Masters ^
  --output F:\M17\Stacked\Stacked.xisf --drizzle --drizzle-scale 2.0 ^
  --cross-group-align --auto-crop --gaia-db D:\Gaia\XPSD

With a shared calibration library (1.8.4+) — bias and darks from the library, flats only from this project, so a stale flat from another project is never matched:

rapid-stacker-cli stack --input F:\M17\Lights --masters F:\CalLibrary ^
  --flat-masters F:\M17\Masters --output F:\M17\Stacked\Stacked.xisf

Build just this project’s flats (and dark-flats) against that library:

rapid-stacker-cli build-masters --input F:\M17 --output F:\M17\Masters ^
  --flats-only --calibration-library F:\CalLibrary

Output files & formats

  • Stacked masters — 32-bit float XISF, one per group, named Stacked_<Filter>_<Camera>_<Exposure>.xisf (e.g. Stacked_Blue_ZWO_ASI2600MM_Duo_300s.xisf). OSC runs with separate channels add _R / _G / _B masters; the optional PCC reference is …_colour.xisf. Plate-solved masters embed both standard FITS WCS keywords and PixInsight AstrometricSolution properties.
  • Rejection map — optionally written alongside the master (CLI --rejection-map) showing, per pixel, how many frames were rejected there.
  • Master calibration frames — written by Build Masters as master_bias_*, master_dark_*, master_flat_* with the matching key in the filename (binning, gain, offset; exposure + temperature for darks; filter + session date for per-session flats), e.g. master_dark_1x1_g100_o20_e30_-10c.xisf.
  • Inputs — lights and cal frames may be FITS (.fits/.fit/.fts) or XISF.
  • Configuration — a single config file in the OS config directory (org com.ekeservices.rapid-stacker), holding all settings, last-used folders, and update preferences.

Next steps