cfui

فارسی

A small, dependency-free toolkit for Python command-line tools. It gives every tool the same look (modelled on Cloudflare's cf CLI), the same common commands, and the same behavior when an option is missing.

• PyPI package: cfuicli. Import name: cfui.
• Python 3.12 to 3.15, standard library only.

Install

uv add cfuicli          # in a project
pip install cfuicli     # anywhere else

A complete tool in a few lines

from cfui import App, Arg, ui

app = App("tool", repo="https://github.com/me/tool", pypi="tool", description="Does things.")


@app.command("greet", "Say hi", args=[Arg("--name", required=True, prompt="Your name")])
def greet(a):
    ui.success(f"hi {a.name}")


def main():
    app.main()

$ tool greet --name Sara          # runs
$ tool greet                      # on a terminal: asks "Your name"
$ tool greet </dev/null           # in a pipe or CI: --name is required. Pass --name <value> or run interactively.
$ tool help greet
$ tool version

What every tool gets

Behavior you do not have to write:

• A required option or argument is asked for on a terminal and reported as an error when the input is piped or the CI variable is set. The error exits with code 2.
• Errors are drawn as a red box on stderr and exit non-zero. raise Fail(message, hint) or sys.exit("message") both work. Ctrl-C exits 130.
• Color follows the rules: only on a TTY, NO_COLOR turns it off, FORCE_COLOR=0 turns it off, and the palette drops to 256 or 16 colors when the terminal needs it.
• Structured results go to stdout as JSON (ui.data), decoration goes to stderr.

Building commands

app = App("tool", repo=..., pypi=..., description=..., default="count", global_args=[Arg("-c", "--config")])

grp = app.group("config", "Manage settings")  # tool config show


@grp.command("show", "Show settings")
def show(a): ...


@app.command("wp", "Pass everything through", raw=True)  # a.args is the untouched argv tail
def wp(a): ...

Arg takes the usual argparse.add_argument keywords plus required=True (prompt when missing), prompt="Question", secret=True (hidden input) and group="Section" (help section). Positional arguments work the same way.

Output helpers (cfui.ui)

success, info, warning, error, hint, heading, banner, error_box, data (JSON), table, out, and the prompts ask, confirm, need, plus progress for a one-line counter.

Shared pieces (cfui.common)

The agent skill

The package carries the cf-cli-ui skill, which tells coding agents how to build and restyle CLIs this way.

cfui skill                 # print where it is
cfui skill --install       # copy it to ~/.agents/skills/cf-cli-ui

Tools built on cfui

aitc, thronetools, ollama-tool-cli, pem, linkcovery, pulsecheck, wpguard. dokploytools is written in Go and follows the same conventions with its own code.

Development

uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .

Commits follow Conventional Commits. A feat: or fix: merged into main runs the Release workflow, which bumps the version, tags it, and publishes to PyPI through a trusted publisher.

License

MIT