cli-to-py 0.1.0

Turn any CLI into a Python API, automatically.

cli-to-py

Turn CLI binaries into Python APIs.

cli-to-py reads a command's help output, builds a callable Python wrapper, and lets you run subcommands with keyword arguments instead of hand-built shell strings.

Full documentation: https://oneryalcin.github.io/cli-to-py/

Install

pip install cli-to-py

or:

uv add cli-to-py

Requires Python 3.11 or newer.

Quick Start

import asyncio
from cli_to_py import convert

async def main():
    git = await convert("git")

    result = await git.status(short=True)
    print(result.stdout)

    branch = await git.branch(show_current=True).text()
    changed = await git("diff", name_only=True, _=["HEAD~1"]).lines()

    print(branch)
    print(changed)

asyncio.run(main())

Flags use Python names and are converted to CLI flags:

await git.commit(message="fix", all=True)
# runs: git commit --message fix --all

Use _ for positional arguments:

await git("diff", name_only=True, _=["HEAD~1"])
# runs: git diff --name-only HEAD~1

Why Use It

• Convert CLIs into async Python APIs with no runtime dependencies.
• Validate flags and arguments before spawning a subprocess.
• Keep subprocess output ergonomic with .text(), .lines(), and .json().
• Stream output, inherit stdio, set timeouts, pass env/cwd, and cancel work.
• Generate standalone wrapper modules for tools you want to check into a project.

Documentation

• Installation
• Quick start
• Validation
• Runtime control
• Code generation
• Parser limits
• Public API

CLI Wrapper Generation

Generate a dependency-free Python wrapper from a CLI:

cli-to-py git -o git_wrapper.py

The generated .py module and .pyi stub can be committed to another project without depending on cli-to-py at runtime.

Development

make test      # unit and integration tests
make ci        # full CI path, including package build
make docs      # strict MkDocs build
make build     # source distribution and wheel

See the release checklist for publishing steps.

Status

This project parses common --help formats pragmatically. It is useful for many CLIs, but it is not a formal parser for every help style. See parser limits before relying on generated wrappers for unusual CLIs.