Face: Command-line application framework

26.0.0 · active · verified Sun Apr 05

Face is a Pythonic microframework for building command-line applications (CLI parser). It provides first-class subcommand support, a powerful middleware architecture, a separate Parser layer, built-in flagfile support, handy testing utilities, and a themeable help display. The current version is 26.0.0, released on February 13, 2026, indicating active development.

Warnings

gotcha Face is very opinionated about argument order and parsing. While it aims to be intuitive, users coming from other CLI frameworks might find its strictness around positional and keyword arguments, especially with subcommands, requires a slight adjustment. Refer to the official documentation for its specific parsing rules to avoid unexpected behavior.
Fix: Consult the 'Why is Face so picky about argument order?' section in the official documentation and review examples of subcommand definition.
gotcha The library's design emphasizes 'middleware' and a 'Parser layer' for advanced customization. For simple CLI tools, this abstraction might seem like an overhead. Ensure you understand the middleware flow when debugging complex argument parsing or command dispatch issues.
Fix: Start with basic commands and gradually introduce middleware or custom parsers as complexity demands. Review the architecture overview in the documentation when encountering unexpected parsing outcomes.

Install

pip install face Install stable version

Imports

Command
```
from face import Command
```
Used to define CLI commands and subcommands.
echo
```
from face import echo
```
A utility function for printing output to the console, similar to click's echo.

Quickstart

This quickstart defines a simple command-line application with a 'hello' command that takes an optional 'name' argument. Running this script will execute the CLI parser and dispatch to the 'hello' function.

from face import Command, echo

@Command
def hello(name: str = 'World'):
    """A simple greeting command."""
    echo(f"Hello, {name}!")

if __name__ == '__main__':
    hello.run()

view raw JSON →