climplicit

Derive CLI tools implicitly from Python class definitions. Decorate a class with @tool, mark methods with @command, and the CLI is derived from type annotations automatically.

Defining a tool

from climplicit import command, tool
from pathlib import Path

@tool("file-processor", desc="Process and inspect text files")
class FileProcessor:
    @command
    def convert(
        self,
        input_file: Path,
        output_file: Path,
        encoding: str = "utf-8",
        uppercase: bool = False,
        max_lines: int | None = None,
    ):
        """Convert a text file, optionally transforming its content."""
        ...

    @command
    def inspect(self, input_file: Path, verbose: bool = False):
        """Print metadata and a preview of a text file."""
        ...

$ file-processor --help
usage: file-processor <command> [options]

│ Process and inspect text files

options:
  -h, --help                  show this help message and exit

commands:
  convert                     Convert a text file, optionally transforming its content.
  inspect                     Print metadata and a preview of a text file.

$ file-processor convert --help
usage: file-processor convert input-file output-file [options]

│ Convert a text file, optionally transforming its content.

positional arguments:
  input-file
  output-file

options:
  -h, --help                  show this help message and exit
  --encoding STR              ['utf-8']
  --uppercase
  --max-lines INT             [None]

How annotations map to CLI behaviour

• snake_case names become --kebab-case flags automatically
• Parameters without type annotations have their type inferred from the default value
• *args and **kwargs are silently ignored
• Both regular methods and @classmethod methods are supported

Single-command shortcut

If a tool defines only one @command, the subcommand layer is skipped entirely:

@tool("greet")
class Greeter:
    @command
    def hello(self, name: str, loud: bool = False):
        """Greet someone."""
        ...

$ greet World --loud   # no "hello" subcommand needed

Installing tools into a venv

climplicit writes scripts directly into the active venv's bin/ on demand — no hardcoded entry points, no reinstall loop.

climplicit-generate <source-root>

<source-root> is the directory containing your packages (equivalent to where in find_namespace_packages). Sibling directories at the same level are also added to sys.path, so shared packages like util/ resolve correctly.

Re-run whenever you add a new @tool class.

Packaging for distribution

To print the [project.scripts] block for all @tool classes in a folder:

climplicit-generate <source-root> --print-scripts

Paste the output into your pyproject.toml and pip will create the scripts on install.

Before climplicit is on PyPI

Until climplicit is published, pip install -e . won't find it in the isolated build environment. Workaround:

pip install -e /path/to/climplicit       # install climplicit into your venv first
pip install --no-build-isolation -e .    # reuse the active venv for building

Or use the helper script:

/path/to/climplicit/scripts/dev-install.sh /path/to/your/project