# GRIME3 Command-Line Interface GRIME3 0.1.0 RC8.4 provides one supported command-line entry point: ```text grime3 ``` The command exposes the browser server and deterministic water-level measurement workflows. The CLI and browser use the same canonical Site Configuration and the same scientific measurement implementation. ## Top-level commands ```text grime3 --version grime3 --help grime3 web --help grime3 measure --help ``` `grime3 measure` contains three measurement operations: ```text grime3 measure image grime3 measure folder grime3 measure folders ``` Pre-public batch command names are not part of the RC8.4 public interface. ## Site Configuration Measurement commands require one canonical GRIME3 Site Configuration JSON file: ```text --site-config PATH ``` The same Site Configuration can be reused for any number of independent single-image, folder, or folder-of-folders runs. A `measure folders` run applies the selected Site Configuration to each child folder in that run. ROI geometry, calibration, datum, world units, grid settings, and other site-specific scientific state come from that file. The CLI does not expose separate legacy ROI, calibration, unit, datum, or small-octagon options. ## Measure one image Unix-like shell: ```bash grime3 measure image \ --image "/path/to/images/image 001.jpg" \ --site-config "/path/to/site config.json" \ --output-dir "/path/to/results" ``` Windows Command Prompt: ```text grime3 measure image ^ --image "C:\Data\Images\image 001.jpg" ^ --site-config "C:\Data\site config.json" ^ --output-dir "C:\Data\results" ``` PowerShell: ```powershell grime3 measure image ` --image "C:\Data\Images\image 001.jpg" ` --site-config "C:\Data\site config.json" ` --output-dir "C:\Data\results" ``` Use: ```text grime3 measure image --help ``` for the authoritative option list. ## Measure one folder Unix-like shell: ```bash grime3 measure folder \ --images "/path/to/images" \ --site-config "/path/to/site_config.json" \ --output-dir "/path/to/results" ``` Add `--recursive` when supported images should also be found below subdirectories. Timestamp selection is controlled with: ```text --timestamp-source auto --timestamp-source exif --timestamp-source filename --timestamp-source none ``` When filename timestamps are used, a `strptime`-compatible pattern can be supplied with: ```text --timestamp-filename-format FORMAT ``` Optional scientific CSV fields can be selected by repeating: ```text --csv-column FIELD ``` Required measurement columns are always retained by the CSV contract. Decision overlays can be written during the same scientific run: ```text --decision-overlays --overlay-scale 50 ``` The overlay scale accepts integer percentages from 10 through 100. ## Measure a folder of folders For a data root whose immediate child directories are independent image folders: ```bash grime3 measure folders \ --images-root "/path/to/data_root" \ --site-config "/path/to/site_config.json" \ --output-dir "/path/to/results" ``` Each non-empty immediate child folder is processed independently. Parent rollups combine the completed child results. The command supports the corresponding timestamp, CSV-column, recursive, decision-overlay, and overlay-scale options shown by: ```text grime3 measure folders --help ``` ## Reusing one Site Configuration A Site Configuration is not consumed or modified by a measurement run. Therefore one configuration can be reused for multiple datasets. For example, a Unix-like shell can define the path once: ```bash SITE_CONFIG="/data/site/site_config.json" grime3 measure folder \ --images "/data/run_01" \ --site-config "$SITE_CONFIG" \ --output-dir "/results/run_01" grime3 measure folder \ --images "/data/run_02" \ --site-config "$SITE_CONFIG" \ --output-dir "/results/run_02" ``` The CLI intentionally does not maintain hidden session state for a "currently loaded" configuration. Each invocation records the explicit configuration path in its provenance. Future Site Catalog and Data Root assignment functionality can provide higher-level persistent configuration selection without making individual measurement commands ambiguous. ## Measurement outputs Single-image and folder measurement use the same underlying output contract. The exhaustive scientific information is retained in JSON. The primary scientific CSV is intentionally curated and contains no more than 20 user-selectable fields, while always retaining its required fields. Typical folder outputs include: ```text waterline_measurement_summary.json waterline_measurement_summary.csv dual_pass_batch_summary.json dual_pass_batch_summary.csv run_manifest.json ``` Per-image exhaustive JSON is written using the image stem and the `_dual_pass_waterline.json` suffix. When decision overlays are enabled, they are written beneath: ```text decision_overlays/ ``` Folder-of-folders runs additionally produce child status information and combined parent rollups such as: ```text folder_child_run_summary.json folder_child_run_summary.csv all_waterline_measurement_summary.json all_waterline_measurement_summary.csv all_dual_pass_batch_summary.json all_dual_pass_batch_summary.csv ``` ## CSV durability During folder measurement, GRIME3 durably checkpoints the scientific CSV after every 10 completed images. RC8.4 keeps this interval fixed. At normal completion, any remaining partial checkpoint group is also flushed and the final CSV is written. ## Ctrl+C behavior For folder and folder-of-folders measurement, the first Ctrl+C requests a cooperative stop. GRIME3 finishes the image currently being processed, finalizes completed outputs, and exits with a nonzero interrupted status. For single-image measurement, a first Ctrl+C likewise requests completion of the current image followed by normal output finalization and an interrupted exit status. A second Ctrl+C forces immediate interruption. The incremental CSV writer is closed through the shared folder execution `finally` path, preserving rows that were already completed, although a forced second interruption can prevent later summary or manifest finalization. ## Exit behavior A normal successful measurement exits with status 0. Invalid input, processing failure, or a completed run containing scientific processing errors exits nonzero. A cooperative or forced Ctrl+C interruption exits with status 130. Programs and shell scripts should use the process exit status rather than parsing human-readable status messages. ## Paths with spaces All supported CLI path arguments use normal filesystem path handling and are tested with paths containing spaces. Quote such paths according to the active shell. ## Browser server The same installed package also starts the browser interface: ```text grime3 web --help ``` The browser and CLI are interfaces over the same GRIME3 scientific implementation; they are not separate measurement engines.