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.0

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.0
File Size Uploaded Provenance Actions
interfacy-0.10.0.tar.gz 177.4 kB Without provenance Details for interfacy-0.10.0.tar.gz

Built distribution (wheel)

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

Total release size: 409.3 kB

Release files / interfacy-0.10.0.tar.gz

Download URL interfacy-0.10.0.tar.gz
Size 177.4 kB
Tags Source
SHA-256 checksum
How to use checksums
309b7b04c2ba2035889fb9944c462df42eb833e4e734a1720a848724f0983916
BLAKE2b-256 checksum
How to use checksums
aca199dd23aedcab579d50f9a409da1df3530537e848b5a64402a3e769a60faa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

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

Download URL interfacy-0.10.0-py3-none-any.whl
Size 231.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e2a2291b759fc9c038333065e6b9eda8501f4091c5686848360c053c3cecdbc7
BLAKE2b-256 checksum
How to use checksums
9964affe869b33601866979de746e1a7541f23df2296f6b401c135a04440ddf2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.8

Security for interfacy 0.10.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.

Release history Release notifications | RSS feed

This release

0.10.0 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