UI — client CLI

Shared Typer client CLI factory for Klea packages.

File: klea_utils/ui/cli.py

Copyright 2026 Ankur Sinha Author: Ankur Sinha <sanjay DOT ankur AT gmail DOT com>

klea_utils.ui.cli.make_client_app(*, label: str, server_url_default: str, app_module: str, tui_app_name: str, tui_prefix: str, tui_entry: str, web_app_name: str, web_entry: str, identity_app_name: str = '', config_env_var: str | None = None, config_dir: str | Path | None = None, template_writer: Callable[[Path], Path] | None = None) → Typer[source]

Create a Typer app for a Klea user client (tui + web).

The app exposes tui / web subcommands for the Textual and NiceGUI clients respectively, each carrying its own options so --help on a subcommand lists everything it accepts. Invoked with no subcommand the app launches the Textual TUI with defaults. All package-specific values are passed as parameters, so the rag and code entry points stay thin wrappers.

Both subcommands accept --profile: the value is validated and forwarded to a spawned local server through config_env_var (see klea_utils.api.server.configure_profile()), so the config file is chosen per invocation. A profile only applies to a server the client spawns itself; reusing an already-running server or pointing at a remote host ignores it with a warning. The special profile template scaffolds a new config and exits.

Parameters:

  • label – Short package name used in help text (e.g. "RAG")

  • server_url_default – Default server URL (e.g. "http://127.0.0.1:8005")

  • app_module – Uvicorn module string for the server this client talks to (e.g. "klea_rag.api.main:app")

  • tui_app_name – Log identity for the terminal client (e.g. "klea-rag-tui")

  • tui_prefix – Prompt label prefix for the terminal client (e.g. "klea-rag")

  • tui_entry – Module:function of the app’s TUI entry (the run_*_tui launched in-process by the tui subcommand, e.g. "klea_rag.ui.tui.page:run_rag_tui")

  • web_app_name – Log identity for the web client (e.g. "klea-rag-web")

  • web_entry – Module string of the app’s NiceGUI entry point (the app.py launched by the web subcommand, e.g. "klea_rag.ui.web.app")

  • identity_app_name – Canonical identity key for the persisted user_id file, shared by the TUI and web frontends of one app so a session can be opened in either (e.g. "klea-agent"). Falls back to the frontend’s own app_name when empty.

  • config_env_var – Environment variable that carries the config file name into the spawned server (e.g. "KLEA_RAG_APP_CONFIG_FILE")

  • config_dir – Config directory searched after the working directory when validating --profile

  • template_writer – Callable that writes a config template into the working directory for --profile template

Returns:

A typer.Typer app for use as a CLI entry point