5. CLI

hoplacli is a command-line interface designed to automate job submission and execution using the hopla framework. It loads a TOML configuration file, prepares an execution environment, submits jobs (individually or in chunks), and produces a final execution report. This guide explains how to use the CLI, how to structure the TOML configuration file, and how the workflow operates.

5.1. Usage

hoplacli --config <config_file.toml> --njobs <N> [--venv]

An experiment.toml demonstration configuration file can be found in the project examples folder. If the venv option is enabled, run the command outside of a container. In this case, the image environment parameter is automatically set to None, so providing it is optional.

5.2. Workflow

  1. Parse CLI arguments using argparse.

  2. Load the TOML configuration file with tomllib: expect four mandatory sections ([project], [inputs], [environment], and [config]) and one optional ([multi]).

  3. Initialize a Executor with [environment] settings.

  4. Extract and submit commands from the [inputs] settings:

    • If a [multi] section is present, split commands into chunks and submit them as delayed submissions.

    • Otherwise, submit commands directly.

  5. Run the executor with the specified maximum number of jobs using the [config] settings.

  6. Write a textual report to report.txt inside the executor’s working directory.

5.3. TOML Configuration

The configuration file is divided into several sections.

5.3.1. [project]

name (str)

Project name.

operator (str)

Person responsible for running the analysis.

date (str)

Date of the experiment in DD/MM/YYYY format.

5.3.2. [inputs]

commands (str or list)

Commands to execute. May be a Python expression string (e.g. "sleep {k}") or a list of explicit commands. In the first case, a data.tsv file is expected for the mapping.

parameters (str)

Additional parameters passed to the container execution command (e.g. "--cleanenv").

5.3.3. [environment]

See the Executor parameters.

5.3.4. [config]

dryrun (bool)

Simulate job submission without executing.

delay_s (int)

Delay (seconds) between refresh.

verbose (bool)

Enable verbose logging.

5.3.5. [multi] (optional)

n_splits (int)

Number of chunks to split commands into.

5.4. Notes

  • The multi section is optional but required for chunked submissions.

  • The Config context manager is used internally to apply configuration settings during execution.