https://github.com/bahamut45/pyclif
Structured Python CLI framework with rich output, auto-configuration, and built-in project scaffolding.
https://github.com/bahamut45/pyclif
cli click framework python rich
Last synced: 29 days ago
JSON representation
Structured Python CLI framework with rich output, auto-configuration, and built-in project scaffolding.
- Host: GitHub
- URL: https://github.com/bahamut45/pyclif
- Owner: bahamut45
- License: mit
- Created: 2026-04-18T13:36:28.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-20T11:50:51.000Z (about 1 month ago)
- Last Synced: 2026-05-20T16:01:08.629Z (about 1 month ago)
- Topics: cli, click, framework, python, rich
- Language: Python
- Homepage: https://bahamut45.github.io/pyclif/
- Size: 2.19 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pyclif
[](https://codecov.io/gh/bahamut45/pyclif)
**PYthon Command Line Interface Framework** — a decorator-driven CLI framework built on
[click-extra](https://github.com/kdeldycke/click-extra) and [rich-click](https://github.com/ewels/rich-click).
pyclif 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
> **Note:** PyPI release is pending ([pypi/support#10302](https://github.com/pypi/support/issues/10302)). In the meantime, install directly from GitHub:
```bash
# pip
pip install git+https://github.com/bahamut45/pyclif.git
# uv
uv add git+https://github.com/bahamut45/pyclif.git
# poetry
poetry add git+https://github.com/bahamut45/pyclif.git
```
Requires Python 3.10+.
## Development
Requires [Task](https://taskfile.dev/#/installation).
```bash
task install # install dev + docs dependencies
pre-commit install # activate git hooks (ruff check + format on every commit)
```
```bash
task check # lint + test
task test # run test suite
task tox # run tests across Python 3.10–3.13
```
```bash
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
```python
"""CLI application using pyclif."""
from pyclif 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()
```
```bash
$ 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//`, `~/.config//`)
- **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** — `pyclif project init` generates a ready-to-use project structure
## Documentation
Full documentation at **[bahamut45.github.io/pyclif](https://bahamut45.github.io/pyclif/)**.
## License
MIT — see [LICENSE](LICENSE).