Command line interface
Inspect structures and use MolFrame in shell pipelines.
The molframe executable is the command-line interface. It writes requested results to standard output and diagnostics to standard error, keeping pipelines clean.
Discover commands
molframe --help
molframe info --helpStart with info to summarise a structure:
molframe info 1ubq.pdbThe binary is built from the molframe-cli crate with the complete feature set. Command names and options are generated by Clap; use local --help output as the authoritative reference for your installed version.
Explicit scientific parameters
Commands that embody a scientific definition take every threshold as a required
flag. There is no literature default hidden in the binary, so a result's
command line is its complete specification, and --provenance PATH records it.
Chemistry-aware commands also take --ccd PATH --ccd-version RELEASE (or the
chem configuration section), because donor, acceptor, charge and aromatic
roles come from a named dictionary release rather than residue names.
Interactions
molframe interactions runs the non-covalent analyses over CCD-annotated
chemistry and prints one row per interaction. Atoms and residues are reported
by their zero-based index in the structure.
| Command | Required parameters | Columns |
|---|---|---|
hbonds | --max-donor-acceptor-distance, --min-angle-degrees (--periodic applies the unit cell) | donor, hydrogen, acceptor, distances, angle_degrees |
salt-bridges | --max-distance | anion, cation, distance_angstrom |
pi-stacking | --max-centre-distance, --max-parallel-angle, --min-perpendicular-angle, --eigen-relative-tolerance, --eigen-maximum-sweeps | residue pair, centre_distance_angstrom, angle_degrees, kind |
cation-pi | --max-distance, --max-face-angle, the eigen controls | cation_residue, ring_residue, distance_angstrom |
water-bridges | as hbonds | water, first, second |
molframe interactions hbonds model.pdb --ccd CCD.cif --ccd-version 2026-10-03 \
--max-donor-acceptor-distance 3.5 --min-angle-degrees 120 --format tsvHydrogen bonds need explicit hydrogens; a structure without them reports no bond rather than guessing a direction.
Validation
molframe validate FILE --checks a,b,c runs the named checks and prints one
check, item, value row per finding; it exits non-zero when any check
reports one. Beyond the basic checks (core, quality, geometry, clashes,
completeness, altloc, ccd-completeness, bfactor) the structural and
reference checks are:
| Check | Required parameters |
|---|---|
valence | none (needs a bond table: read connectivity or pass --ccd) |
ligand | --ligand-bond-tolerance |
chirality | CCD, --chirality-minimum-volume |
cis-peptide | CCD, --role-profile, --cis-threshold-degrees |
nucleic | CCD, --role-profile, --base-plane-deviation, --glycosidic-range MIN MAX, --phosphodiester-range MIN MAX, --plane-relative-tolerance, --plane-maximum-sweeps |
ramachandran | CCD, --role-profile, --reference-library, one --basin REGION=DISTRIBUTION per basin, --ramachandran-minimum-probability |
rotamer | CCD, --rotamer-profile, --reference-library, --rotamer-minimum-probability |
plane-restraints | --plane-restraints, --planarity-tolerance, --plane-relative-tolerance, --plane-maximum-sweeps |
tls | --tls-groups, --tls-max-deviation, --tls-symmetry-tolerance |
Backbone and nucleotide checks find atoms through a polymer role profile you
write (see sse), never by atom name. The file formats of the reference
library, rotamer profile, plane restraints and TLS groups are documented with
the analysis kernels. A check that cannot assess some of its targets prints the
coverage (assessed N of M) on standard error rather than passing silently.
Comparison
molframe compare MODEL REFERENCE --metrics a,b prints one metric, value
row per score. The model and the reference share atom numbering for every
metric but ce, which aligns guide atoms in sequence order, and --map-chains,
which maps chains by sequence before dockq or qs.
| Metric | Required parameters |
|---|---|
lddt, tm-score, gdt-ts, gdt-ha | lDDT: --lddt-radius, --lddt-minimum-distance, --lddt-tolerances, --lddt-empty |
dockq | --receptor, --ligand, --contact-distance, --ligand-scale, --interface-scale |
qs | --receptor, --ligand (the chain pair), --contact-distance |
contact-similarity | --contact-distance, --min-separation |
cad | --cad-probe, --cad-density, --radii |
ce | --guide, --ce-window, --ce-max-gap, --ce-max-paths, --ce-fragment-threshold, --ce-path-threshold, --ce-memory-limit (--ce-significance adds the z-score) |
interface-rmsd, pocket-rmsd | --region, --alignment fit|none |
ligand-rmsd | CCD, --ligand-selection, --ligand-component, --ligand-automorphism-limit; --align-on fits the model first |
ligand-rmsd compares the atoms both structures have and takes the best of the
chemically equivalent atom mappings of that fragment, so a ring flip or a
swapped carboxylate oxygen costs nothing and a missing hydrogen does not
exhaust the mapping bound. A control for a metric that was not selected is
refused rather than ignored.
Contacts and normal modes
| Command | Required parameters | Columns |
|---|---|---|
contact-map FILE | --cutoff, --min-separation | first_residue, second_residue, min_distance_angstrom |
native-contacts REFERENCE TARGET | --cutoff, --contact-tolerance, --match index|names | native, kept, fraction |
nma FILE | --network gnm|anm, --sites, --contact-distance, --mode-count, --zero-mode-tolerance, --memory-limit, --table modes|fluctuations; gnm also --reduction | mode, eigenvalue or site, fluctuation |
native-contacts counts a reference pair within --cutoff as native and keeps
it when the target pair is within the cutoff plus --tolerance ångström (default
0, so a structure compared with itself has Q = 1). --match index (default)
needs the structures to share atom numbering; --match names pairs atoms by
chain, residue number, residue name and atom name, and counts only contacts
between atoms present in both. nma
prints the zero-mode count on standard error; GNM fluctuations are summed over
the requested modes only, so they are a lower bound unless every mode is asked
for. --reduction fast lets the GNM solver reorder floating-point reductions;
deterministic is bit-identical at any worker count.
Chemistry
| Command | Required parameters | Columns |
|---|---|---|
chem peoe FILE | CCD, --passes, --initial-damping, --damping-factor, --minimum-difference, --profile | atom, charge |
chem smarts TARGET --pattern SMARTS | CCD | match, query_atom, atom |
chem peoe prints one elementary-charge value per atom in file order and, on
standard error, whether it came from the file or from PEOE under the named
dictionary release. A residue whose atom names the dictionary does not define
is an error, never a zero charge. chem smarts searches the annotated
structure, or with --component a dictionary component (TARGET is then its
identifier and rows name atoms). Structure matches are within residues, since
polymer links are not applied: a peptide-bond pattern needs a structure whose
residues are already linked.
Crystallography
| Command | Required parameters | Output |
|---|---|---|
crystal mtz-info FILE | --table summary|columns | header properties, or one row per column |
crystal map-stats FILE | none (--histogram-bins with --histogram-range MIN MAX adds bins) | count, extrema, mean, population sigma |
crystal map-correlation OBSERVED CALCULATED | none | Pearson coefficient over identically placed maps |
crystal mates FILE | --cutoff, --candidate-limit | atoms of neighbouring symmetry copies |
crystal mates needs a space group the catalogue knows (a PDB CRYST1 record
or mmCIF symmetry); without one it refuses rather than guessing a lattice. It
lists only other copies: the deposited copy's own atoms are the molecule, not
its crystal contacts. --candidate-limit bounds the images examined and is
conservative, so a packed cell needs a large value; exceeding it is an error,
not a truncated list. Map computation (FFT, density from a model) is out of
scope.
Trajectories
molframe trajectory rmsf FILE streams an XTC, DCD or TRR trajectory and prints
each atom's root-mean-square fluctuation about its mean position
(atom, rmsf_angstrom) in one pass with memory independent of the frame
count. Frames are used as stored: none is fitted, so superpose the trajectory
first when overall motion should not count as fluctuation. The other
trajectory commands are info, convert, extract, contacts, sasa and
rmsd.
Use in reproducible workflows
Keep source files, command lines, and any parsing-policy flags in your workflow record. Structural-file ambiguity is part of the scientific input, not merely an I/O detail.