CLI Reference

Full flag reference for xyzrender. See also xyzrender --help.

Input / Output

Flag	Description
INPUT	Input file (.xyz, .mol, .sdf, .mol2, .pdb, .smi, .cif, .cube/.cub, .com, .gjf, .inp, .nw, .vasp, POSCAR, .in, .fdf, .abi, .coord, QM .out / .log …) — omit to read from stdin
-o, --output	Static output path (.svg, .png, .pdf); defaults to {basename}.svg
--smi SMILES	Embed a SMILES string into 3D (requires rdkit: pip install 'xyzrender[smi]')
--mol-frame N	Record index in multi-molecule SDF (default: 0)
--rebuild	Ignore file connectivity; re-detect bonds with xyzgraph
-c, --charge	Molecular charge
-m, --multiplicity	Spin multiplicity
--bohr	Input coordinates are in Bohr (force conversion to Angstrom)
--config	Config preset (default, flat, paton, pmol, skeletal, bubble, vdw, tube, mtube, btube, wire, graph) or path to JSON file
-d, --debug	Debug logging

Styling

Flag	Description
-S, --canvas-size	Canvas size in px (default: 800)
-a, --atom-scale	Atom radius scale factor
-b, --bond-width	Bond stroke width
-s, --atom-stroke-width	Atom outline stroke width
--bond-color	Bond color (hex or named)
--bond-outline-color	Bond edge stroke color (default: black)
--bond-outline-width	Bond edge stroke width in px (0 = off)
--no-bonds	Hide all bonds (e.g. space-filling style)
--unbond SPEC [...]	Hide bonds by rule or index*. all / * hides every covalent bond
--bond PAIR [...]	Force-show/add bonds: 1-indexed pairs (1-3 4-5). Overrides --unbond
--haptic	Replace pi-coordination bond fans with single centroid bonds (dotted). Inherits overlay / ensemble colour from the metal atom
--atom-opacity ATOMS VALUE	Per-atom fill opacity (repeatable), e.g. --atom-opacity "1-5" 0.3. Affects the atom circle only; adjacent bonds stay fully opaque
-B, --background	Background color
-t, --transparent	Transparent background
--grad / --no-grad	Radial gradient toggle
--atom-gradient-strength	Atom gradient strength (default: 1.0)
--bond-gradient / --no-bond-gradient	Cylinder shading on bonds (3D tube look)
--bond-gradient-strength	Bond cylinder gradient strength (default: 0.3)
-F, --fog-strength	Depth fog strength
--fog / --no-fog	Depth fog toggle
--bo / --no-bo	Bond order rendering toggle
--bond-by-element / --no-bond-by-element	Color bonds by endpoint atom colors
--radius-scale ATOMS FACTOR	Scale selected atoms (repeatable). Multiplies on top of -a
--region ATOMS CONFIG	Render atom subset with a different style (repeatable). Selectors: indices "1-5", elements "Pt", categories (see below)
-Hls, --hue-shift-factor	Hue gradient contrast (advanced; default per preset)
-hLs, --light-shift-factor	Lightness gradient contrast (advanced)
-hlS, --saturation-shift-factor	Saturation gradient contrast (advanced)
--skeletal-label-color	Override all element label colours in --config skeletal

*— categories (M, sbm, L, het, hal, pnic, chal, noble, triel, tetrel), pair specs (M-L, Fe-het, M-hal), pi-coordination (M-pi, pi), element (Li), atom index (2), or pair (1-3). Comma or space separated.

Display

