# Getting Started

Install the CLI, generate a NeXus definition, and convert it to a NeXus HDF5 file.

## Installation

```bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install .
```

> Want to experiment without installing? Run `python3 NeXusCreator.py -h` directly from the clone.

## Generate a NeXus Definition (`.nxd`/YAML)

```bash
# From a SPEC file
nexuscreator -g out.nxd -i data.spec

# Single-scan template for later multi-scan conversion
nexuscreator -g template.nxd -i data.spec -t

# From a batteries folder (DTA/DAT)
nexuscreator -g out.nxd -i /path/to/folder -b batteries
```

Add `--yaml` to produce YAML-based templates instead of `.nxd` files.

## Convert to NeXus HDF5 (`.nxs`)

```bash
# Single output
nexuscreator -n def.nxd -i data.spec -o out.nxs

# One file per scan plus a master with external links
nexuscreator -n def.nxd -i data.spec -o out.nxs -f

# Batteries or DTA/DAT inputs
nexuscreator -n def.nxd -i data.dta -o out.nxs
nexuscreator -n def.nxd -i /path/to/folder -b batteries -o out.nxs
```

## Placement and Metadata (Optional)

```bash
# Bias placement using NXDL application definitions
nexuscreator -g out.nxd -i data.spec --nxdl-root /path/to/nxdl --app-def NXxas

# Enrich variables with descriptions/units from CSV (name, description, units)
nexuscreator -g out.nxd -i data.spec --metadata-csv femtospex.csv

If `--nxdl-root` is omitted, NeXusCreator uses `external_references/nexus/nexus_definitions` when
present.
```

Next steps: explore the [Usage guide](usage.md) and the [CLI reference](cli.md).