humancli 0.1.0__py3-none-any.whl

agentcli/_wizard.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import inspect
+from enum import Enum
+from typing import Any, Literal, get_origin
+
+from . import prompt as prompt_api
+from ._types import CommandSchema, MISSING, ParameterSpec
+
+
+def wizard_schema(command: CommandSchema) -> dict[str, Any]:
+    return {
+        "command": command.command,
+        "description": command.description,
+        "parameters": [
+            serialize_parameter(parameter)
+            for parameter in command.all_parameters
+            if not parameter.hidden
+        ],
+    }
+
+
+def prompt_for_parameter(
+    parameter: ParameterSpec, *, stdin: Any = None, stdout: Any = None
+) -> Any:
+    message = parameter.prompt or parameter.description or parameter.name
+    if parameter.is_bool:
+        default = (
+            bool(parameter.default)
+            if parameter.has_default and parameter.default is not None
+            else False
+        )
+        return prompt_api.confirm(message, default=default, stdin=stdin, stdout=stdout)
+    if parameter.choices:
+        return prompt_api.select(
+            message,
+            parameter.choices,
+            default=_default(parameter.default),
+            stdin=stdin,
+            stdout=stdout,
+        )
+    if parameter.secret:
+        return prompt_api.password(
+            message, default=_default(parameter.default), stdin=stdin, stdout=stdout
+        )
+    if parameter.is_list:
+        raw = prompt_api.text(message, default="", stdin=stdin, stdout=stdout)
+        return [item.strip() for item in raw.split(",") if item.strip()]
+    return prompt_api.text(
+        message, default=_default(parameter.default), stdin=stdin, stdout=stdout
+    )
+
+
+def serialize_parameter(parameter: ParameterSpec) -> dict[str, Any]:
+    return {
+        "name": parameter.name,
+        "kind": parameter.kind,
+        "flag": None if parameter.kind == "argument" else f"--{parameter.cli_name}",
+        "required": parameter.required,
+        "description": parameter.description,
+        "choices": list(parameter.choices) if parameter.choices else None,
+        "default": None
+        if parameter.default in (MISSING, inspect.Signature.empty)
+        else parameter.default,
+        "type": parameter_type(parameter.annotation),
+    }
+
+
+def parameter_type(annotation: Any) -> str:
+    origin = get_origin(annotation)
+    if origin is Literal:
+        return "literal"
+    if origin in (list, tuple):
+        return "list"
+    if inspect.isclass(annotation) and issubclass(annotation, Enum):
+        return "enum"
+    return getattr(annotation, "__name__", str(annotation))
+
+
+def _default(value: Any) -> str | None:
+    if value in (None, MISSING, inspect.Signature.empty):
+        return None
+    return str(value)

agentcli/prompt.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import getpass
+import sys
+from typing import Any
+
+
+def text(
+    message: str,
+    *,
+    default: Any = None,
+    stdin: Any = None,
+    stdout: Any = None,
+) -> str:
+    input_stream = stdin or sys.stdin
+    output_stream = stdout or sys.stdout
+    suffix = f" [{default}]" if default not in (None, "") else ""
+    output_stream.write(f"? {message}{suffix}: ")
+    output_stream.flush()
+    value = input_stream.readline().rstrip("\n")
+    return str(default) if value == "" and default is not None else value
+
+
+def password(message: str, *, stdin: Any = None, stdout: Any = None) -> str:
+    input_stream = stdin or sys.stdin
+    output_stream = stdout or sys.stdout
+    if input_stream is sys.stdin and output_stream is sys.stdout:
+        return getpass.getpass(f"? {message}: ")
+    output_stream.write(f"? {message}: ")
+    output_stream.flush()
+    return input_stream.readline().rstrip("\n")
+
+
+def confirm(
+    message: str,
+    *,
+    default: bool = False,
+    stdin: Any = None,
+    stdout: Any = None,
+) -> bool:
+    answer = (
+        text(
+            f"{message} [{'Y/n' if default else 'y/N'}]",
+            default="y" if default else "n",
+            stdin=stdin,
+            stdout=stdout,
+        )
+        .strip()
+        .lower()
+    )
+    return answer in {"y", "yes", "true", "1"}
+
+
+def select(
+    message: str,
+    options: list[str],
+    *,
+    stdin: Any = None,
+    stdout: Any = None,
+) -> str:
+    output_stream = stdout or sys.stdout
+    output_stream.write(f"? {message}: {', '.join(options)}\n")
+    output_stream.flush()
+    choice = text("Choice", stdin=stdin, stdout=stdout)
+    if choice in options:
+        return choice
+    if choice.isdigit():
+        index = int(choice) - 1
+        if 0 <= index < len(options):
+            return options[index]
+    raise ValueError(f"Invalid selection: {choice}")