Flag	Description
--hy [ATOMS]	Show H atoms (no args = all, or indices like "1-5,8")
--no-hy	Hide all H atoms
--only ATOMS	Render only selected atoms before orientation/canvas fitting. Repeatable; same selector grammar as --hl, e.g. "1-24", "C,N,O", "M". Cube/surface fields are not cropped
--exclude ATOMS	Remove selected atoms before orientation/canvas fitting. Repeatable; same selector grammar as --hl, e.g. "25-40", "Na,Cl". Cube/surface fields are not cropped
-k, --kekule	Use Kekulé bond orders (no aromatic 1.5)
--vdw [ATOMS]	vdW spheres (no args = all, or selectors like "1-6", "M", "Pt")
--vdw-opacity	vdW sphere opacity (default: 0.25)
--vdw-scale	vdW sphere radius scale
--vdw-gradient-strength	vdW sphere gradient strength (default: 1.6)
--vdw-interlocking / --no-vdw-interlocking	Render the --vdw overlay as interlocked silhouettes (default: on)
--atom-interlocking / --no-atom-interlocking	Render primary atom spheres as interlocked silhouettes; the vdw preset turns this on for space-filling renders
--vdw-outline-width FLOAT	vdW overlay outline width (default: 0 = no outline)
--vdw-outline-color COLOR	vdW overlay outline colour
--h-scale FLOAT	H-atom radius scale (primary atoms; default: 0.6)
--vdw-h-scale FLOAT	H-atom radius scale on the --vdw overlay (default: 0.7)
--mol-color COLOR	Flat color for all atoms and bonds (overrides CPK). Highlight paints on top
--hl ATOMS [COLOR]	Highlight atom group. Accepts the same selectors as --only/--region — indices/ranges ("1-5,8"), elements ("C,N"), or categories ("M", "het", "hal", "chal", "pnic", …). Repeatable; auto-colours from palette if no colour given
--dof	Depth-of-field blur (does not affect bonds/lines)
--dof-strength FLOAT	DoF max blur strength (default: 3.0)
--glow ATOMS	Add blurred glow under selected atoms (same selector grammar as --hl / --vdw)
--glow-strength FLOAT	Glow blur strength (default: 5.0)

Orientation

Flag	Description
-I, --interactive	Interactive rotation (see --viewer)
--viewer {vmol,ase}	Viewer backend for -I: vmol (default, requires vmol) or ase (requires ase). Close the ASE window to confirm; press z then q in vmol
--orient / --no-orient	Auto-orientation toggle
--ref [FILE]	Save/load orientation reference (reference.xyz by default)

Transition states / NCI graph overlay

These flags draw graph-detected bond overlays (dashes / dots) on top of the molecular skeleton. The volumetric NCI surface (--nci-surf) is documented in the Surfaces section below.

Flag	Description
--ts	Auto-detect TS bonds via graphRC
--ts-frame	TS reference frame (0-indexed)
--ts-bond PAIR	Manual TS bond pair(s) (1-indexed, e.g. "1-2")
--ts-color	Colour for dashed TS bonds (hex or named); overrides --ts-element
--ts-element / --no-ts-element	Atom-coloured halves on TS dashes
--ts-dash LEN,GAP	TS dash length,gap as bond-width multiples (default 1.2,2.2)
--ts-width MULT	TS line width as a bond-width multiple (default 1.2)
--nci	Auto-detect NCI interactions (graph topology, not the volumetric surface — see --nci-surf)
--nci-bond PAIR	Manual NCI bond pair(s) (1-indexed)
--nci-color	Colour for dotted NCI/haptic bonds (hex or named); overrides --nci-element
--nci-element / --no-nci-element	Atom-coloured halves on NCI/haptic dots (on in pmol/btube/tube/mtube)
--nci-dash LEN,GAP	NCI/haptic dot length,gap as bond-width multiples (default 0.08,2.0)
--nci-width MULT	NCI/haptic line width as a bond-width multiple (default 1.0)

Surfaces

