Metadata-Version: 2.4
Name: humancli
Version: 0.1.0
Summary: Python CLIs for agents and humans
Project-URL: Repository, https://github.com/elyase/agentcli
Project-URL: Issues, https://github.com/elyase/agentcli/issues
Author-email: Yaser Martinez Palenzuela <yaser.martinez@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,cli,command-line,llm
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: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: docstring-parser>=0.16
Provides-Extra: all
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: pydantic>=2.0; extra == 'all'
Requires-Dist: pyyaml>=6.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: pydantic
Requires-Dist: pydantic>=2.0; extra == 'pydantic'
Provides-Extra: rich
Requires-Dist: rich>=13.0; extra == 'rich'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == 'yaml'
Description-Content-Type: text/markdown

# agentcli

Python CLIs for agents and humans.

agentcli builds command-line interfaces that produce structured, parseable output for AI agents while remaining human-friendly. Type hints are the schema — a function signature IS the CLI specification.

## Install

```sh
pip install humancli
```

The package installs as `humancli` on PyPI but you import it as `agentcli`:

```python
from agentcli import App
```

## Quick start

### Single function

```python
from agentcli import run

def greet(name: str):
    """Greet someone."""
    return {"message": f"hello {name}"}

run(greet)
```

```sh
$ greet world
message: hello world

$ greet world --json
{"ok": true, "data": {"message": "hello world"}}

$ greet --llms
# greet
| Command | Description |
|---------|-------------|
| `greet <name>` | Greet someone |
```

### Multi-command app

```python
from agentcli import App

app = App("my-cli", version="1.0.0")

@app.command
def status():
    """Show status."""
    return {"clean": True, "branch": "main"}

@app.command
def install(package: str, *, save_dev: bool = False):
    """Install a package."""
    return {"added": 1, "packages": 451}

app()
```

Parameters before `*` are positional arguments. Parameters after `*` are named options/flags. This is just Python's own syntax.

### Parameter metadata

```python
from typing import Annotated, Literal
from agentcli import App, Param

app = App("deploy-cli")

@app.command
def deploy(
    env: Annotated[Literal["staging", "prod"], Param(help="Target environment")],
    *,
    token: Annotated[str, Param(env="DEPLOY_TOKEN", secret=True)] = "",
):
    """Deploy to an environment."""
    return {"url": f"https://{env}.example.com"}

app()
```

### Sub-apps

```python
app = App("gh")
pr = App("pr")

@pr.command
def list_(*, state: Literal["open", "closed"] = "open"):
    """List pull requests."""
    return {"prs": [], "state": state}

app.mount(pr)
app()

# $ gh pr list --state closed
```

### Default commands

```python
app = App("fetch")

@app.default
def fetch_cases(*, limit: int = 20):
    """Fetch cases."""
    return {"fetched": limit}

# Runs when no sub-command is given:
# $ fetch --limit 5
```

## Agent discovery

Every agentcli app gets built-in flags for agent consumption:

- `--llms` — markdown command index
- `--llms-full` — full JSON schema of all commands
- `--json` / `--yaml` / `--jsonl` — structured output formats
- `--mcp` — start as an MCP server (requires `agentcli[mcp]`)

## Optional extras

```sh
pip install humancli[rich]      # rich terminal formatting
pip install humancli[pydantic]  # pydantic model support
pip install humancli[yaml]      # yaml output format
pip install humancli[mcp]       # MCP server mode
pip install humancli[all]       # everything
```

## License

MIT
