Command Scripts#

Command scripts work similarly to generators - passing JSON to Avogadro to render a form interface and then perform work. In principal, the scripts can be written in any programming language, although most are currently written in Python.

This guide will cover the UI aspects of scripts, with separate discussion of generators and command operation elsewhere.

Script Entry Points#

The script must handle the following command-line arguments:

  • --debug Enable extra debugging output. Used with other commands. It is not required that the script support extra debugging, but it should not crash when this option is passed.

  • --lang XX Display the user interface with a specific language or localization. It is not required that scripts support localization, but it should not crash when this option is passed.

  • --print-options Print the available UI options supported by the script, e.g. simulation parameters, etc. See below for more details.

  • --display-name Print a user-friendly name for the script. This is used in the GUI for menu entries, window titles, etc.

  • --menu-path Print the expected menu path for the script, separated by “|” characters (e.g., “Extensions|Quantum” or “Build|Insert”). The final part of the menu path will include the display-name.

Specifying UI options with –print-options#

The format of the --print-options output must be a JSON object of the following form:

  "userOptions": {
  "inputMoleculeFormat": "cjson"

The userOptions block contains a JSON object keyed with option names (e.g. “First option name”), which are used in the GUI to label simulation parameter settings. Various parameter types are supported.

If the command does not require an options dialog, the JSON can be completely empty. or include an empty userOptions block.

Returning Data#

Avogadro will pass JSON on the standard input, including the userOptions selections as well as the molecular data as requested.

After running the script, data should be printed to the standard output in JSON format, e.g.

  "cjson": {}

Returning Data in a Specific File Format#

While the default is for data to be returned as cjson objects, scripts can return data in any format recognized by Avogadro. In general, we suggest mol or sdf, xyz, pdb, cif, cml, or cjson as relatively common interchange foramts.

To indicate the format use the moleculeFormat key and then return the file data with the appropriate key:

  "moleculeFormat": "pdb",
  "pdb", "…" // PDB file as a string

Appending New Atoms and Bonds#

Sometimes a script may wish to append new atoms and bonds to the current system. As indicated above, the default action is to replace the current molecule with data returned to Avogadro (e.g., deleting or replacing atoms, etc.).

Instead, one can use the append key in the JSON returned to Avogadro:

  "moleculeFormat": "pdb",
  "append": true

Avogadro will not modify the existing molecule, but only insert new atoms and/or bonds.

Bonding New Atoms#

Avogadro can perceive bonds and bond orders in the new or appended molecule. Simply supply the bond key in the JSON returned to Avogadro, for example:

  // other data to return, e.g. in XYZ format
  "moleculeFormat": "xyz",
  "append": true,
  "bond": true

Selected Atoms#

A script can indicate atoms to select in the current molecule using the selectedAtoms key in the JSON returned to Avogadro. The selectedAtoms should be a numeric list, e.g.

    # e.g., matching a SMARTS pattern
    for match in mol.GetSubstructMatches(smarts):
        for atom in match:
    # Just indicate that we want to select matching atoms
    result = {
        'selectedAtoms': selected


Debugging may be enabled by defining AVO_PYTHON_SCRIPT_DEBUG in the process’s environment. This will cause the --debug option to be passed in all calls to scripts, and will print extra information to the qDebug() stream from within Avogadro (i.e., to the console). The script is free to handle the debug flag as the author wishes.