# CLI reference

The console entry point is the ``arcade`` command, implemented as
``arcade.cli:main``. After an editable install you should be able to invoke it
from any directory while the virtual environment is active.

```bash
pip install -e ".[torch,signature]"
arcade -h
```

The subcommands below are the stable public surface for running pipelines,
inspecting the registry, validating YAML, emitting templates, and summarizing
data files.

## ``arcade run``

Run the full pipeline from a YAML configuration file. That is the preferred
path for anything beyond a quick smoke test.

```bash
arcade run configs/paper_all_methods_benchmark.yaml
arcade run --data data/readout2019_adc.h5 --qubits 5 --classifiers threshold,lda --output ./output/smoke
```

| Argument | Meaning |
|----------|---------|
| ``config`` | Path to the main YAML file as a positional argument |
| ``--data`` | Data file when you are not passing a full config |
| ``--qubits`` | Required together with ``--data`` |
| ``--classifiers`` | Comma-separated registry names |
| ``--output`` | Output directory; default is ``./output`` |

Prefer a full YAML file for production runs so demodulation and split settings
are explicit. With neither a config nor ``--data``, ARCADE may try a tiny
synthetic demo that can fail if optional extras are missing.

## ``arcade list``

Print every registered classifier with its category and a one-line
description.

```bash
arcade list
```

## ``arcade describe``

```bash
arcade describe fnn
arcade describe herqules
```

Shows category, ``FEATURE_KIND``, and whether a neural-network companion
config is required.

## ``arcade validate``

```bash
arcade validate configs/example.yaml
```

Runs Pydantic validation through ``arcade.config.validate_and_explain``. Exit
code ``1`` means errors were found. Fix the reported field paths before
launching a long training run.

## ``arcade template``

Emit a commented YAML skeleton to standard output.

```bash
arcade template --qubits 5 --classifiers threshold,lda,fnn > my_lab.yaml
```

Redirect the skeleton into a file, then fill paths and demodulation settings
for your lab.

## ``arcade explore``

Print a data summary after loading, including shapes, label histogram, and
splits when available.

```bash
arcade explore data/readout2019_adc.h5 --qubits 5
```

```{note}
For ADC files you usually need demodulation settings that a bare-path explore
call does not load from the zoo YAML. Prefer ``arcade run`` with a full config
for production paths. Use ``explore`` on already-prepared caches or after you
know the loader defaults match your file.
```

## Related Python API

| CLI | Python |
|-----|--------|
| ``arcade run cfg.yaml`` | ``arcade.run("cfg.yaml")`` |
| ``arcade list`` or ``describe`` | ``arcade.describe("fnn")`` |
| ``arcade explore`` | ``arcade.explore(path, num_qubits=…)`` |
| load or compare helpers | ``arcade.load`` and ``arcade.compare`` |