nmrium-cli

CLI tool for processing NMR spectroscopy data and preparing exercise collections compatible with NMRium.

Installation

npm install --global nmrium-cli

This adds an nmrium command to your system.

Commands

All commands accept a global --dataDir, -d <path> option to specify the root data directory. By default it is the current working directory.

createGeneralTOC

Recursively scans a folder of NMR data files and generates a toc.json (and sub-TOC files) that NMRium can load.

nmrium createGeneralTOC
nmrium createGeneralTOC --dataDir /path/to/nmr-data

createExercisesTOC

Builds toc.json for an exercise collection. Each exercise folder must contain a structure.mol file and one or more JCAMP-DX spectra (.jdx / .dx).

nmrium createExercisesTOC [options]

| Option | Alias | Type | Default | Description | |---|---|---|---|---| | --appendIDCode | -i | boolean | false | Include the OpenChemLib IDCode in each TOC entry | | --appendNoStereoIDCodeHash | -s | boolean | false | Add a hash computed without stereo information so wrong-stereo answers are still accepted | | --appendRacemateIDCodeHash | | boolean | true | Accept any enantiomer as a correct answer | | --cleanJCAMP | | boolean | false | Keep only the first spectrum block in each JCAMP-DX file |

createExercisesCorrection

Scans all exercise folders and writes a Markdown file listing all structures (with SVG images). Useful for preparing answer keys.

nmrium createExercisesCorrection

predictSpectra

For every folder that contains a structure.mol file, predict a 1H NMR spectrum and write it as a JCAMP-DX file.

nmrium predictSpectra [options]

| Option | Alias | Type | Default | Description | |---|---|---|---|---| | --frequency | -b | number | 400 | Spectrometer frequency in MHz |

createMolfilesFromFiles

Converts a .txt file (one SMILES per line) or a .sdf file into a numbered folder structure, each containing a structure.mol file. Useful for bulk-creating exercises from a list of molecules.

nmrium createMolfilesFromFiles

appendLinks

Replaces the <-- LINKS --> placeholder in README.md with NMRium links derived from the toc.json and the GitHub Pages URL of the repository.

nmrium appendLinks [options]

| Option | Alias | Type | Default | Description | |---|---|---|---|---| | --baseURL | -b | string | https://www.nmrium.org/teaching#?toc= | Base URL prepended to each TOC link |

deleteJSONs

Removes all generated *.json files from the data tree. Run this before regenerating to ensure a clean state.

nmrium deleteJSONs

deleteStructures

Removes all .mol structure files from the data tree.

nmrium deleteStructures

Folder structures

Exercise collection (createExercisesTOC)

Exercises are organised in a two-level hierarchy. Each leaf folder contains one structure.mol and any number of spectrum files. The command packages each exercise into a self-contained .nmrium.zip archive and removes the source folder.

exercises/
├── index.yml                     # optional: workspace configuration
├── Series1/                      # group (generates toc_Series1.json)
│   ├── Exercise1/
│   │   ├── structure.mol         # required
│   │   └── 1h.jdx
│   └── Exercise2/
│       ├── structure.mol
│       ├── 13c.jdx
│       └── cosy.jdx
├── Chiral/                       # flat exercise (no sub-group)
│   ├── structure.mol
│   └── 1h.jdx
└── noMF/                         # group with custom workspace config
    ├── index.yml
    ├── exercise1/
    │   ├── structure.mol
    │   └── 1h.jdx
    └── exercise2/
        ├── structure.mol
        └── 1h.jdx

After running createExercisesTOC, source folders are replaced by archives:

exercises/
├── Chiral.nmrium.zip             # generated: self-contained archive
├── Exercises3.nmrium.zip         # generated
├── Series1/
│   ├── Exercise1.nmrium.zip      # generated
│   └── Exercise2.nmrium.zip      # generated
├── noMF/
│   ├── exercise1.nmrium.zip      # generated
│   └── exercise2.nmrium.zip      # generated
├── toc.json                      # generated: master TOC
├── toc_Series1.json              # generated: sub-TOC for Series1
└── toc_noMF.json                 # generated: sub-TOC for noMF

Folder names prefixed with numbers (e.g. 01_, 001_) are sorted numerically and the prefix is stripped from the displayed title.

General NMR data collection (createGeneralTOC)

