cli-utils

Small route-driven command utilities with three interfaces over the same command set:

• Click CLI for direct terminal usage
• Textual TUI for local interactive use
• Browser-hosted Textual app via textual-serve
• FastAPI service for non-interactive HTTP access

The project also discovers Makefile targets at startup and exposes them as commands.

Requirements

• Python 3.14+
• uv

Setup

Install dependencies and create the virtual environment:

make sync

Or with uv directly:

uv sync

Run The CLI

Show available commands:

uv run python main.py --help

Example top-level commands include:

• greet
• salute
• interactive-demo
• longrun
• tui
• web
• api
• make-* commands generated from the local Makefile

Examples:

uv run python main.py greet --name World
uv run python main.py salute --name Alice
uv run python main.py longrun --name Alice
uv run python main.py interactive-demo
uv run python main.py make-help
uv run python main.py make-remove --pkg requests

Run The TUI

Launch the local Textual app:

uv run python main.py tui

What the TUI supports:

• Parameter form generation from registered command metadata
• Live stdout rendering while commands run
• Interactive stdin for commands marked as interactive
• Kill support for running commands
• Router and Makefile command sources
• Command palette actions for theme, quit, keys, screenshot, layout, and source switching

Useful keys:

• q: quit
• ctrl+r: toggle router vs Makefile command source
• ctrl+t: toggle stacked vs side-by-side layout
• ctrl+f: toggle output fullscreen

Run In The Browser

Launch the Textual app through textual-serve:

uv run python main.py web

Defaults:

• bind host: 0.0.0.0
• bind port: 8000
• public URL announced to the browser: http://localhost:8001

Custom example:

uv run python main.py web --host 0.0.0.0 --port 8000 --public-url http://localhost:8001

Run The FastAPI Service

Launch the HTTP API:

uv run python main.py api

Or:

uv run python main.py api --host 0.0.0.0 --port 8000

API surfaces:

• GET /health
• GET /commands
• POST /commands/{name}
• POST /commands/{name}/stream

Interactive commands are intentionally not exposed over HTTP.

Standard JSON Execution

Example:

curl -X POST "http://localhost:8000/commands/greet?name=Alice"

Typical response:

{
	"command": "greet",
	"result": "Hello, Alice!",
	"stdout": "",
	"stderr": ""
}

Streaming Execution

Streaming uses Server-Sent Events and emits these event types:

• start
• stdout
• stderr
• result
• error

Example:

curl -N -X POST "http://localhost:8000/commands/longrun/stream?name=Alice"

Example event stream:

event: start
data: {"command": "longrun"}

event: stdout
data: {"chunk": "Working on Alice...\n"}

event: result
data: {"command": "longrun", "result": null, "stdout": "...", "stderr": ""}

Built-In Commands

greet

Returns a simple greeting. Defaults to World.

uv run python main.py greet
uv run python main.py greet --name Alice

salute

Requires a name and returns a farewell.

uv run python main.py salute --name Alice

interactive-demo

Demonstrates interactive stdin and live output. Best used in the TUI or web-hosted TUI.

longrun

Prints progress every five seconds to demonstrate long-running output.

make-*

Every discovered Makefile target becomes a command such as:

• make-help
• make-sync
• make-lock
• make-update
• make-remove
• make-clean

Targets with Makefile variables are mapped to command parameters. For example, this Makefile target:

remove:
	uv remove $(PKG)

becomes:

uv run python main.py make-remove --pkg requests

In the TUI, you can switch between router commands and Makefile commands with ctrl+r.

Project Layout

.
├── api_service.py
├── cli_router.py
├── main.py
├── Makefile
└── commands/
		├── api.py
		├── greet.py
		├── interactive_demo.py
		├── long_running.py
		├── makefile_routes.py
		└── salute.py

Development Notes

• Command modules are auto-discovered from commands/.
• The FastAPI layer wraps the same router used by the CLI and TUI.
• Makefile routes are registered at import time based on the current working directory.

Common maintenance targets:

make sync
make lock
make update
make clean