# CLI Reference

Run `nexuscreator -h` to see the latest autogenerated help.

## Always Relevant (Any Run)

- `-i`, `--input PATH` — source data (file or directory).
- `-o`, `--output_path PATH` — output file or directory.
- `-b`, `--beamline_name NAME` — beamline context (`ikft`, `batteries`, `peaxis`, ...).
- `-h`, `--help` — display help and exit.
- `-v`, `--version` — print the semantic version.
- `--list-beamlines` — list accepted beamline names.
- `--license`, `--notice` — print legal texts.

## Relevant When Converting to `.nxs` (`-n`)

- `-n`, `--nexus_definition FILE` — apply an existing `.nxd`/YAML definition.
- `-f`, `--file_per_scan` — SPEC only: write one file per scan plus a master with links.
- `-I`, `--icat_proposal_number NUM` — append a `proposal_<NUM>/` subfolder to the output path
  for ICAT ingestion (see Output Path Rules in `architecture`).
- `--auto-generate-nxd` — for directory inputs, auto-generate per-file definitions before conversion.
- `--pair-dta-raw` — for single `.dta`, merge with sibling `*_raw.dta` (or inverse) into one
  combined variable library.
- `--batteries-analysis` — enable electrochemical analysis for batteries workflows: derives
  state-of-charge (SoC), current/voltage datasets, and EIS metrics. Off by default.
- `--user-name NAME` — user name embedded in generated pair DTA/RAW templates. If omitted,
  the CLI prompts interactively on first use and caches the answer for the run.

## Relevant When Generating Definitions (`-g`)

- `-g`, `--generate_nexus_definition FILE` — generate `.nxd` (or YAML with `--yaml`).
- `-t`, `--template` — generate a single-scan SPEC template.
- `--yaml` — emit YAML definitions instead of `.nxd`.
- `--hdf5-option {links,extract}` — HDF5 generation mode (`1/2` aliases supported).
- `--single-file` — for directory input, generate one combined definition.
- `--multi-file` — for directory input, generate one definition per matched input.

## Relevant for Directory / Batch Inputs

- `-r`, `--recursive` — scan subdirectories.
- `--glob PATTERN` — global filter for matched files.
- `--glob-spec PATTERN` — SPEC-specific filter (overrides `--glob` for SPEC).
- `--glob-dta PATTERN` — DTA/DAT-specific filter (overrides `--glob` for DTA/DAT).
- `--no-group-dta-folders` — process DTA/DAT individually instead of grouping by folder.
- `--dry-run` — show planned processing without writing outputs.
- `--summary-only` — with `--dry-run`, print only the summary.

## Relevant for Metadata / Schema-Guided Placement

- `--metadata-csv FILE` — enrich variables (`variable_name, variable_description, units`).
- `--jsonld-structure FILE` — enable JSON-LD driven parsing/generation.
- `--nxdl-root PATH` — path to NXDL definitions.
- `--app-def NAME` — preferred NXDL application definition (for example `NXxas`).
- `--export-vars-csv FILE` — export parsed variable dictionaries.
- `-d`, `--dictionary` — print the parsed variable dictionary.
- `-D`, `--debug` — print the active `.nxd` line during conversion.

## Relevant for Validation / CSV Export Workflows

- `--validate` — run `punx` validation after `.nxs` generation.
- `--export-values-csv FILE` — export values from `.nxs`/HDF5 to CSV.
- `--export-values-prefix PATH` — restrict value export to an HDF5 subtree (must start with `/`).
- `--csv-delimiter CHAR` — CSV delimiter for value export (default `,`).