Any mix of supported formats can coexist. Each sample folder is packaged into a self-contained .nmrium.zip archive placed next to it; the source folder is then removed.

nmr-data/
├── index.yml                     # optional: workspace configuration
├── Group1/                       # sub-group (generates toc_Group1.json)
│   ├── index.yml                 # optional: group-level config
│   ├── settings.json             # optional: NMRium settings applied to this group
│   ├── acetone/                  # source folder (removed after archiving)
│   │   ├── 1h.jdx
│   │   └── 13c.jdx
│   └── ethylvinylether/
│       └── 1h.jdx
├── aspirin/                      # Bruker FID folder
│   └── 1/                        # experiment number
│       ├── fid
│       └── acqu / acqus
└── ethylbenzene/
    ├── 1h.jdx
    ├── 13c.jdx
    └── structure.mol

After running createGeneralTOC, source folders are replaced by archives:

nmr-data/
├── Group1/
│   ├── acetone.nmrium.zip        # generated
│   └── ethylvinylether.nmrium.zip
├── aspirin/
│   └── 1.nmrium.zip              # generated
├── ethylbenzene.nmrium.zip       # generated
├── toc.json                      # generated: master TOC
└── toc_Group1.json               # generated: sub-TOC for Group1

Bruker FID structure

Bruker data is stored in numbered experiment folders following the standard Bruker directory layout:

sample/
└── 1/                            # experiment number
    ├── fid                       # raw FID data
    ├── acqu                      # acquisition parameters
    ├── acqus
    └── pdata/
        └── 1/                    # processed data
            ├── proc
            ├── procs
            └── peaklist.xml

QUAD Systems structure

sample/
├── proton/
│   └── 1/
│       ├── data.dat              # raw data
│       ├── header.xml            # metadata
│       ├── Serie.xml
│       ├── PulseAcquisition.sxml
│       └── Proc/
│           └── 0/
│               ├── data.dat      # processed data (used when present)
│               └── header.xml
└── carbon/
    └── 2/
        └── ...                   # same structure

Supported file formats

| Format | File / folder detection | |---|---| | Bruker | folder containing fid, ser, 1r, or data.dat | | JCAMP-DX | .jdx, .dx files | | QUAD Systems | folder with data.dat + header.xml + Proc/ | | Varian | .zip archives | | Molfile | .mol structure files | | SMILES / SDF | .txt (one SMILES per line), .sdf |

Workspace configuration (index.yml)

Place an index.yml file in any folder to customise how that folder and its children are processed.

Available properties

| Property | Type | Description | |---|---|---| | menuLabel | string | Display label shown in the NMRium menu | | settingsFilename | string | Path (relative to the folder) to a JSON file containing NMRium settings | | default | object | Default values inherited by every child folder in this group |

Any extra keys are passed through as metadata (e.g. noMF, description).

Example: group with a shared label and settings

# Group1/index.yml
menuLabel: 'Organic Chemistry — Series 1'
default:
  settingsFilename: settings.json

Example: group-level defaults without a mol file

# noMF/index.yml
default:
  noMF: true
  description: 'Determine the molecular formula and find the structure of the unknown compound.'

The default block is merged into every child folder's configuration, so you do not need to repeat settings in each subfolder.

Typical exercise workflow

cd /path/to/exercises

# 1. Generate the TOC — packages every exercise into a .nmrium.zip archive
#    and removes the source folders
nmrium createExercisesTOC

# 2. Inject NMRium links into README.md (requires a GitHub remote)
nmrium appendLinks

Local testing

Run the test suite once to populate the output/ directory:

npm test

Then serve it with CORS headers enabled (-C is short for --cors):

npx serve -C output

The server starts on http://localhost:3000. Use the links below to open each dataset in NMRium:

Exercises (teaching mode)

Open at https://app.nmrium.com/teaching/exercises — NMRium validates idCodeHash and lets students draw and check their answer.

| Dataset | Link | |---|---| | Exercises | open | | ACD Prediction | open |

General NMR data (viewer mode)

Open at https://app.nmrium.com — no exercise validation, just spectrum viewing.

| Dataset | Link | |---|---| | Bruker | open | | JCAMP-DX | open | | QUAD Systems | open |

Note: Support for loading .nmrium.zip archives from a TOC was added in NMRium on 2026-04-28. Make sure app.nmrium.com is running a release from that date or later.

License

MIT