Skip to content

Command Line Options

Jump to bottom
Hiromichi Yokoyama edited this page Aug 7, 2026 · 2 revisions

Command-Line Options

MoleditPy's CLI is defined with argparse in main.py (prog="moleditpy"). This page documents every flag, the positional argument, and the environment variables that change runtime behavior.

usage: moleditpy [-h] [--version] [--safe] [--install-plugin PATH] [file]

Positional argument

file (optional)

nargs="?", default=None — "File to open on startup"

If given, MoleditPy opens this file immediately after launch, exactly as if you had used the relevant File ▸ Open/Import action. There is no restriction on extension in the parser itself — what happens depends on what the file actually is; unsupported/corrupt files fail the same way they would from the GUI's open dialog.

moleditpy molecule.mol
moleditpy project.pmeprj

Flags

-h, --help

Standard argparse help text; prints usage and exits.

--version

action="version" — prints MoleditPy {VERSION} (or MoleditPy (Linux) {VERSION} when running from the moleditpy-linux distribution — detected by checking whether "moleditpy_linux" appears in __file__) and exits immediately, before Qt is even imported. VERSION comes from moleditpy/src/moleditpy/utils/constants.py.

moleditpy --version
# MoleditPy <version>

--safe

action="store_true", default=False — "Start in safe mode: skip loading all plugins"

Passed through to MainWindow(initial_file=..., safe_mode=True). In ui/main_window_init.py, safe mode sets self.host.plugin_manager = None entirely (the PluginManager is never constructed) and logs "Safe mode: plugins disabled.". Consequences:

  • No plugin .py files under ~/.moleditpy/plugins/ are discovered, loaded, or initialize()d — including plugins that provide file openers, 3D styles, or menu actions.
  • Opening Plugin ▸ Plugin Manager... shows an informational dialog — "Plugins are disabled (safe mode)." — instead of the plugin table, since there is no PluginManager instance to browse.
  • Use this to recover from a crash caused by a broken/incompatible plugin, or to rule plugins in/out when debugging a problem.
moleditpy --safe

--install-plugin PATH

metavar="PATH" — "Install a plugin from a .py file, .zip, or folder (Headless)"

Installs a plugin without launching the GUI at all — this is a separate headless code path in main(), executed and exited before QApplication is created:

  1. Resolves PATH to an absolute path; if it doesn't exist, prints Error: Plugin path not found: {path} and exits with status 1.
  2. Computes the plugin's SHA-256 (PluginManager.compute_sha256) — for a .py file or .zip, the hash of the file itself; for a folder, a hash derived from its contents.
  3. If the path is a folder containing an __init__.py, metadata is read from that __init__.py (PLUGIN_NAME, PLUGIN_AUTHOR, PLUGIN_VERSION, PLUGIN_DESCRIPTION constants, see get_plugin_info_safe); for a bare .py file the same constants are read directly; for a .zip no metadata preview is available before install.
  4. Prints a confirmation summary (name, author, version, description, path, SHA-256) and prompts interactively: 
    Do you want to proceed with installation? (y/N):
    Only a literal y proceeds; anything else (including Enter) prints Installation aborted. and exits 0.
  5. On y, calls PluginManager.install_plugin(path), which copies the file/zip/folder into ~/.moleditpy/plugins/ (see Using Plugins for what "install" means in more detail). Prints Success: {msg} and exits 0, or Error: {msg} and exits 1.

Because this path calls input(), it is meant for interactive terminal use (e.g. scripted first-time setup), not for a fully unattended pipeline — there is no --yes/--force flag to skip the confirmation.

moleditpy --install-plugin ~/Downloads/my_plugin.py
moleditpy --install-plugin ~/Downloads/some_plugin.zip
moleditpy --install-plugin ~/Downloads/some_plugin_folder/

Unrecognized arguments (Qt passthrough)

The parser calls parser.parse_known_args(), not parse_args(), specifically so that Qt's own command-line flags (e.g. -platform offscreen, -style, -geometry) pass straight through to QApplication untouched — anything argparse doesn't recognize is forwarded as remaining and appended to sys.argv when constructing QApplication([sys.argv[0]] + remaining). This means you can combine MoleditPy's own flags with Qt's:

moleditpy --safe -platform offscreen

Environment variables

These are read directly via os.environ, not via argparse — set them in the shell before launching.

MOLEDITPY_HEADLESS

Checked in two places:

  • main.py: setup_logging() — if set (any truthy string), the GUI error-dialog handler (_ErrorDialogHandler, which pops a QMessageBox for every ERROR/CRITICAL log record) is not installed. This exists because a blocking modal dialog would hang an automated/headless run waiting for a click that will never come.
  • ui/io_logic.py: _report_load_error() — if set, load-error dialogs (QMessageBox.warning) are skipped; only the status-bar message is shown. Without it, a failed file load in a headless environment would otherwise try to pop a modal warning box.

This is how MoleditPy's own test suite runs (see the main-app CLAUDE.md): MOLEDITPY_HEADLESS=1 QT_QPA_PLATFORM=offscreen python tests/run_all_tests.py .... It is not read by main.py's CLI parsing at all — it changes behavior after launch, not startup flags.

QT_QPA_PLATFORM

Not read by MoleditPy's own code — this is a Qt/PyQt6 environment variable consumed by the Qt platform-abstraction layer itself, before any Python moleditpy code runs. Setting it to offscreen makes Qt render without an actual display/X server/compositor, which is what lets MoleditPy start at all on a headless CI runner or an SSH session with no DISPLAY. Without a real display and without this variable, Qt fails to initialize with a platform-plugin error (see Troubleshooting Common Issues).

MOLEDITPY_HEADLESS=1 QT_QPA_PLATFORM=offscreen moleditpy --safe

Settings that affect the next launch (not CLI flags, but launch-time reads)

main.py reads ~/.moleditpy/settings.json before Qt/logging is configured (_read_startup_log_settings()), specifically for two keys that are otherwise set from Settings ▸ Settings... ▸ Other:

Key Effect at startup
log_to_file (bool, default False) If true, a RotatingFileHandler is attached writing to ~/.moleditpy/moleditpy.log (1 MiB per file, 3 backups kept).
log_level_debug (bool, default False) If true, the root logger level is DEBUG instead of INFO.

These aren't CLI flags — you can't set them with --log-to-file — but they behave like startup configuration since they're read from disk before the window opens, and any parse failure (missing file, malformed JSON) silently falls back to (False, False).

See also

Clone this wiki locally