CLI¶
CliApp is a typer.Typer subclass whose root callback wires the standard
options into AppLogger and the console singleton from rn-forge-commons:
from rn_forge.cli import CliApp
app = CliApp("my-tool", help="Do the thing.")
@app.command()
def run() -> None:
print("running")
and in pyproject.toml:
[project.scripts]
my-tool = "my_tool.cli:app"
That is the whole wiring. A generated console script is sys.exit(app()), and
CliApp.__call__ returns a mapped exit code, so the repository writes no
main() and no exit-code handling.
my-tool gets four options for free: --log-level/--log-file (feeding
AppLogger.initialize) and --quiet/--json (feeding console, whose modes
are described in the console guide in rn-forge-commons).
Because CliApp is a typer.Typer, every Typer facility works unchanged —
@app.command(), app.add_typer(...), and the constructor's full keyword set
via **typer_kwargs.
Exit codes¶
| Code | Meaning |
|---|---|
0 |
ExitCode.OK — the command succeeded |
1 |
ExitCode.FAILURE — an AppException, or an unexpected error |
2 |
ExitCode.USAGE — a bad command line (Click's own convention) |
130 |
ExitCode.INTERRUPTED — Ctrl-C (128 + SIGINT) |
An AppException is a diagnosed failure: it prints as one line, with its
traceback logged at debug level. Anything else is a defect, and its traceback is
logged in full. A command that raises typer.Exit(3) exits 3 — an explicit
code is honoured as given.
To apply the same mapping to a hand-built typer.Typer, call the free function:
from rn_forge.cli import run
def main() -> int:
return run(my_plain_typer_app)
Reading the resolved flags in a command¶
Typer allows --quiet/--json both before and after the subcommand name
(my-tool --quiet run and my-tool run --quiet). The root callback only sees
the former, so a command that declares its own copies merges them with
CliOptions.from_context:
import typer
from rn_forge.cli import CliOptions, JsonOption, QuietOption
@app.command()
def run(ctx: typer.Context, quiet: QuietOption = False, json_output: JsonOption = False) -> None:
opts = CliOptions.from_context(ctx, quiet=quiet, json_output=json_output).apply(ctx)
if opts.json_output:
...
The two steps are separate because they do different things. from_context is
pure: it reads what the root callback resolved and merges the command-level
flags over it. apply is not: it rejects the mutually-exclusive
--quiet --json pair, switches console into the requested mode, and writes
the merged result back onto the root context. A caller that only wants to know
the options — a test, or a command driving its own AppConsole — stops after
from_context.
dry_run and yes ride along on the same object, so a command that writes
anything reads both off the context instead of threading them through.
CLI overrides¶
SetOption and parse_overrides are the two halves of
--set dotted.key=value:
from rn_forge.cli import SetOption, parse_overrides
@app.command()
def deploy(overrides: SetOption = None) -> None:
values = parse_overrides(overrides)
# --set database.port=5432 --set 'feature_flags=["a", "b"]'
# {"database": {"port": 5432}, "feature_flags": ["a", "b"]}
Each value is parsed first as JSON, then as a TOML scalar, falling back to the
raw string. The nested mapping is exactly the shape DictUtils.merge_layers in
rn-forge-commons takes as its highest-precedence layer, so an override lands
in a layered configuration with its provenance tracked.
Typer's native bool handling (--flag/--no-flag) covers plain boolean
options directly — no wrapper needed.