https://github.com/zigai/interfacy
Framework for building command-line interfaces from Python functions, classes, and class instances
https://github.com/zigai/interfacy
argparse argparse-alternative argument-parser cli cli-framework interfacy python python3 type-hints
Last synced: 12 days ago
JSON representation
Framework for building command-line interfaces from Python functions, classes, and class instances
- Host: GitHub
- URL: https://github.com/zigai/interfacy
- Owner: zigai
- License: mit
- Created: 2022-03-17T17:39:32.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2026-01-31T14:00:41.000Z (about 1 month ago)
- Last Synced: 2026-01-31T14:35:18.075Z (about 1 month ago)
- Topics: argparse, argparse-alternative, argument-parser, cli, cli-framework, interfacy, python, python3, type-hints
- Language: Python
- Homepage:
- Size: 475 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Interfacy
[](https://github.com/zigai/interfacy/actions/workflows/tests.yml)
[](https://badge.fury.io/py/interfacy)
[](https://pepy.tech/project/interfacy)
[](https://github.com/zigai/interfacy/blob/main/LICENSE)
Interfacy is a CLI framework for building command-line interfaces from Python functions, classes, and class instances using type annotations and docstrings.
## Features
- Generate CLIs from functions, class methods, or class instances.
- Nested subcommands and command groups with aliases.
- Type inference from annotations, with support for custom parsers.
- `--help` text generated from docstrings.
- Run a target callable directly from the CLI (e.g. `interfacy path.py:main`).
- Multiple help layouts and color themes.
- Optional class initializer arguments exposed as CLI options.
- Argparse-compatible backend, including a drop-in `ArgumentParser` replacement.
- Stdin piping support with configurable routing to parameters.
- Optional tab completion via `argcomplete`.
## Installation
### From PyPI
```bash
pip install interfacy
```
```bash
uv add interfacy
```
### From source
```bash
pip install git+https://github.com/zigai/interfacy.git
```
```bash
uv add "git+https://github.com/zigai/interfacy.git"
```
## Quick start
```python
from interfacy import Argparser
def greet(name: str, times: int = 1) -> None:
for _ in range(times):
print(f"Hello, {name}!")
if __name__ == "__main__":
Argparser().run(greet)
```
## Classes as flags
```python
from dataclasses import dataclass
from interfacy import Argparser
@dataclass
class Address:
"""Mailing address data for a user.
Args:
city: City name.
zip: Postal or ZIP code.
"""
city: str
zip: int
@dataclass
class User:
"""User profile information for the CLI.
Args:
name: Display name.
age: Age in years.
address: Optional mailing address details.
"""
name: str
age: int
address: Address | None = None
def greet(user: User) -> str:
if user.address is None:
return f"Hello {user.name}, age {user.age}"
return f"Hello {user.name}, age {user.age} from {user.address.city} {user.address.zip}"
if __name__ == "__main__":
Argparser(print_result=True).run(greet)
```
Help output:
```text
usage: app.py greet [--help] --user.name USER.NAME --user.age USER.AGE
[--user.address.city] [--user.address.zip]
options:
--help show this help message and exit
--user.name Display name. [type: str] (*)
--user.age Age in years. [type: int] (*)
--user.address.city City name. [type: str]
--user.address.zip Postal or ZIP code. [type: int]
```
## Class-based commands
```python
from interfacy import Argparser
class Calculator:
def add(self, a: int, b: int) -> int:
return a + b
def mul(self, a: int, b: int) -> int:
return a * b
if __name__ == "__main__":
Argparser(print_result=True).run(Calculator)
```
## Decorator-based commands
```python
from interfacy import Argparser
parser = Argparser()
@parser.command()
def greet(name: str) -> str:
return f"Hello, {name}!"
@parser.command(name="calc", aliases=["c"])
class Calculator:
def add(self, a: int, b: int) -> int:
return a + b
def mul(self, a: int, b: int) -> int:
return a * b
if __name__ == "__main__":
parser.run()
```
## CLI entrypoint
Use the CLI entrypoint to run a target callable from a module or file, or to inspect its help:
```text
usage: interfacy [--help] [--version] [--config-paths] [TARGET] ...
Interfacy is a CLI framework for building command-line interfaces from Python callables.
positional arguments:
TARGET Python file or module with a symbol (e.g. main.py:main or pkg.cli:app).
ARGS Arguments passed through to the target command.
options:
--help show this help message and exit
--version show version and exit.
--config-paths print config file search paths and exit.
Use 'interfacy TARGET --help' to display the help text for the target.
```
## License
[MIT License](https://github.com/zigai/interfacy/blob/main/LICENSE)