agentcli/testing.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import io
+import json
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass
+class CliResult:
+    exit_code: int
+    output: str
+    data: Any = None
+    error: Any = None
+
+
+class CliRunner:
+    def __init__(self, app: Any) -> None:
+        self.app = app
+
+    def invoke(
+        self,
+        argv: list[str],
+        *,
+        env: Mapping[str, str] | None = None,
+        is_tty: bool = False,
+        stdin: str = "",
+    ) -> CliResult:
+        stdout = io.StringIO()
+        input_stream = io.StringIO(stdin)
+        result = self.app.invoke(
+            argv=argv,
+            env=dict(env or {}),
+            is_tty=is_tty,
+            stdin=input_stream,
+            stdout=stdout,
+        )
+        output = stdout.getvalue()
+        data = result.data
+        error = result.error
+        try:
+            parsed = json.loads(output)
+        except Exception:
+            parsed = None
+        if isinstance(parsed, dict) and "ok" in parsed:
+            data = parsed.get("data")
+            error = parsed.get("error")
+        elif parsed is not None:
+            data = parsed
+        return CliResult(
+            exit_code=result.exit_code,
+            output=output,
+            data=data,
+            error=error,
+        )

humancli-0.1.0.dist-info/METADATA

@@ -0,0 +1,178 @@
+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

humancli-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+agentcli/__init__.py,sha256=HxjImv5iEFR6gnh5QyoEne6sGKbiRevyWBd40z1aufA,403
+agentcli/_agents.py,sha256=17m1RXYH2eAKioNrT9Gj8ahQjXZc7gyOzrGn_MPrlUE,3095
+agentcli/_app.py,sha256=298niScGWCQ4GHw4y7v5Jfx2oI3xnaWJ6JfMLHvtpsw,15006
+agentcli/_context.py,sha256=SqMmYndkVHLVKIDyH64Jes3GZfmlVASY3EtO18PGbRY,1161
+agentcli/_errors.py,sha256=cEmYSCs76Agp-NSqEI7UFdij9HYjMWPInEyQvYoHfFo,3564
+agentcli/_help.py,sha256=HhlN__lKUSB9T4VV_EGPxtsRnF8CrFJawRm7ttefjB0,2214
+agentcli/_output.py,sha256=8FLwRjeQjHtZ2dRUcP8WS64w6bv_Fqdg0_ioUiYPqek,8371
+agentcli/_parser.py,sha256=zuz2r0Bed0ro3rwOZPAaf4CJm2jYNjmMMHLnwAUtLhA,13822
+agentcli/_schema.py,sha256=nPzBZHB0TuML1i397OyKcMz1jEiMFhwLCqJf5dNiv9M,4708
+agentcli/_types.py,sha256=OzBDnAu8eyR6Uw3tAVV2UNKdtmUyky20eg1MYC5K7sk,3126
+agentcli/_wizard.py,sha256=WRML8rKLHfOjw50xW9j6ZPNx_LaGK-a-3ergnjolCp4,2725
+agentcli/prompt.py,sha256=AGBBSeGbjY7qiIxUMXledz_vLpnkwdb22RwBuvUY2T4,1880
+agentcli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentcli/testing.py,sha256=wm6oZeYRhbHx-Da0sIvmtKl6AB_LZgOGhrh-4LLaiw0,1303
+humancli-0.1.0.dist-info/METADATA,sha256=vR0V8-81rzlduSyUcK38lWptC9GNRs87YKyZmRwLGW8,4210
+humancli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+humancli-0.1.0.dist-info/licenses/LICENSE,sha256=71w9pR4vtroGYKlGefIRpDZmUXAWVZIyyJpljlFZOzo,1082
+humancli-0.1.0.dist-info/RECORD,,

humancli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

humancli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaser Martinez Palenzuela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.