Interfacy
Interfacy is a CLI framework that turns Python functions, classes, and class instances into command-line interfaces. It derives the CLI from signatures, type annotations, and docstrings instead of making you define it twice.
Features
- Generate CLIs from functions, classes, class methods, and class instances.
- Nested subcommands and manual command groups with aliases.
- Type-driven parsing from annotations, with support for custom parsers.
- Model expansion for dataclasses, Pydantic models, and plain classes.
--helptext generated from docstrings.- Highly customizable help output with multiple layouts, color themes, and configurable ordering.
- Stdin piping support with configurable routing to parameters.
- Optional tab completion via
argcomplete. - Import-path commands loaded on demand; user-facing failures with
CommandError.
Installation
From PyPI
pip install interfacy
uv add interfacy
From source
pip install git+https://github.com/zigai/interfacy.git
uv add "git+https://github.com/zigai/interfacy.git"
Quick Start
from interfacy import Interfacy
def greet(name: str, times: int = 1) -> None:
"""Print a greeting."""
print(" ".join([f"Hello, {name}!" for _ in range(times)]))
if __name__ == "__main__":
Interfacy().run(greet)
$ python app.py Ada
Hello, Ada!
$ python app.py Ada --times 2
Hello, Ada! Hello, Ada!
Agent Skill
The official AI agent skill can be installed from this repo.
npx skills add https://github.com/zigai/interfacy/tree/master/interfacy/.agents/skills/interfacy
or
uvx library-skills
Class-Based Commands
Classes become command namespaces. __init__ parameters live at the command level and public methods become subcommands.
from interfacy import Interfacy
class Calculator:
def __init__(self, precision: int = 2) -> None:
self.precision = precision
def add(self, a: float, b: float) -> float:
return round(a + b, self.precision)
def mul(self, a: float, b: float) -> float:
return round(a * b, self.precision)
if __name__ == "__main__":
Interfacy(print_result=True).run(Calculator)
$ python app.py --precision 3 add 1.2345 2.3445
3.579
Structured Parameters
Dataclasses, Pydantic models, and plain classes with typed __init__ parameters can be expanded into nested flags and reconstructed before execution.
from dataclasses import dataclass
from interfacy import Interfacy
@dataclass
class Address:
city: str
postal_code: int
@dataclass
class User:
name: str
age: int
address: Address | None = None
def greet(user: User) -> str:
return f"Hello {user.name}, age {user.age}"
if __name__ == "__main__":
Interfacy(print_result=True).run(greet)
$ python app.py --user.name Ada --user.age 32
Hello Ada, age 32
Manual Groups
Use CommandGroup when your command tree is not naturally rooted in one callable:
from interfacy import CommandGroup, Interfacy
def clone(url: str) -> str:
return f"clone:{url}"
class Releases:
def cut(self, version: str) -> str:
return f"cut:{version}"
ops = CommandGroup("ops", description="Operational commands")
ops.add_command(clone)
ops.add_command(Releases)
if __name__ == "__main__":
Interfacy(print_result=True).run(ops)
Interfacy CLI Entrypoint
Interfacy also ships a CLI that can run an existing function, class, or class instance directly from a module or Python file:
$ interfacy app.py:greet Ada
$ interfacy app.py:greet --help
$ interfacy package.cli:Calculator add 1 2
The entrypoint supports configuration via TOML, loaded from ~/.config/interfacy/config.toml or INTERFACY_CONFIG.
usage: interfacy [--help] [--version] [--config-paths] [TARGET] ...
Interfacy is a framework for building CLIs from Python callables.
positional arguments:
[TARGET] Python file or module with a function/class/instance symbol
(e.g. main.py:main, pkg.cli:App, pkg.cli:service).
... 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
Metadata
Release files for interfacy 0.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| interfacy-0.11.0.tar.gz | 183.4 kB | Without provenance | Details for interfacy-0.11.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| interfacy-0.11.0-py3-none-any.whl | Python 3 | none | any | Details for interfacy-0.11.0-py3-none-any.whl |
Total release size: 422.1 kB
Release files / interfacy-0.11.0.tar.gz
| Download URL | interfacy-0.11.0.tar.gz |
|---|---|
| Size | 183.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
32fe73b364242afa96289cc917868bca9ddc45b0c1becbd22313691c7a5094cf
|
|
BLAKE2b-256 checksum How to use checksums |
2614be420233d7021f2c81f9e41078072cbd695ad0a1c8dcfd4856db0e684b54
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.10
|
Release files / interfacy-0.11.0-py3-none-any.whl
| Download URL | interfacy-0.11.0-py3-none-any.whl |
|---|---|
| Size | 238.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fb4d1b0b3cb8cd41bb377174ee0db937015c72d7038f13b5c6dd1fc82e0dc98e
|
|
BLAKE2b-256 checksum How to use checksums |
7372848b456edbf4ec6304002e1883db5ef2b63c68b986ccd2a1ca0e2b6fa122
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.10
|
Security for interfacy 0.11.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.