molstar-cli

Open local structure and map files in the Mol* viewer from the terminal.

$ pip install molstar-cli
$ molstar 5me2.cif emd_3488.map.gz
Mol* viewer: http://127.0.0.1:34037/MtXDcbb3cYRnGhsxczKvZw/
Press Ctrl-C to stop.

All files open together in one Mol* scene in your default browser — e.g. a model fitted into its cryo-EM map. The Mol* viewer is bundled, so it works offline; there are no dependencies beyond Python ≥ 3.10.

Usage

molstar FILE [FILE ...] [-p PORT] [--no-browser]

$ molstar *.cif                      # several structures, one scene
$ molstar model.cif emd_1234.map.gz  # model + EMDB map
$ molstar PDBDEV_00000001.cif        # integrative (IHM) models, incl. coarse-grained beads

The command keeps serving while you look at the structures; stop it with Ctrl-C. Reloading the browser tab re-reads the files from disk.

Supported formats

Anything Mol*'s Open Files dialog accepts, detected by file extension, optionally wrapped in .gz or .zip:

• Structures: mmCIF / PDBx (.cif, .mmcif, .mcif) including IHM integrative models, BinaryCIF (.bcif), PDB (.pdb, .ent), PDBQT, PQR, GRO, XYZ, SDF / MOL / MOL2, LAMMPS data/dump
• Volumes: CCP4 / MRC / MAP (.map, .mrc, .ccp4 — EMDB maps), DSN6 / BRIX, DX, Cube, density server CIF, MTZ
• Trajectories and topologies: DCD, XTC, TRR, NetCDF, PSF, PRMTOP, TOP
• Other: PLY / OBJ meshes, MolViewSpec (.mvsj, .mvsx), Mol* sessions (.molj, .molx)

Unsupported files are skipped with a warning in the Mol* log panel.

Maps open at Mol*'s default isovalue (2σ) — the EMDB-recommended contour level is not stored in the map file. Adjust it in the Volume panel on the right.

Remote machines

With --no-browser, or on a Linux machine without a display (e.g. over SSH), molstar doesn't start a browser; it prints an ssh -L command instead:

server$ molstar model.cif
Mol* viewer: http://127.0.0.1:41235/Xy.../
On a remote machine? Run `ssh -L 41235:127.0.0.1:41235 server` on your computer, then open the URL above there.
Press Ctrl-C to stop.

Use --port to keep the same forwarded port between runs.

Security

The server listens on 127.0.0.1 only, every URL carries a random token, and only the files named on the command line can be read — no directory listing, no other paths.

Development

$ python -m venv .venv && .venv/bin/pip install -e . pytest
$ .venv/bin/pytest

Updating the bundled Mol*

The prebuilt viewer from the molstar npm package is vendored in molstar_cli/static/molstar/ (no Node.js needed):

$ python scripts/update_molstar.py 5.11.0

Check that it loads, then commit the result.

Releasing

Create a GitHub release with a tag like v0.0.2. The package version is taken from the tag, so there is nothing to bump. The Publish to PyPI workflow builds and uploads it using trusted publishing (PyPI publisher: owner aozalevsky, repository molstar_cli, workflow publish.yml, environment pypi).

Citing Mol*

If you use Mol* in your work, please cite:

D. Sehnal, S. Bittrich, M. Deshpande, R. Svobodová, K. Berka, V. Bazgier, S. Velankar, S.K. Burley, J. Koča, A.S. Rose. Mol* Viewer: modern web app for 3D visualization and analysis of large biomolecular structures. Nucleic Acids Research 49(W1), W431–W437 (2021). doi:10.1093/nar/gkab314

License

MIT. The bundled Mol* viewer is © Mol* contributors, also MIT — see LICENSE.molstar.