CLI

Command Line Interface documentation.

Usage

Assuming kloch and its dependencies are installed:

python -m kloch --help

The CLI can also be started from a python script:

import kloch
kloch.run_cli(["--help"])

# you can also use get_cli to have more control
# main difference is logging not being configuring
cli = kloch.get_cli(["..."])
cli.execute()

Commands

--help

import kloch
kloch.get_cli(["--help"])

usage: kloch [-h] [--debug] [--profile_roots [PROFILE_ROOTS ...]]
             {run,list,resolve,python,plugins} ...

Create an environment to launch software using pre-defined configurations.

positional arguments:
  {run,list,resolve,python,plugins}

optional arguments:
  -h, --help            show this help message and exit
  --debug               True to execute the CLI in debug mode. Usually with
                        more verbose logging.
  --profile_roots [PROFILE_ROOTS ...]
                        One or multiple filesystem path to existing directory
                        containing profile file. The paths are append to the
                        global profile roots variable.

run

import kloch
kloch.get_cli(["run", "--help"])

usage: kloch run [-h] [--debug] [--profile_roots [PROFILE_ROOTS ...]]
                 [--launcher LAUNCHER] [-- [COMMAND ...]]
                 profile_ids [profile_ids ...]

Launch an environment as described in the given profile.

Optionally specify a command to execute after the "--" argument:
   > kloch run some-profile -- echo "hello world"

positional arguments:
  profile_ids           One or more identifier or file paths of existing
                        environment profile(s). The profiles are concatenated
                        together from left to right.

optional arguments:
  -h, --help            show this help message and exit
  --debug               True to execute the CLI in debug mode. Usually with
                        more verbose logging.
  --profile_roots [PROFILE_ROOTS ...]
                        One or multiple filesystem path to existing directory
                        containing profile file. The paths are append to the
                        global profile roots variable.
  --launcher LAUNCHER   The name of a launcher to use in the provided
                        environment profile. Only required if the profile
                        define more than one launcher profile.
  -- [COMMAND ...]      Specify multiple argument to execute in the
                        environment as a single command. MUST be the last
                        argument as anything after is consumed.If the profile
                        already specify a command, the arguments are appended
                        to the existing command.

Be aware that the run command need to create files on the system. The location is determined by the cli_session_dir option. Those locations can be cleared automaticaly based on a lifetime option.

list

import kloch
kloch.get_cli(["list", "--help"])

usage: kloch list [-h] [--debug] [--profile_roots [PROFILE_ROOTS ...]]
                  [id_filter]

List all available profiles.

positional arguments:
  id_filter             A regex expression to remove profiles whose identifier
                        doesn't match. Example: "knots" will match all profile
                        starting by "knots"; ".*beta.*" will match all profile
                        containing "beta"

optional arguments:
  -h, --help            show this help message and exit
  --debug               True to execute the CLI in debug mode. Usually with
                        more verbose logging.
  --profile_roots [PROFILE_ROOTS ...]
                        One or multiple filesystem path to existing directory
                        containing profile file. The paths are append to the
                        global profile roots variable.

resolve

import kloch
kloch.get_cli(["resolve", "--help"])

usage: kloch resolve [-h] [--debug] [--profile_roots [PROFILE_ROOTS ...]]
                     [--skip-context-filtering]
                     profile_ids [profile_ids ...]

Output the given profile(s) resolved and merged to a single profile.The output
is machine parsable as a valid yaml file (unless you use the --debug flag).

positional arguments:
  profile_ids           One or more identifier or file paths of existing
                        environment profile(s). The profiles are concatenated
                        together from left to right.

optional arguments:
  -h, --help            show this help message and exit
  --debug               True to execute the CLI in debug mode. Usually with
                        more verbose logging.
  --profile_roots [PROFILE_ROOTS ...]
                        One or multiple filesystem path to existing directory
                        containing profile file. The paths are append to the
                        global profile roots variable.
  --skip-context-filtering
                        Do not remove launcher that does not match the current
                        system context. (disable context token resolving)

python

import kloch
kloch.get_cli(["python", "--help"])

usage: kloch python [-h] [--debug] [--profile_roots [PROFILE_ROOTS ...]]
                    file_path [user_args ...]

Execute the given python file with the internal python interpreter.

positional arguments:
  file_path             A filesysten path to an existing python file to
                        execute or an existing directory that MUST contains a
                        __main__.py file.
  user_args             Arbitrary nummber of command line argument passed to
                        the python file.

optional arguments:
  -h, --help            show this help message and exit
  --debug               True to execute the CLI in debug mode. Usually with
                        more verbose logging.
  --profile_roots [PROFILE_ROOTS ...]
                        One or multiple filesystem path to existing directory
                        containing profile file. The paths are append to the
                        global profile roots variable.

plugins

import kloch
kloch.get_cli(["plugins", "--help"])

usage: kloch plugins [-h] [--debug] [--profile_roots [PROFILE_ROOTS ...]]
                     [--launcher_plugins [LAUNCHER_PLUGINS ...]]

List information about the currently registred plugins.

optional arguments:
  -h, --help            show this help message and exit
  --debug               True to execute the CLI in debug mode. Usually with
                        more verbose logging.
  --profile_roots [PROFILE_ROOTS ...]
                        One or multiple filesystem path to existing directory
                        containing profile file. The paths are append to the
                        global profile roots variable.
  --launcher_plugins [LAUNCHER_PLUGINS ...]
                        Manually specify the launcher_plugins configuration
                        key instead of using the default/user-generated one.
                        This is a list of module names.