Command Line CLI

Command-line CLI

This page is a practical reference for ChemDraft’s JSON-Lines command-line interface.

Run every command from a checkout with pnpm -s chemdraft. The -s flag is required: without it, a pnpm script banner can appear on stdout and corrupt the JSON Lines stream. Successful jobs write an object with ok: true, identifying input, outputs, and warnings; failed jobs write ok: false and an error. Human progress belongs on stderr. Exit status is 0 when every job succeeds, 1 when an attempted job fails, and 2 for invalid arguments or batch input.

On macOS and Windows, the robust form is:

pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft --help

--config.shell-emulator=true is especially important on Windows: without it pnpm can double backslashes in arguments, changing paths and SMILES bond-direction marks. In PowerShell, quote comma-separated lists such as '1H,13C' and 'rdkit.composition,rdkit.crippen-logp'.

Shared input rules

Single-structure commands take --smiles; batch commands take a JSON array, commonly objects like {"name":"ethanol","smiles":"CCO"}. Names are unique case-insensitively, 1–100 characters, and use letters, numbers, spaces, underscores, or hyphens. Empty names, leading dots, path separators, and Windows device names are rejected on every platform. UTF-8 (with or without a BOM), BOM-marked UTF-16LE/BE, LF, and CRLF input files are accepted. PNG width is 16–4,000 pixels.

Commands

Command	Purpose	Essential inputs and output
render	Cropped structure SVG/PNG	--smiles or --batch; --out or --out-dir; `--format png
document	Editable native JSON document	--smiles or --batch; --out or --out-dir
render-document	Render native JSON or .chemdraft	--document, --out, `--format svg
grid	Named multiple-choice structure grid	--batch, --out ending .png or .svg
reaction	Reaction-scheme SVG/PNG	--rxn, or role-specific components, plus --out
analyze	Properties and predictions	--smiles or --batch; optional --methods, --format
name	OPSIN name-to-structure conversion	--name or --batch; optional --render, --allow-ambiguous
stereo	R/S and E/Z inspection	--smiles or --batch
nmr	¹H/¹³C predictions through optional plugin	--smiles or --batch; optional --nuclei, spectrum options
export	CDXML, PDF, SDF, MOL, or SMILES	--smiles or --batch; --format and destination

Render and document

pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft render --smiles 'CCO' --out ethanol.svg
pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft render --smiles 'CCO' --out ethanol --format both
pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft document --smiles 'C1CCC2CCCCC2C1' --out decalin.json

render accepts --width, --background white|transparent, --bond-length, and --padding. document produces chemdraft.document.v1 JSON containing editable object, atom, bond, and ring identifiers and page-pixel coordinates. render-document can render that JSON after styling, or a desktop .chemdraft envelope. SVG, PNG, and PDF render only its first page and warn when more pages exist; .chemdraft retains the complete document.

Grid and reaction

pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft grid --batch jobs.json --out questions.svg --columns 2 --labels letters
pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft reaction --rxn 'CC(=O)O.OCC>OS(=O)(=O)O>CC(=O)OCC' --out ester.png

For a grid, --labels is none, letters, or names; --columns, --width, --gutter, --padding, and --background are available. A reaction SMILES has exactly two > separators. Alternatively, repeat --reactant, --agent, and --product; this preserves each supplied dot-joined salt as one molecule object. --conditions adds arrow text and --arrow accepts forward, equilibrium, resonance, or retrosynthesis.

Reaction roles are explicit: reactants and products flank the arrow, and agents/conditions are shown above it.

Analysis, names, and stereochemistry

pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft analyze --smiles 'CC(=O)Oc1ccccc1C(=O)O' --methods 'rdkit.composition,rdkit.crippen-logp'
pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft name --name '2-acetoxybenzoic acid' --render aspirin.png
pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft stereo --smiles 'C/C=C/C'

analyze --format is json, md, or text; an md/text report without --out remains inside the JSON result’s report field. Read each method status and interpretation label. name converts with the bundled OPSIN runtime; ambiguous names fail unless --allow-ambiguous is supplied. stereo reports tetrahedral centres and stereogenic double bonds separately, using 0-based molfile atom/bond indices and identifying unspecified units.

NMR and export

pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft nmr --smiles 'CCO' --nuclei '1H,13C' --spectrum ethanol.svg
pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft export --smiles 'CCO' --out ethanol.sdf

NMR accepts --statistic median|mean, --ignore-labile, --width, and batch --spectrum-dir/--spectrum-format svg|png. It requires the external predictor checkout and owner trust described in MCP Server. Its shifts are predictions; J values and multiplicities are estimates.

export accepts cdxml, pdf, sdf, mol, and smi. A batch SDF/SMILES export combines records into one --out file; the other batch formats write named files into --out-dir. Query bonds are refused because their chemical bond order cannot be verified.

See also

• MCP Server
• Agent Setup Recipes
• Analysis and Properties
• File Formats and Compatibility