Metadata-Version: 2.4
Name: cli-to-py
Version: 0.1.0
Summary: Turn any CLI into a Python API, automatically.
License: MIT
License-File: LICENSE
Keywords: agent,cli,introspection,subprocess,wrapper
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Shells
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# cli-to-py

[![PyPI version](https://img.shields.io/pypi/v/cli-to-py)](https://pypi.org/project/cli-to-py/)
[![Python versions](https://img.shields.io/pypi/pyversions/cli-to-py)](https://pypi.org/project/cli-to-py/)
[![CI](https://github.com/oneryalcin/cli-to-py/actions/workflows/ci.yml/badge.svg)](https://github.com/oneryalcin/cli-to-py/actions/workflows/ci.yml)
[![Docs](https://github.com/oneryalcin/cli-to-py/actions/workflows/pages.yml/badge.svg)](https://github.com/oneryalcin/cli-to-py/actions/workflows/pages.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```bash
pip install cli-to-py
```

or:

```bash
uv add cli-to-py
```

Requires Python 3.11 or newer.

## Quick Start

```python
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:

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

Use `_` for positional arguments:

```python
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](https://oneryalcin.github.io/cli-to-py/getting-started/installation/)
- [Quick start](https://oneryalcin.github.io/cli-to-py/getting-started/quickstart/)
- [Validation](https://oneryalcin.github.io/cli-to-py/user-guide/validation/)
- [Runtime control](https://oneryalcin.github.io/cli-to-py/user-guide/runtime-control/)
- [Code generation](https://oneryalcin.github.io/cli-to-py/user-guide/code-generation/)
- [Parser limits](https://oneryalcin.github.io/cli-to-py/user-guide/parser-limits/)
- [Public API](https://oneryalcin.github.io/cli-to-py/api-reference/public-api/)

## CLI Wrapper Generation

Generate a dependency-free Python wrapper from a CLI:

```bash
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

```bash
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](https://oneryalcin.github.io/cli-to-py/development/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](https://oneryalcin.github.io/cli-to-py/user-guide/parser-limits/)
before relying on generated wrappers for unusual CLIs.