Flag	Description
--mo	Render MO lobes from .cube or .cub input
--mo-colors POS NEG	MO lobe colors (hex or named)
--mo-outline-width [PX]	Outline stroke per lobe (solid style only; pair with --opacity 1.0 for crisp edges). Bare flag = 5.0; 0 = off
--mo-outline-color COLOR	Outline color (default: black)
--mo-blur SIGMA	MO Gaussian blur sigma (default: 0.8, advanced)
--mo-upsample N	MO contour upsample factor (default: 3, advanced)
--flat-mo	Disable depth-fog colour blend on MO lobes (textbook flat colours)
--dens	Render density isosurface from .cube or .cub input
--dens-color	Density surface color (default: steelblue)
--esp CUBE	ESP cube file for potential coloring (implies --dens)
--nci-surf CUBE	Interaction surface cube — auto-classified as low_field (NCIPLOT RDG) or high_field (Multiwfn IGMH δg)
--nci-mode MODE	NCI surface coloring: avg (default), pixel, uniform, or a colour name/hex
--iso	Isosurface threshold. Defaults: MO 0.05, density/ESP 0.001. Interaction surfaces are starting points — tune per cube: low-field RDG 0.3; IGMH dg_inter 0.005, dg_intra 0.05–0.3
--opacity	Surface opacity multiplier (default: 1.0; >1 boosts)
--surface-style STYLE	Surface rendering style: solid (default), mesh, contour, dot. Density falls back to contour for mesh; ESP raster ignores style

Convex hull / faces / pore

Flag	Description
--hull [INDICES ...]	Draw convex hull (no args = all heavy atoms; rings = auto aromatic rings; faces = 2D structural faces; or 1-indexed subsets e.g. 1-6 or 1-6 7-12)
--hull-color COLOR [...]	Hull fill color(s) (hex or named, one per subset)
--hull-opacity FLOAT	Hull fill opacity (0–1)
--hull-color-type {type,size,env}	Ring colouring: type (atom types + size, default), size (size only), env (type + ring fusion)
--hull-edge / --no-hull-edge	Draw/hide non-bond hull edges (default: on)
--hull-edge-width-ratio FLOAT	Hull edge stroke width as fraction of bond width (default: 0.4)
--ring-min-size N	Minimum ring size for --hull faces / --pore (default: 3)
--ring-max-size N	Maximum ring size for --hull faces / --pore (default: 100)
--face-planarity FLOAT	Planarity tolerance for 3D face detection: 0 = strict, 1 = permissive (default: 0.25)
--pore	Detect pore cavities and draw inscribed sphere(s)
--pore-color	Pore sphere colour (default: warm yellow)
--pore-opacity FLOAT	Pore sphere opacity (default: 0.5)

Structural overlay / ensemble

Flag	Description
--overlay FILE	Second structure to overlay (RMSD-aligned onto the primary). Different atom counts handled via shared-scaffold alignment
--overlay-color COLOR	Overlay atom colour (bonds auto-darkened 30 %)
--opacity FLOAT	Transparency 0–1. Applied to the overlay when --overlay is set, to the ensemble when --ensemble is set, else to surfaces
--overlay-atom-scale FLOAT	Absolute atom radius scale for the overlay only (mirrors --atom-scale)
--overlay-bond-width FLOAT	Absolute bond width for the overlay only
--overlay-unbond SPEC [...]	Hide bonds on the overlay only (same grammar as --unbond; indices are overlay-local)
--overlay-bond PAIR [...]	Force-show / add bonds on the overlay only (1-indexed, overlay-local)
--overlay-show SPEC [...]	Render only these overlay atoms (same selector grammar as --hl). Applied after alignment so the fit still uses the full scaffold
--overlay-ts	Run graphRC TS detection on the overlay (mirrors --ts; soft-fails if overlay has no freq data)
--overlay-ts-bond PAIR	Manual TS bond pair(s) on the overlay, 1-indexed in the overlay’s atom list
--align / --no-align	Force / skip Kabsch/MCS alignment for --overlay and --ensemble. Default: on
--ensemble	Ensemble overlay for multi-frame XYZ trajectories; conformers default to CPK atom colours
--ensemble-color VALUE	Palette name (viridis, plasma, spectral, coolwarm, RdBu, rainbow, batlow, roma, vik, bam, managua), a single colour, or comma-separated colours
--align-atoms SELECTOR	Alignment candidates for --overlay and --ensemble (min 3 atoms). 1-indexed IDs (1,2,3, 1-6), element symbols (Fe,P,Cl), categories (M, L, het, sbm), or a mix (1-5,Fe). Metal-containing specs pivot on the metal so paired metals coincide; otherwise MCS + K-subset Kabsch picks the lowest-RMSD candidate

