saturnin._scripts.cli

# Saturnin management console

The primary tool for interacting with Saturnin via the command line. It operates in two primary modes:

  1. Console Mode (REPL):

When invoked without any commands or arguments (i.e., just saturnin), it launches an interactive Read-Eval-Print Loop. The set of commands available in console mode might differ slightly from direct mode. This mode offers enhanced features such as:

  • Command and parameter auto-completion.

  • Interactive help (? or ?).

  • Persistent command history.

  1. Direct Mode:

When invoked with a command and its arguments (e.g., saturnin list services), it executes the specified command directly and then exits. Some commands, particularly those for one-time setup or infrequent operations (like initialize or create home), are typically available only in this mode. For technical reasons, commands pip, install package and uninstall package are available only in console mode.

—

 The CLI dynamically loads commands from registered entry points, including core commands, application-specific commands, and commands generated from installed recipes.

Globals

saturnin._scripts.cli.REPL_INTRO

Introductory Markdown text displayed when the REPL starts for the first time.

saturnin._scripts.cli.REPL_HELP

Brief help text displayed in the REPL, guiding users on basic interactions.

saturnin._scripts.cli.command_groups: list[tuple[str, str]]

Standard command groups used to organize commands in the Typer help output. Each tuple contains (command_group_name, short_help_description).

Functions

saturnin._scripts.cli.main()[source]

Main entry point for the Saturnin CLI.

This function manages the cli_loop, allowing for restarts if requested by a command or the REPL itself (e.g., after installing new packages that might add new commands).

saturnin._scripts.cli.find_group(in_app: Typer, name: str) → Typer | None[source]

Finds and returns a registered Typer sub-command group by its name.

Parameters:

  • in_app (Typer) – The parent Typer application or group to search within.

  • name (str) – The name of the sub-command group to find.

Returns:

The Typer instance of the found sub-command group, or None if no group with the given name is registered under in_app.

Return type:

Typer | None

saturnin._scripts.cli.add_command(app: Typer, name: str, cmd: Callable, *, help: str | None = None, panel: str | None = None) → None[source]

Adds a command to a Typer application, potentially creating sub-command groups.

This function allows adding commands using a dot-separated name to specify their position within a hierarchy of command groups. If intermediate groups do not exist, they are created.

Parameters:

  • app (Typer) – The root Typer application or a parent group to which the command (or its parent group) will be added.

  • name (str) – The command name. If it contains dots (e.g., “group.subgroup.command”), “group” and “subgroup” will be created as Typer groups if they don’t already exist.

  • cmd (Callable) – The function to be registered as the Typer command.

  • help (str | None) – Optional help text for the command. This will be displayed in the --help output.

  • panel (str | None) – Optional name of the Rich help panel under which this command should be listed in the Typer help output.

Return type:

None

saturnin._scripts.cli.cli_loop(*, restart: bool) → bool[source]

Sets up and runs the Typer CLI application, handling REPL invocation.

This function initializes the main Typer application, registers command groups, and dynamically loads commands from entry points and recipes. If the CLI is invoked without a subcommand, it launches the REPL.

Parameters:

restart (bool) – If True, indicates that the CLI is being restarted (e.g., after a command requested a restart). This can be used to modify initial REPL messages.

Returns:

True if the REPL (or a command executed within it) requested a restart of the CLI loop, False otherwise for a normal termination.

Return type:

bool