Command Line Interface Overview

CHEMSMART provides a comprehensive command-line interface for quantum chemistry calculations and molecular analysis. This guide covers the fundamental CLI structure, execution modes, and common options.

Basic Command Structure

CHEMSMART offers two main execution modes:

• Local execution: Use chemsmart run to execute tasks on the current terminal.

• HPC submission: Use chemsmart sub to submit jobs to high-performance computing clusters.

The basic command structure is:

chemsmart run/sub [OPTIONS] <CMD> [CMD_OPTIONS] <SUBCMD> [SUBCMD_OPTIONS]

Common Options for All Jobs

Server and Resource Options

Option	Type	Description
-s, --server	string	Server name from ~/.chemsmart/server/*.yaml (auto-detected if not specified)
-n, --num-cores	int	Number of cores per job
-g, --num-gpus	int	Number of GPUs per node (defaults to server configuration)
-m, --mem-gb	int	Memory allocation in gigabytes

Note

The -s option takes the server name without the .yaml extension. The -n, -g, and -m options override the server defaults.

Execution Control Options

Option	Type	Description
-S/-R, --skip-completed/--no-skip-completed	bool	Skip or rerun completed jobs (default: skip)
--fake/--no-fake	bool	Enable simulation mode with fake job runners (default: disabled)
--scratch/--no-scratch	bool or None	Force scratch on (--scratch) or off (--no-scratch). Omit both (None) to use program YAML SCRATCH when set, otherwise the job-runner class default (see Server Settings)

Note

Use -R at the end of the command to rerun a completed job.

Note

CLI (``chemsmart run`` / ``chemsmart sub``)

When both --scratch and --no-scratch are omitted, scratch mode is decided in JobRunner.from_job before the typed runner is built:

1. Explicit --scratch or --no-scratch wins.

2. Else program SCRATCH in server YAML for executable-backed runners.

3. Else the job-runner class default (True for Gaussian/ORCA/NCIPLOT; False for xTB, CREST, PyMOL, thermochemistry, etc.).

Programmatic API (direct constructor)

If you construct a runner yourself with scratch=None, server YAML is not read—you get the class SCRATCH default only. That can differ from the CLI path when YAML would override the class default.

Scratch path (when mode is on) is resolved separately from program ENVARS, then SERVER.SCRATCH_DIR, then user settings. See Scratch Behavior in Server Settings.

Note

--fake automatically selects the program-matched fake runner based on the command group:

• chemsmart run --fake gaussian ... / chemsmart sub --fake gaussian ... uses the Gaussian fake runner.

• chemsmart run --fake orca ... / chemsmart sub --fake orca ... uses the ORCA fake runner.

• chemsmart run --fake xtb ... / chemsmart sub --fake xtb ... uses the xTB fake runner.

• chemsmart run --fake crest ... / chemsmart sub --fake crest ... uses the CREST fake runner.

In these fake modes, executable-path checks for the corresponding real program are not required and the corresponding fake runner will be used without needing to specify its path.

Debugging and Logging Options

Option	Type	Description
-d, --debug/--no-debug	bool	Enable debug logging (default: disabled)
--stream/--no-stream	bool	Enable logging to stdout (default: enabled)

Submission-Specific Options

These options are only available with chemsmart sub:

Option	Type	Description
-t, --time-hours	float	Maximum job runtime in hours
-q, --queue	string	HPC queue name
-v, --verbose/--no-verbose	bool	Enable verbose output and debug logging (default: disabled)
--test/--no-test	bool	Generate scripts without submitting (default: disabled)
--print-command/--no-print-command	bool	Print the generated command (default: disabled)

Available Commands

• gaussian: Run or submit Gaussian jobs

• orca: Run or submit ORCA jobs

• xtb: Run or submit xTB jobs

• crest: Run or submit CREST conformational search jobs

• mol: Run PyMOL visualization and analysis jobs

• thermochemistry: Run thermochemistry analysis jobs

• grouper: Run structure grouping jobs

• convert: Convert molecular structure files between formats

Next Steps

For specific job types, see the detailed tutorials:

• Gaussian CLI Options

• ORCA CLI Options

• xTB CLI Options

• CREST CLI Options

• PyMOL CLI Options

• Thermochemistry Analysis

• Grouper CLI Options

• Convert CLI Options

• Molecule Input Formats

Note

CHEMSMART checks job name uniqueness. If a job with the same name is already running, submission will be blocked. Use -a (append label) or -l (label) options to create unique job names.