pyclifer 0.4.1

PYthon Command Line Interface Framework — decorator-driven CLI framework built on click-extra and rich-click

pyclifer

PYthon Command Line Interface Framework — a decorator-driven CLI framework built on click-extra and rich-click.

pyclifer provides four decorators (@app_group, @group, @command, @option) that give your CLI applications automatic configuration management, environment variable binding, Rich-enhanced logging, global option propagation, and standardized output formatting — with zero boilerplate.

Installation

# pip
pip install pyclifer

# uv
uv add pyclifer

# poetry
poetry add pyclifer

Requires Python 3.10+.

Development

Requires Task.

task install       # install dev + docs dependencies
pre-commit install # activate git hooks (ruff check + format on every commit)

task check         # lint + test
task test          # run test suite
task tox           # run tests across Python 3.10–3.13

task release:patch # bump patch version, commit, tag and push
task release:minor
task release:major

Run task --list to see all available tasks.

Quick Start

"""CLI application using pyclifer."""
from pyclifer import app_group, command, option, Response


@app_group(handle_response=True)
def main():
    """My CLI application."""
    pass


@main.command()
@option("--name", "-n", default="World", help="Your name")
def hello(name: str) -> Response:
    """Say hello."""
    return Response(success=True, message=f"Hello {name}!")


if __name__ == "__main__":
    main()

$ python app.py --help
 Usage: app.py [OPTIONS] COMMAND [ARGS]...

 My CLI application.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│     --version                                    Show the version and exit.  │
│     --log-file       FILE                        Path to the log file (with  │
│                                                  daily automatic rotation).  │
│                                                  [env var: MYAPP_LOG_FILE]   │
│ -v  --verbosity      LEVEL                       Either TRACE, DEBUG, INFO,  │
│                                                  WARNING, ERROR, CRITICAL.   │
│                                                  [env var: MYAPP_VERBOSITY]  │
│                                                  [default: WARNING]          │
│ -C  --config         CONFIG_PATH                 Configuration file          │
│                                                  location. Supports glob     │
│                                                  patterns and remote URLs.   │
│                                                  [env var: MYAPP_CONFIG]     │
│                                                  [default:                   │
│                                                  /etc/myapp/*.{toml,yaml,    │
│                                                  yml,json,ini,xml},          │
│                                                  ~/.config/myapp/*.{toml,    │
│                                                  yaml,yml,json,ini,xml}]     │
│ -o  --output-format  [json|yaml|table|rich|raw]  Specify the output format   │
│                                                  for the command. [env var:  │
│                                                  MYAPP_OUTPUT_FORMAT]        │
│                                                  [default: table]            │
│ -h  --help                                       Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ hello                       Say hello.                                       │
╰──────────────────────────────────────────────────────────────────────────────╯

$ python app.py hello --name Alice
Hello Alice!

$ python app.py hello --help
 Usage: app.py hello [OPTIONS]

 Say hello.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ -n  --name           TEXT                        Your name [env var:         │
│                                                  MYAPP_HELLO_NAME] [default: │
│                                                  World]                      │
│ -v  --verbosity      LEVEL                       Either TRACE, DEBUG, INFO,  │
│                                                  WARNING, ERROR, CRITICAL.   │
│                                                  [env var:                   │
│                                                  MYAPP_HELLO_VERBOSITY]      │
│                                                  [default: WARNING]          │
│ -o  --output-format  [json|yaml|table|rich|raw]  Specify the output format   │
│                                                  for the command. [env var:  │
│                                                  MYAPP_HELLO_OUTPUT_FORMAT]  │
│                                                  [default: table]            │
│ -h  --help                                       Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯

Features

• Decorator-driven — four decorators cover the full CLI surface
• Autoconfiguration — TOML/YAML/JSON config files with Linux path conventions (/etc/<app>/, ~/.config/<app>/)
• Environment variables — automatic prefix-based binding for every option
• Rich logging — colored output, custom TRACE level, secret masking, rotating log files
• Standardized output — Response dataclass with JSON/YAML/Table/Rich/Raw formatters via --output-format
• Global options — options marked is_global=True propagate automatically to all subcommands
• Project scaffolding — pyclifer project init generates a ready-to-use project structure

Documentation

Full documentation at bahamut45.github.io/pyclifer.

License

MIT — see LICENSE.