Fine-grained overlay style (atom_stroke_width, atom_stroke_color, bond_color, bond_outline_*) lives in preset JSON or OverlayConfig only — not exposed as CLI flags.

Annotations

Flag	Description
--measure [TYPE...]	Print bond measurements to stdout (d, a, t; combine or omit for all)
--idx [FMT]	Atom index labels in SVG (sn = C1, default; s = C; n = 1)
-l TOKEN...	Inline SVG annotation (repeatable); 1-based indices
--label FILE	Bulk annotation file (same syntax as -l)
--label-size PT	Label font size (overrides preset)
--stereo [CLASSES]	Stereochemistry labels from 3D geometry. Optional comma-separated class filter: point, ez, axis, plane, helix. Omit to show all
--stereo-style STYLE	R/S label placement: atom (centered, default) or label (offset)
--cmap FILE	Per-atom property colormap (1-indexed atom index, value)
--cmap-range VMIN VMAX	Explicit colormap range (default: auto from file)
--cmap-symm	Symmetric colormap range about zero: `[-max(
--cmap-palette NAME	Shared scalar palette override (viridis for --cmap, rainbow for --esp)
--cbar	Add a vertical colorbar on the right for --cmap or --esp

Vector arrows

Flag	Description
--vector FILE	Path to a JSON file defining 3D vector arrows for overlay
--vector-scale FACTOR	Global length multiplier for all vector arrows

GIF animations

Flag	Description
--gif-rot [AXIS]	Rotation GIF (default axis: y). Combinable with --gif-ts and --gif-bounce
--gif-bounce DEG[,AXIS]	Bounce rotation: starts at the original orientation, then rotates to +DEG, back through 0, and to -DEG on the rotation axis (y by default). Append ,AXIS to override
--gif-ts	TS vibration GIF (via graphRC)
--gif-trj	Trajectory / optimisation GIF (multi-frame input)
--trj-bonds	Re-detect bonds for every frame (NEB-TS MEPs and other trajectories with changing connectivity)
--gif-diffuse	Diffuse / assembly GIF — atoms scatter and reassemble
--diffuse-frames N	Number of diffuse frames (default: 60)
--diffuse-noise FLOAT	Per-frame random walk noise (default: 0.3)
--diffuse-bonds {fade,show,hide}	Bond visibility during diffuse (default: fade)
--diffuse-rot [DEG]	Add partial rotation during diffuse (default: 180°)
--diffuse-forward	Play forward (molecule → noise) instead of assembly
--anchor ATOMS	Atoms that stay fixed during --gif-diffuse, e.g. "1-5,8"
-go, --gif-output	GIF output path (default: {basename}.gif)
--gif-fps	Frames per second (default: 10)
--rot-frames	Rotation frame count (default: 120)
--vib-frames	Vibration frames for --gif-ts (default: 20)

Available rotation axes: x, y, z, xy, xz, yz, yx, zx, zy. Prefix - to reverse (e.g. -xy). For crystal inputs, a 3-digit Miller index string is also accepted (e.g. 111, 001).

Crystal / unit cell

Flag	Description
--cell	Draw unit cell box from Lattice= in extXYZ (usually auto-detected)
--cell-color	Cell edge color (hex or named, default: #333333)
--cell-width	Unit cell box line width (default: 1.5)
--no-cell	Hide the unit cell box
--ghosts / --no-ghosts	Show/hide ghost (periodic image) atoms outside the cell
--ghost-opacity	Opacity of ghost atoms/bonds (default: 0.5)
--axes / --no-axes	Show/hide the a/b/c axis arrows
--axis HKL	Orient looking down a crystallographic direction (e.g. 111, 001)
--supercell M N L	Repeat the unit cell M×N×L times along a/b/c (requires lattice/unit-cell data; default: 1 1 1)