Skip to content

Declaring a CLI

CliApp.from_config builds a Typer application from a [cli] table in a TOML, YAML or JSON document. You write the command functions; the table names them, and CliApp supplies the app, the standard options and exit-code handling.

The [cli] table

[cli]
name = "golden-app"
help = "Do the thing."
default_log_level = "verbose"

[[cli.commands]]
name = "sync"
target = "golden_app.commands.sync:sync"

[[cli.commands]]
name = "db"
help = "Database maintenance."
target = "golden_app.commands.db:app"
Key Meaning
name application name, also the root logger name
help the application's --help text
default_log_level default value of --log-level (default verbose)
commands[].name the name the command is invoked by
commands[].target import path, as module:attribute or a dotted path
commands[].help help text, used as written; defaults to the target's docstring, cut before its first section

A target that is a typer.Typer becomes a subcommand group; a target that is a function becomes a single command.

Where help text comes from

An explicit help is used as written. Without one, a function target's docstring is used, cut before its first Args:, Arguments:, Returns:, Raises:, Yields:, Examples: or Note: line, so those sections stay in the docstring and out of --help. A typer.Typer target's own help text is used as it is. Square brackets that are not Rich markup, such as [kiln], show literally. This applies to declared commands, not to commands registered with @app.command().

The whole of cli.py

from pathlib import Path

from rn_forge.cli import CliApp

app = CliApp.from_config(Path(__file__).parent / "cli.toml")

with golden-app = "golden_app.cli:app" under [project.scripts]. There is no main() — the generated console script is sys.exit(app()), and CliApp returns an exit code.

Validation

The table is validated when it is loaded. A value of the wrong type is rejected with the offending key named:

AppException: Invalid CliSurface: wrong value type for field "commands.target"
              - should be "str" instead of value "1" of type "int"

A missing [cli] table, a blank name, duplicate command names and a target that cannot be imported are rejected the same way.

Loading from a mapping

CliSurface.load also accepts an already-parsed mapping, for a test or an application with its own config loader. Loading and building are separate steps, so a configuration can be validated without building the app:

from rn_forge.cli import CliApp, CliSurface

surface = CliSurface.load({"name": "demo", "commands": [...]})   # validates
app = CliApp.from_surface(surface)                                # builds

Building the app in code

When a table is not enough, construct CliApp directly, or use a plain typer.Typer and wrap it in run to get the same exit-code handling.