Skip to content

CLI Reference

keppy ships a single command, keppy, which reads a TOML configuration file and writes the corresponding KEPLER punch-card generator file.

Synopsis

keppy [OPTIONS] CONFIG OUTPUT

Arguments

Argument Description
CONFIG Path to the input .toml configuration file. Must exist.
OUTPUT Path where the generated punch-card file will be written.

Options

Option Description
--burngen PATH Path for the BURN generator file. Defaults to <output-dir>/<burngen-name> taken from the config's chemistry.burngen field.
--help Show the help message and exit.

Environment

KEPLER_DATA must be set when [chemistry] preset = "..." is used. It should point to the KEPLER auxiliary data directory that contains the composition files:

export KEPLER_DATA=~/projects/kepler/local_data

Custom compositions ([chemistry] custom = {...}) work without this variable.

Examples

Generate a punch-card deck and BURN generator from a TOML config:

keppy star.toml run/s20g
# writes: run/s20g      (punch-card generator deck)
# writes: run/solas09g  (BURN generator — name from config)

Override the BURN generator output path:

keppy star.toml run/s20g --burngen run/myburngen
# writes: run/s20g      (punch-card generator deck)
# writes: run/s20bg     (BURN generator — name from CLI)

Display usage:

keppy --help

Output

On success the command prints both output paths and exits with code 0:

Punch cards written to run/s20g
BURN generator written to run/solas09g

Any configuration validation error or unsupported file type produces a clean error message and exits with a non-zero code.

Programmatic equivalent

The CLI is a thin wrapper around two public functions:

from keppy.main import load_config, kepgen

# validate config only
config = load_config("star.toml")

# write punch cards and BURN generator
burngen_path = kepgen("star.toml", "run/s20g")

# override BURN generator path
burngen_path = kepgen("star.toml", "run/s20g", burngen_path="run/myburngen")

main

Main routines, including loaders and CLI entrypoint.

load_config 

load_config(config_path: str | Path) -> StellarConfig

Load and validate a YAML or TOML configuration file.

Source code in src/keppy/main.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def load_config(config_path: str | Path) -> StellarConfig:
    """Load and validate a YAML or TOML configuration file."""
    if isinstance(config_path, str):
        config_path = Path(config_path)
    with config_path.open("r") as f:
        if config_path.suffix == ".yaml":
            raw_config = yaml.safe_load(f)
        elif config_path.suffix == ".toml":
            raw_config = toml.load(f)
        else:
            raise click.BadParameter(
                f"unsupported file type '{config_path.suffix}' — expected .toml or .yaml",
                param_hint="CONFIG",
            )
    return StellarConfig(**raw_config)

kepgen 

kepgen(config_path: Path, output_path: Path, burngen_path: Path | None = None) -> Path

Load config, write KEPLER punch cards and the BURN generator file.

Parameters:

Name Type Description Default
config_path Path

Path to the TOML/YAML configuration file.

 required
output_path Path

Destination for the punch-card generator deck.

 required
burngen_path Path | None

Destination for the BURN generator file. When None (default) the file is placed in the same directory as output_path, using the name stored in config.chemistry.burngen.

 None

Returns:

Type Description
Path

The resolved path of the written BURN generator file.
Source code in src/keppy/main.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
def kepgen(
    config_path: Path,
    output_path: Path,
    burngen_path: Path | None = None,
) -> Path:
    """Load config, write KEPLER punch cards and the BURN generator file.

    Args:
        config_path: Path to the TOML/YAML configuration file.
        output_path: Destination for the punch-card generator deck.
        burngen_path: Destination for the BURN generator file.  When
            ``None`` (default) the file is placed in the same directory
            as *output_path*, using the name stored in
            ``config.chemistry.burngen``.

    Returns:
        The resolved path of the written BURN generator file.
    """
    config = load_config(config_path)

    PunchCardConverter().write_punch_cards(config, output_path)

    if burngen_path is None:
        burngen_path = output_path.parent / config.chemistry.burngen

    BurnGenConverter().write(config, burngen_path)
    return burngen_path