Skip to main content

Interfacy

Tests PyPI version Supported versions Downloads license

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.
  • --help text 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.

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

MIT License

Metadata

Release files for interfacy 0.10.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for interfacy 0.10.1
File Size Uploaded Provenance Actions
interfacy-0.10.1.tar.gz 177.2 kB Without provenance Details for interfacy-0.10.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for interfacy 0.10.1
File Interpreter ABI Platform Actions
interfacy-0.10.1-py3-none-any.whl Python 3 none any Details for interfacy-0.10.1-py3-none-any.whl

Total release size: 409.0 kB

Release files / interfacy-0.10.1.tar.gz

Download URL interfacy-0.10.1.tar.gz
Size 177.2 kB
Tags Source
SHA-256 checksum
How to use checksums
b6cb47e379bbe168a13a906019c4864aa3d5ad2a1711189b45a23381e7e05448
BLAKE2b-256 checksum
How to use checksums
14dbf1a247e593b55eaf64d18e0e218c53a57e1ccd5348cadce25cd3092dd64c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.9

Release files / interfacy-0.10.1-py3-none-any.whl

Download URL interfacy-0.10.1-py3-none-any.whl
Size 231.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2587d772f3a8ff8b30afd7fdc1fb0cf1df23e62e8579380afb5e638220778143
BLAKE2b-256 checksum
How to use checksums
cdb0330af9dc95caa220bdea763dd74f937c7d79e208b0f532152aa17f33c34e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.9

Security for interfacy 0.10.1

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.

Release history Release notifications | RSS feed

This release

0.10.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page