======================
Command-line reference
======================

Run ``imcluster --help`` to see the reference for the installed version.

Positional arguments
====================

``INPUTS...``
   Optional image files, directories, or text manifests to process. Inputs may
   be omitted when ``--cache`` names an existing imcluster cache.

Main options
============

``--cache PATH``
   Preserve processing results in a reusable Parquet cache.

``--gallery PATH``
   Preserve the standalone HTML cluster gallery at this path.

``--no-open``
   Do not launch the generated gallery in the default browser.

``--dino-version [auto|2|3]``
   Select the DINO generation. Automatic mode prefers an accessible or cached
   DINOv3 model and otherwise falls back to DINOv2.

``--arch [vit|convnext]`` and ``--size [tiny|small|base|large|huge|max]``
   Select a model preset. DINOv2 ignores ``--arch`` and supports ``small``,
   ``base``, ``large``, and ``max`` (Giant). DINOv3 uses both options.

``--model TEXT``
   Use an arbitrary compatible Hugging Face model instead of the preset.

``--device [auto|cpu|cuda|mps]`` and ``--batch-size INTEGER``
   Control model inference hardware and batching.

``--recursive`` and ``--max-images INTEGER``
   Control input discovery.

``--clustering [spectral|dbscan|hdbscan|kmeans|agglomerative|hierarchical]``
   Select clustering behavior. Fixed-count methods use ``--n-clusters``;
   DBSCAN uses ``--dbscan-eps``. DBSCAN and HDBSCAN share ``--min-samples``.
   The default is ``kmeans``.

``--reduce [none|umap|tsne|pca]``
   Optionally reduce DINO feature dimensions before clustering. Reduced vectors
   are cached. The default is ``umap``; use ``--reduce none`` to disable it.

``--reduction-dims INTEGER``
   Set the requested output dimensionality for PCA and UMAP. The default is
   ``50``. t-SNE is capped at three dimensions.

``--name``
   Generate and cache descriptive cluster names from representative cached
   thumbnails using a multimodal LLM.

``--llm TEXT`` and ``--llm-temperature FLOAT``
   Select the llmloader-compatible naming model and its sampling temperature.
   Defaults are ``gpt-5.6-luna`` and ``0.2``.

``--llm-api-key TEXT``
   Pass a provider API key for cluster naming. Prefer the provider's environment
   variable to avoid exposing a secret in shell history or process listings.

``--in-group-size INTEGER`` and ``--out-group-size INTEGER``
   Set the maximum in-cluster and contrasting outside thumbnails sent to the
   naming LLM. The defaults are ``10`` and ``0`` respectively.

``--thumbnail-width INTEGER`` and ``--thumbnail-height INTEGER``
   Set the maximum embedded thumbnail dimensions.

``--evaluate PATH`` (alias: ``--expected PATH``)
   Evaluate clustering against a CSV with ``filename,class`` columns and print
   Normalized Mutual Information (NMI), Adjusted Rand Index (ARI), and
   optimally matched clustering accuracy (ACC).

``--metric PATH``
   Write NMI, ARI, and ACC scores to a CSV. Requires ``--evaluate``.

Cache options
=============

``--force`` replaces every cached stage. ``--force-features``,
``--force-cluster``, and ``--force-thumbnails`` recompute
individual stages and their required downstream results.