{"id":27062752,"url":"https://github.com/andarius/piou","last_synced_at":"2026-02-08T22:08:59.665Z","repository":{"id":41998942,"uuid":"437034801","full_name":"Andarius/piou","owner":"Andarius","description":"A CLI tool to build beautiful rich text command-line interfaces with type validation.","archived":false,"fork":false,"pushed_at":"2025-04-17T16:16:23.000Z","size":841,"stargazers_count":315,"open_issues_count":2,"forks_count":5,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-05-15T13:08:57.267Z","etag":null,"topics":["cli","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/piou/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Andarius.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-12-10T15:58:59.000Z","updated_at":"2025-04-17T16:16:25.000Z","dependencies_parsed_at":"2023-01-30T03:01:02.182Z","dependency_job_id":"1389c800-ee79-4c8f-8d51-f9e1bbd7695a","html_url":"https://github.com/Andarius/piou","commit_stats":{"total_commits":200,"total_committers":3,"mean_commits":66.66666666666667,"dds":0.25,"last_synced_commit":"4ce38fac6f44bb42fe4585772664b677aa55fdcb"},"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andarius%2Fpiou","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andarius%2Fpiou/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andarius%2Fpiou/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andarius%2Fpiou/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Andarius","download_url":"https://codeload.github.com/Andarius/piou/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346623,"owners_count":22055808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","python"],"created_at":"2025-04-05T15:19:19.865Z","updated_at":"2026-02-03T12:15:47.322Z","avatar_url":"https://github.com/Andarius.png","language":"Python","readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/Andarius/piou/raw/master/docs/static/piou-dark.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/Andarius/piou/raw/master/docs/static/piou.jpg\"\u003e\n  \u003cimg alt=\"Piou logo\"\n    src=\"https://github.com/Andarius/piou/raw/master/docs/static/piou.jpg\"\n    width=\"250\"/\u003e\n\u003c/picture\u003e\n\n# Piou\n\n[![Python versions](https://img.shields.io/pypi/pyversions/piou)](https://pypi.python.org/pypi/piou)\n[![Latest PyPI version](https://img.shields.io/pypi/v/piou?logo=pypi)](https://pypi.python.org/pypi/piou)\n[![CI](https://github.com/Andarius/piou/actions/workflows/ci.yml/badge.svg)](https://github.com/Andarius/piou/actions/workflows/ci.yml)\n[![Latest conda-forge version](https://img.shields.io/conda/vn/conda-forge/piou?logo=conda-forge)](https://anaconda.org/conda-forge/piou)\n\nA CLI tool to build beautiful command-line interfaces with type validation.\n\n## Quick Example\n\n```python\nfrom piou import Cli, Option\n\ncli = Cli(description='A CLI tool')\n\n\n@cli.command(cmd='foo', help='Run foo command')\ndef foo_main(\n        bar: int = Option(help='Bar positional argument (required)'),\n        baz: str = Option('-b', '--baz', help='Baz keyword argument (required)'),\n        foo: str | None = Option(None, '--foo', help='Foo keyword argument'),\n):\n    \"\"\"\n    A longer description on what the function is doing.\n    \"\"\"\n    pass\n\n\nif __name__ == '__main__':\n    cli.run()\n```\n\n![example](https://github.com/Andarius/piou/raw/master/docs/static/simple-output.svg)\n\n## Installation\n\n```bash\npip install piou\n```\n\nOr with [uv](https://docs.astral.sh/uv/):\n\n```bash\nuv add piou\n```\n\nOr with [conda](https://docs.conda.io/):\n\n```bash\nconda install piou -c conda-forge\n```\n\n### Raw Formatter\n\nBy default, Piou uses [Rich](https://github.com/Textualize/rich) for beautiful terminal output. If you prefer plain text output, you can use the raw formatter:\n\n```bash\n# Force raw output via environment variable\nPIOU_FORMATTER=raw python your_cli.py --help\n```\n\n## Documentation\n\nFull documentation is available at **[andarius.github.io/piou](https://andarius.github.io/piou)**.\n\n### Features\n\n- FastAPI-like developer experience with type hints\n- Custom formatters (Rich-based by default)\n- Nested command groups / sub-commands\n- Derived options for reusable argument patterns\n- Async command support\n- Type validation and casting\n- **Interactive TUI mode** with command suggestions and history\n\n## Why Piou?\n\nI could not find a library that provided:\n\n- The same developer experience as [FastAPI](https://fastapi.tiangolo.com/)\n- Customization of the interface (to build a CLI similar to [Poetry](https://python-poetry.org/))\n- Type validation / casting\n\n[Typer](https://github.com/tiangolo/typer) is the closest alternative but lacks the possibility to format the output in a custom way using external libraries (like [Rich](https://github.com/Textualize/rich)).\n\n**Piou** provides all these possibilities and lets you define your own Formatter.\n\n## Interactive TUI Mode\n\nPiou includes an optional interactive TUI (Text User Interface) mode powered by [Textual](https://textual.textualize.io/).\nThis provides a rich terminal experience with command suggestions, history, and inline completions.\n\n### Installation\n\n```bash\npip install piou[tui]\n```\n\n### Usage\n\nEnable TUI mode by setting `tui=True` when creating your CLI:\n\n```python\nfrom piou import Cli, Option\n\ncli = Cli(description='My Interactive CLI', tui=True)\n\n@cli.command(cmd='hello', help='Say hello')\ndef hello(name: str = Option(..., help='Name to greet')):\n    print(f'Hello, {name}!')\n\nif __name__ == '__main__':\n    cli.run()\n```\n\nOr via the `--tui` flag:\n\n```bash\npython my_cli.py --tui\n```\n\nOr via the `PIOU_TUI=1` environment variable:\n\n```bash\nPIOU_TUI=1 python my_cli.py\n```\n\n### TUI Features\n\n- **Command suggestions**: Type `/` to see available commands with descriptions\n- **Subcommand navigation**: Use `:` to navigate subcommands (e.g., `/stats:uploads`)\n- **Inline completions**: See argument placeholders as you type\n- **Command history**: Navigate previous commands with up/down arrows (persisted across sessions)\n- **Rich output**: ANSI colors and formatting preserved in output\n- **Keyboard shortcuts**:\n  - `Tab` - Confirm selected suggestion\n  - `Up/Down` - Navigate suggestions or history\n  - `Ctrl+C` - Clear input (press twice to exit)\n  - `Escape` - Quit\n\n\u003cimg alt=\"TUI Demo\" src=\"https://github.com/Andarius/piou/raw/master/docs/static/tui-demo.gif\" width=\"600\"/\u003e\n\n### Advanced Example: HTTP Benchmark\n\nThe TUI mode supports mounting custom Textual widgets for rich interactive displays. This example benchmarks HTTP libraries with live progress grids:\n\n\u003cimg alt=\"HTTP Benchmark TUI\" src=\"https://github.com/Andarius/piou/raw/master/docs/static/bench_1000.gif\" width=\"700\"/\u003e\n\nSee [examples/http_bench_tui.py](examples/http_bench_tui.py) for the full implementation using `TuiContext` and custom widgets.\n\n## Development\n\n### Running Tests\n\n```bash\nuv run pytest\n```\n\n### Generating Documentation\n\n```bash\n# Build docs\nuv run --group docs mkdocs build\n\n# Serve locally\nuv run --group docs mkdocs serve\n```\n\n### Generating Screenshots and GIFs\n\nTerminal recordings are created with [VHS](https://github.com/charmbracelet/vhs). Install it first:\n\n```bash\n# Ubuntu/Debian\nsudo apt install vhs ttyd\n\n# macOS\nbrew install vhs\n\n# Or via Go\ngo install github.com/charmbracelet/vhs@latest\n```\n\nThen generate recordings from tape files:\n\n```bash\nvhs docs/static/tui-demo.tape\n```\n\nTape files are located in `docs/static/` and define scripted terminal sessions that produce GIFs.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandarius%2Fpiou","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandarius%2Fpiou","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandarius%2Fpiou/lists"}