Convert CLI Options

This page documents the CLI options for converting molecular structure files between formats. Use chemsmart run convert --help for the complete list.

Basic Command Structure

chemsmart run convert [CONVERT_OPTIONS]

Convert Options

Option	Type	Description
`-i, --input`	string	Input molecular structure file for single-file conversion
`-o, --output`	string	Output file path (format is inferred from the extension). Required when `--input` is used
`-d, --directory`	string	Directory containing files to convert in batch mode
`-t, --filetype`	string	Input file type for batch directory conversion (e.g. `log`, `com`, `gjf`, `out`, `inp`, `xyz`, `sdf`, `pdb`, `cdxml`, `cdx`)
`-p, --program`	string	Computational program (`gaussian` or `orca`). Required when `--filetype` is `out`, because both Gaussian and ORCA use this extension
`--output-filetype`	string	Output file type used in batch mode when `--output` is not specified (default: `xyz`)
`-z/--no-z, --include-intermediate-structures/--no-include-intermediate-structures`	bool	Include all intermediate structures from multi-structure files (default: disabled)

Note

Provide either --input / --output (single-file) or --directory / --filetype (batch), not both.

Single-File Conversion

Single-file conversion infers the output format from the --output extension:

chemsmart run convert -i molecule.pdb -o molecule.xyz
chemsmart run convert -i molecule.log -o molecule.mol2

Batch Directory Conversion

Convert all matching files in a directory:

chemsmart run convert --directory /path/to/dir --filetype log --output-filetype xyz
chemsmart run convert -d . -t pdb --output-filetype xyz

Directory batch conversion uses a fixed whitelist (log, com, gjf, out, inp, xyz, sdf, pdb, cdxml, cdx). Formats such as .mol2 / .smi are available via single-file convert (-i / -o) only.

Output Formats and Conversion

Native writers (Molecule.write) support xyz, extxyz, com, pdb, and cosmorsxyz.

For any other output format, CHEMSMART falls back to Open Babel (via a temporary XYZ intermediate). This is used automatically by the convert CLI when the output extension is not a native writer format:

chemsmart run convert -i water.xyz -o water.mol2
chemsmart run convert -i water.pdb -o water.cml

Note

Because the write fallback uses a temporary XYZ file, charge, multiplicity, and bond connectivity are not carried into Open Babel output formats. Connectivity in the written file is regenerated by Open Babel from geometry.

Open Babel is included in the CHEMSMART conda environment. If you install CHEMSMART via pip and request a non-native output format, install Open Babel separately:

conda install -c conda-forge openbabel

If Open Babel is not installed, CHEMSMART raises an ImportError with installation instructions. Formats that Open Babel itself cannot write raise a ValueError.

Multi-structure conversion with -z / --include-intermediate-structures writes numbered files (basename_1.ext, basename_2.ext, …) rather than overwriting a single output path. This also applies to multi-fragment ChemDraw (.cdx / .cdxml) files; without -z, only the last molecule is written:

chemsmart run convert -i ensemble.pdb -o ensemble.xyz -z
chemsmart run convert -i two_molecules.cdxml -o two_molecules.xyz -z

Note

Read vs write fallbacks: unsupported input extensions try Open Babel first, then ASE (periodic / ASE-only extensions skip Open Babel; see Molecule Input Formats). Unsupported output formats fall back to Open Babel.

Next Steps

For supported input formats and file reading details, see: