Command Usage Conventions

Command help pages have Usage lines that show syntax and options using various fonts and symbols:

• keywords to be taken literally are not italicized
• parameters that should be replaced with an appropriate value (such as a number or word) are italicized
• atom-spec, model-spec, spec, and similar terms indicate target specification strings, which generally mean “all” when left blank
• optional keywords and parameters are referred to as options or are enclosed in square brackets: [ ]
• mutually exclusive choices are separated by a vertical bar: |
• mutually exclusive choices of a required item are grouped with parentheses: ( )

These brackets, vertical bars, and parentheses in Usage lines are merely symbolic and should not be included in the typed command.

In addition to the detailed help, the usage command can be used to show a brief description of any command in the Log. See also: help, color specification, target specification, sequence specification, specifying points and vectors, ChimeraX command files

The display is updated as needed when a user presses return after entering a command, or when a wait command is executed within a script. As mentioned below, multiple commands can be combined into a single line with semicolon separators.

Truncation
Command names and keywords can be truncated to unique strings, with rare exceptions specifically noted. However, the entire command name may be needed as the “unique string” if the name of another command (including those in bundles installed from the ChimeraX Toolshed) starts with the same string. If a truncation matches multiple keywords but one is a simpler compound word, the simpler one is used; otherwise, an ambiguity error is raised.

Boolean (truth) values can also be truncated, with synonyms for true: True, 1, and synonyms for false: False, 0.

Capitalization
Command names should be entered as lowercase letters, whereas keywords can be completely lowercase or capitalized as shown in the documentation, typically camelCase for compound words.

Quotation Marks
Pathnames and string values should be enclosed in quotation marks if they contain spaces or characters with special meanings in the command line (#, :, and others). In unquoted pathnames and strings, * (wild card), ? (single-character wild card), and square brackets [ ] enclosing alternative single-character matches can be used, as described here for atom and residue names.

Space-containing target specifications and multiword color names do not need to be enclosed in quotation marks, except that a palette argument containing a multiword color name does need to be enclosed in quotation marks.

Input from File Browser
Substituting the word browse for a file or directory pathname brings up a file browser window for specifying the name and location interactively. Alternatively, dragging and dropping the icon for a file or directory into the Command Line Interface substitutes the corresponding pathname text.

[back to top: Command Usage Conventions]

ChimeraX Command Files

ChimeraX command files (scripts) are plain text files containing the same commands as could be entered into the Command Line Interface. The filename suffix .cxc is used for this type of file. Opening a ChimeraX command file in ChimeraX executes the commands (and echoes them to the Log unless the script was opened with log false). To process multiple data files iteratively with the same command file, see the open command option forEachFile.

For command file examples, see the ChimeraX feature highlights and example images. See also: Startup preferences, making movies

• Comments: Lines with # as the first nonspace character and in-line text with # as the first nonspace character following a semicolon (;) are interpreted as comments and ignored. Blank lines are also allowed.
  
  
• Command truncation: As discussed above, although command names can be truncated to unique strings, using the full command names is more robust against possible name conflicts with other commands that might be added later.
  
  
• Combining commands: Multiple commands can be combined into a single line with semicolon separators. This is done to make multi-frame actions start simultaneously and/or to suppress the display of intermediate states, usually within a script. Semicolon separators are also needed to define composite (multi-command) actions with alias or perframe, whether interactively or in a script. See also: volume calculateSurfaces
  
  
• Order of execution: Even when multiple actions occur within a single image update frame, their order is important, and one command may need to precede or follow another to give the desired result. In general, the order of execution is the order in which the commands are given. For example, if a script plays a molecular dynamics trajectory and at each frame shows a molecular surface and colors it by electrostatic potential, the coloring should come after the surface calculation.
  
  
• Concurrent vs. serial execution: The wait command is used to enforce completion of a multi-frame action before initiation of the next command in a script; omitting it or waiting for fewer frames allows successive actions to overlap or run concurrently.
  
  
• Working directory: Opening a command file changes the current directory to the directory containing that file. After execution of the file finishes, the current directory is changed back to what it was previously. See also: cd