=============
CLI Reference
=============

calibrate
---------

Main calibration binary.

.. code-block:: text

   calibrate [OPTIONS] [COMMAND]

Default Mode (Calibration)
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Flag
     - Default
     - Description
   * - ``-i, --input <PATH>``
     -
     - L0 Zarr store path
   * - ``--output <PATH>``
     -
     - L1 Zarr output directory
   * - ``--atm-table <PATH>``
     -
     - ATM table file (.catm, .dat, or .dat.gz)
   * - ``--manifest <PATH>``
     -
     - WFM manifest JSON (replaces --input/--output/--atm-table)
   * - ``--pwv <FLOAT>``
     - fit
     - Fixed PWV in mm (omit to fit from data)
   * - ``--mode <MODE>``
     - auto
     - Observation mode: auto, totalpower, otf
   * - ``--physics <MODE>``
     - kalibrate-compat
     - Physics constants: exact, kalibrate-compat
   * - ``--foeff <FLOAT>``
     - 0.97
     - Forward efficiency
   * - ``--gain-image <FLOAT>``
     - 0.5
     - Image sideband gain
   * - ``--threads <N>``
     - auto
     - Rayon thread pool size
   * - ``-v, --verbose``
     -
     - Increase log level (-v = debug, -vv = trace)
   * - ``-q, --quiet``
     -
     - Suppress progress bar

FITS Ingest Mode (requires ``fits-ingest`` feature)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Flag
     - Default
     - Description
   * - ``-f, --fits-folder <PATH>``
     -
     - FITS folder to convert and calibrate
   * - ``--zarr-cache <PATH>``
     - ``<fits_folder>.zarr``
     - Where to place the converted Zarr store

Subcommands
~~~~~~~~~~~

``calibrate convert``
  Convert a text ATM table to binary format for fast loading.

  .. code-block:: bash

     calibrate convert --input atm.dat.gz --output atm.catm

Exit Codes
~~~~~~~~~~

- **0** — all scans calibrated successfully
- **1** — all scans failed (or no scans found)
- **2** — partial failure (some scans succeeded, see ``failures.json``)

Manifest Schema
~~~~~~~~~~~~~~~

.. code-block:: json

   {
     "input_zarr_paths": ["/data/l0/session.zarr"],
     "atm_table_path": "/data/atm/atm.catm",
     "output_dir": "/data/l1/",
     "scan_range": [25650, 25660],
     "config_overrides": {
       "obs_mode": "otf",
       "pwv": 1.2,
       "physics": "exact",
       "foeff": 0.97,
       "gain_image": 0.5,
       "threads": 8
     }
   }

zarr-fits
---------

Standalone FITS-to-Zarr conversion binary.

.. code-block:: text

   zarr-fits convert [OPTIONS]

.. list-table::
   :header-rows: 1
   :widths: 30 15 55

   * - Flag
     - Default
     - Description
   * - ``-f, --fits-folder <PATH>``
     -
     - Input directory containing FITS files
   * - ``-z, --zarr-path <PATH>``
     -
     - Output Zarr store path
   * - ``-s, --scans <RANGE>``
     -
     - Scan filter (e.g., ``100,200`` for range or ``100,200,300`` for list)
   * - ``-w, --workers <N>``
     - CPU count
     - Parallel worker threads
   * - ``--overwrite``
     - false
     - Re-process scans already in store
   * - ``-p, --profile <NAME>``
     - auto
     - Telescope profile name
   * - ``--profiles-dir <PATH>``
     - embedded
     - Custom profile directory
   * - ``-v``
     -
     - Verbosity (-v = debug, -vv = trace)

Examples
--------

.. code-block:: bash

   # Basic calibration
   calibrate -i session.zarr --output l1/ --atm-table atm.catm

   # OTF mode with fixed PWV
   calibrate -i session.zarr --output l1/ --atm-table atm.catm \
     --pwv 1.2 --mode otf

   # FITS folder → convert + calibrate
   calibrate -f /data/raw/session_001 --output l1/ --atm-table atm.catm

   # Standalone conversion
   zarr-fits convert -f /data/raw/session_001 -z session.zarr

   # Convert ATM table to binary
   calibrate convert --input atm.dat.gz --output atm.catm

   # Batch via manifest
   calibrate --manifest manifest.json