openapi-cli-gen 0.0.1__py3-none-any.whl

openapi_cli_gen/__init__.py

@@ -0,0 +1,7 @@
+"""Generate typed Python CLIs from OpenAPI specs with Pydantic model flattening."""
+
+__version__ = "0.0.1"
+
+from openapi_cli_gen.engine.builder import build_cli, build_command_group
+
+__all__ = ["build_cli", "build_command_group", "__version__"]

openapi_cli_gen/__main__.py

@@ -0,0 +1,3 @@
+from openapi_cli_gen.cli import main
+
+main()

openapi_cli_gen/cli.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import typer
+
+from openapi_cli_gen.spec.loader import load_spec
+from openapi_cli_gen.spec.parser import parse_spec, extract_security_schemes
+
+app = typer.Typer(
+    name="openapi-cli-gen",
+    help="Generate typed Python CLIs from OpenAPI specs.",
+)
+
+
+@app.command()
+def generate(
+    spec: str = typer.Option(..., help="Path to OpenAPI spec file"),
+    name: str = typer.Option(..., help="CLI/package name"),
+    output: str = typer.Option(None, help="Output directory (default: ./<name>)"),
+):
+    """Generate a CLI package from an OpenAPI spec."""
+    from openapi_cli_gen.codegen.generator import generate_package
+
+    output_dir = output or f"./{name}"
+    result = generate_package(spec=spec, name=name, output_dir=output_dir)
+    typer.echo(f"Generated CLI package at: {result}")
+
+
+@app.command()
+def run(
+    spec: str = typer.Option(..., help="Path to OpenAPI spec file"),
+    args: list[str] = typer.Argument(None, help="Command args: <group> <command> [--flags]"),
+):
+    """Run a CLI directly from an OpenAPI spec (no code generation)."""
+    from openapi_cli_gen import build_cli
+
+    cli = build_cli(spec=spec, name="cli")
+    cli(args or [])
+
+
+@app.command()
+def inspect(
+    spec: str = typer.Option(..., help="Path to OpenAPI spec file"),
+):
+    """Inspect an OpenAPI spec — show what would be generated."""
+    resolved = load_spec(spec)
+    endpoints = parse_spec(resolved)
+    schemes = extract_security_schemes(resolved)
+
+    groups: dict[str, list] = {}
+    for ep in endpoints:
+        groups.setdefault(ep.tag, []).append(ep)
+
+    title = resolved.get("info", {}).get("title", "Unknown")
+    version = resolved.get("info", {}).get("version", "?")
+
+    typer.echo(f"API: {title} v{version}")
+    typer.echo(f"Endpoints: {len(endpoints)}")
+    typer.echo(f"Groups: {len(groups)}")
+    typer.echo(f"Auth schemes: {len(schemes)}")
+    typer.echo()
+
+    for group_name, eps in sorted(groups.items()):
+        typer.echo(f"  {group_name}:")
+        for ep in eps:
+            body = " [body]" if ep.body_schema else ""
+            typer.echo(f"    {ep.method.upper():7} {ep.path:30} {ep.summary}{body}")
+
+
+def main():
+    app()

openapi_cli_gen/codegen/generator.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from jinja2 import Environment, PackageLoader
+
+import openapi_cli_gen
+
+
+def generate_package(
+    spec: str,
+    name: str,
+    output_dir: str,
+) -> Path:
+    """Generate a CLI package from an OpenAPI spec."""
+    output = Path(output_dir)
+    pkg_dir = output / "src" / name
+
+    pkg_dir.mkdir(parents=True, exist_ok=True)
+
+    env = Environment(
+        loader=PackageLoader("openapi_cli_gen", "codegen/templates"),
+        keep_trailing_newline=True,
+    )
+
+    context = {
+        "name": name,
+        "openapi_cli_gen_version": openapi_cli_gen.__version__,
+    }
+
+    for template_name, output_path in [
+        ("cli.py.jinja2", pkg_dir / "cli.py"),
+        ("__init__.py.jinja2", pkg_dir / "__init__.py"),
+        ("pyproject.toml.jinja2", output / "pyproject.toml"),
+    ]:
+        template = env.get_template(template_name)
+        output_path.write_text(template.render(**context))
+
+    shutil.copy2(spec, pkg_dir / "spec.yaml")
+
+    return output

openapi_cli_gen/codegen/templates/__init__.py.jinja2

@@ -0,0 +1 @@
+"""{{ name }} CLI — generated by openapi-cli-gen."""

openapi_cli_gen/codegen/templates/cli.py.jinja2

@@ -0,0 +1,15 @@
+from pathlib import Path
+from openapi_cli_gen import build_cli
+
+app = build_cli(
+    spec=Path(__file__).parent / "spec.yaml",
+    name="{{ name }}",
+)
+
+
+def main():
+    app()
+
+
+if __name__ == "__main__":
+    main()

openapi_cli_gen/codegen/templates/pyproject.toml.jinja2

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{ name }}"
+version = "0.1.0"
+description = "CLI for {{ name }} API"
+requires-python = ">=3.10"
+dependencies = [
+    "openapi-cli-gen>={{ openapi_cli_gen_version }}",
+]
+
+[project.scripts]
+{{ name }} = "{{ name }}.cli:main"

openapi_cli_gen/engine/auth.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import os
+
+from openapi_cli_gen.spec.parser import SecuritySchemeInfo
+
+
+class AuthState:
+    """Holds resolved auth credentials and produces HTTP headers."""
+
+    def __init__(self):
+        self._headers: dict[str, str] = {}
+        self._token_override: str | None = None
+        self._scheme_type: str | None = None
+        self._header_name: str | None = None
+
+    def set_token(self, token: str) -> None:
+        self._token_override = token
+
+    def get_headers(self) -> dict[str, str]:
+        if self._token_override:
+            if self._scheme_type == "bearer":
+                return {"Authorization": f"Bearer {self._token_override}"}
+            elif self._scheme_type == "apiKey" and self._header_name:
+                return {self._header_name: self._token_override}
+        return dict(self._headers)
+
+
+def build_auth_config(
+    cli_name: str,
+    schemes: list[SecuritySchemeInfo],
+) -> AuthState:
+    """Build auth state from security schemes + environment variables."""
+    prefix = cli_name.upper().replace("-", "_")
+    state = AuthState()
+
+    for scheme in schemes:
+        if scheme.type == "http" and scheme.scheme == "bearer":
+            state._scheme_type = "bearer"
+            token = os.environ.get(f"{prefix}_TOKEN")
+            if token:
+                state._headers = {"Authorization": f"Bearer {token}"}
+            break
+        elif scheme.type == "apiKey" and scheme.location == "header":
+            state._scheme_type = "apiKey"
+            state._header_name = scheme.header_name or "X-API-Key"
+            api_key = os.environ.get(f"{prefix}_API_KEY")
+            if api_key:
+                state._headers = {state._header_name: api_key}
+            break
+
+    return state

openapi_cli_gen/engine/builder.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Callable
+
+import httpx
+
+from openapi_cli_gen.spec.loader import load_spec
+from openapi_cli_gen.spec.parser import parse_spec, extract_security_schemes
+from openapi_cli_gen.engine.registry import build_registry, CommandInfo
+from openapi_cli_gen.engine.dispatch import dispatch
+from openapi_cli_gen.engine.auth import build_auth_config
+from openapi_cli_gen.output.formatter import format_output
+
+
+def build_cli(
+    spec: str | Path,
+    name: str = "cli",
+    base_url: str | None = None,
+) -> Callable:
+    """Build a CLI application from an OpenAPI spec.
+
+    Args:
+        spec: Path to OpenAPI spec file.
+        name: CLI name (used for help text and env var prefix).
+        base_url: Override the API base URL. If None, uses first server from spec.
+
+    Returns:
+        A callable that accepts a list of args (or uses sys.argv[1:]).
+    """
+    spec_path = str(spec)
+    resolved = load_spec(spec_path)
+    endpoints = parse_spec(resolved)
+    security_schemes = extract_security_schemes(resolved)
+    registry = build_registry(endpoints)
+    auth_state = build_auth_config(name, security_schemes)
+
+    if base_url is None:
+        servers = resolved.get("servers", [])
+        base_url = servers[0]["url"] if servers else "http://localhost:8000"
+
+    # Attach cli_cmd to each command model
+    for group_cmds in registry.values():
+        for cmd_info in group_cmds.values():
+            _attach_cli_cmd(cmd_info, base_url, auth_state)
+
+    def app(args: list[str] | None = None):
+        if args is None:
+            args = sys.argv[1:]
+        dispatch(registry, args, name=name)
+
+    return app
+
+
+def _attach_cli_cmd(cmd_info: CommandInfo, base_url: str, auth_state) -> None:
+    """Attach a cli_cmd method to the command model that makes the HTTP call."""
+    ep = cmd_info.endpoint
+
+    def cli_cmd(self):
+        data = self.model_dump(exclude_none=True)
+
+        # Separate path params from body/query
+        path_names = {p.name for p in ep.path_params}
+        query_names = {p.name for p in ep.query_params}
+
+        path_params = {k: v for k, v in data.items() if k in path_names}
+        query_params = {k: v for k, v in data.items() if k in query_names}
+        body = {k: v for k, v in data.items() if k not in path_names and k not in query_names}
+
+        # Build URL with path params
+        path = ep.path
+        for k, v in path_params.items():
+            path = path.replace(f"{{{k}}}", str(v))
+        url = f"{base_url}{path}"
+
+        headers = auth_state.get_headers()
+
+        with httpx.Client() as client:
+            if ep.method in ("post", "put", "patch"):
+                resp = client.request(ep.method.upper(), url, json=body or None, params=query_params, headers=headers)
+            else:
+                resp = client.request(ep.method.upper(), url, params=query_params, headers=headers)
+
+        if resp.status_code >= 400:
+            print(f"Error: {resp.status_code}")
+            try:
+                print(format_output(resp.json(), "json"))
+            except Exception:
+                print(resp.text)
+            raise SystemExit(1)
+
+        try:
+            result = resp.json()
+        except Exception:
+            result = resp.text
+
+        output = format_output(result, "json")
+        if output is not None:
+            print(output)
+
+    cmd_info.model.cli_cmd = cli_cmd
+
+
+def build_command_group(
+    spec: str | Path,
+    name: str = "api",
+    base_url: str | None = None,
+) -> dict[str, dict[str, CommandInfo]]:
+    """Build command group from spec. Returns the registry for programmatic use."""
+    spec_path = str(spec)
+    resolved = load_spec(spec_path)
+    endpoints = parse_spec(resolved)
+    security_schemes = extract_security_schemes(resolved)
+    registry = build_registry(endpoints)
+    auth_state = build_auth_config(name, security_schemes)
+
+    if base_url is None:
+        servers = resolved.get("servers", [])
+        base_url = servers[0]["url"] if servers else "http://localhost:8000"
+
+    for group_cmds in registry.values():
+        for cmd_info in group_cmds.values():
+            _attach_cli_cmd(cmd_info, base_url, auth_state)
+
+    return registry

openapi_cli_gen/engine/dispatch.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import sys
+
+from pydantic_settings import CliApp
+
+from openapi_cli_gen.engine.registry import CommandInfo
+
+
+def dispatch(
+    registry: dict[str, dict[str, CommandInfo]],
+    args: list[str],
+    name: str = "cli",
+) -> None:
+    """Dispatch CLI args to the right command via manual group+command routing."""
+    if not args or args[0] in ("-h", "--help"):
+        _print_root_help(registry, name)
+        return
+
+    group = args[0]
+    if group not in registry:
+        print(f"Error: unknown group '{group}'. Available: {', '.join(sorted(registry.keys()))}")
+        sys.exit(1)
+
+    remaining = args[1:]
+    if not remaining or remaining[0] in ("-h", "--help"):
+        _print_group_help(registry[group], group, name)
+        return
+
+    command = remaining[0]
+    if command not in registry[group]:
+        print(f"Error: unknown command '{group} {command}'. Available: {', '.join(sorted(registry[group].keys()))}")
+        sys.exit(1)
+
+    cmd_info = registry[group][command]
+    flag_args = remaining[1:]
+
+    CliApp.run(cmd_info.model, cli_args=flag_args)
+
+
+def _print_root_help(
+    registry: dict[str, dict[str, CommandInfo]],
+    name: str,
+) -> None:
+    print(f"Usage: {name} <group> <command> [options]\n")
+    print("Groups:")
+    for group, commands in sorted(registry.items()):
+        cmds = ", ".join(sorted(commands.keys()))
+        print(f"  {group:20} {cmds}")
+    print(f"\nUse '{name} <group> --help' for group help")
+
+
+def _print_group_help(
+    commands: dict[str, CommandInfo],
+    group: str,
+    name: str,
+) -> None:
+    print(f"Usage: {name} {group} <command> [options]\n")
+    print("Commands:")
+    for cmd_name, cmd_info in sorted(commands.items()):
+        doc = cmd_info.endpoint.summary or cmd_info.endpoint.operation_id
+        print(f"  {cmd_name:20} {doc}")

openapi_cli_gen/engine/models.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, create_model
+from pydantic.fields import FieldInfo
+
+TYPE_MAP: dict[str, type] = {
+    "string": str,
+    "integer": int,
+    "number": float,
+    "boolean": bool,
+}
+
+
+def schema_to_model(
+    name: str,
+    schema: dict,
+    doc: str = "",
+    _model_cache: dict[str, type[BaseModel]] | None = None,
+) -> type[BaseModel]:
+    """Convert a JSON Schema object to a dynamic Pydantic model.
+
+    Handles: primitives, nested objects, arrays, enums, dicts, nullable.
+    Nested objects become nested BaseModel subclasses (works with CliApp dot-notation).
+    """
+    if _model_cache is None:
+        _model_cache = {}
+
+    if name in _model_cache:
+        return _model_cache[name]
+
+    fields: dict[str, Any] = {}
+    required_fields = set(schema.get("required", []))
+    properties = schema.get("properties", {})
+
+    for field_name, prop in properties.items():
+        py_type, field_info = _property_to_field(
+            field_name, prop, field_name in required_fields, name, _model_cache
+        )
+        fields[field_name] = (py_type, field_info)
+
+    model = create_model(name, __doc__=doc or name, **fields)
+    _model_cache[name] = model
+    return model
+
+
+def _property_to_field(
+    field_name: str,
+    prop: dict,
+    is_required: bool,
+    parent_name: str,
+    model_cache: dict[str, type[BaseModel]],
+) -> tuple[type, FieldInfo]:
+    """Convert a single JSON Schema property to a (type, FieldInfo) tuple."""
+    prop_type = prop.get("type", "string")
+
+    # Handle nullable (3.1 style: type as list)
+    nullable = False
+    if isinstance(prop_type, list):
+        non_null = [t for t in prop_type if t != "null"]
+        nullable = len(non_null) < len(prop_type)
+        prop_type = non_null[0] if non_null else "string"
+
+    # Handle nested object with properties → nested BaseModel
+    if prop_type == "object" and "properties" in prop:
+        nested_name = f"{parent_name}_{field_name.title()}"
+        nested_model = schema_to_model(nested_name, prop, _model_cache=model_cache)
+        py_type = nested_model | None
+        return py_type, FieldInfo(default=None)
+
+    # Handle dict (additionalProperties without properties)
+    if prop_type == "object" and "additionalProperties" in prop:
+        value_type = TYPE_MAP.get(
+            prop.get("additionalProperties", {}).get("type", "string"), str
+        )
+        py_type = dict[str, value_type] | None
+        return py_type, FieldInfo(default=None)
+
+    # Handle array
+    if prop_type == "array":
+        items = prop.get("items", {})
+        item_type_str = items.get("type", "string")
+        if item_type_str == "object" and "properties" in items:
+            item_model = schema_to_model(
+                f"{parent_name}_{field_name.title()}Item", items, _model_cache=model_cache
+            )
+            py_type = list[item_model]
+        else:
+            item_type = TYPE_MAP.get(item_type_str, str)
+            py_type = list[item_type]
+
+        if not is_required:
+            py_type = py_type | None
+            return py_type, FieldInfo(default=None)
+        return py_type, FieldInfo()
+
+    # Handle enum
+    enum_values = prop.get("enum")
+    if enum_values:
+        enum_cls = Enum(f"{parent_name}_{field_name.title()}", {v: v for v in enum_values}, type=str)
+        py_type = enum_cls
+    else:
+        py_type = TYPE_MAP.get(prop_type, str)
+
+    # Handle nullable
+    if nullable or not is_required:
+        py_type = py_type | None
+
+    default = prop.get("default")
+    if default is not None:
+        return py_type, FieldInfo(default=default)
+    elif is_required and not nullable:
+        return py_type, FieldInfo()
+    else:
+        return py_type, FieldInfo(default=None)

openapi_cli_gen/engine/registry.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from pydantic import BaseModel, create_model
+from pydantic.fields import FieldInfo
+
+from openapi_cli_gen.engine.models import schema_to_model, TYPE_MAP
+from openapi_cli_gen.spec.parser import EndpointInfo
+
+
+@dataclass
+class CommandInfo:
+    model: type[BaseModel]
+    endpoint: EndpointInfo
+
+
+def build_registry(
+    endpoints: list[EndpointInfo],
+) -> dict[str, dict[str, CommandInfo]]:
+    """Build a command registry from parsed endpoints.
+
+    Returns: {group_name: {command_name: CommandInfo}}
+    """
+    registry: dict[str, dict[str, CommandInfo]] = {}
+    model_cache: dict[str, type[BaseModel]] = {}
+
+    for ep in endpoints:
+        group = ep.tag
+        cmd_name = _derive_command_name(ep)
+        model = _build_command_model(ep, model_cache)
+
+        registry.setdefault(group, {})[cmd_name] = CommandInfo(
+            model=model,
+            endpoint=ep,
+        )
+
+    return registry
+
+
+def _derive_command_name(ep: EndpointInfo) -> str:
+    """Derive a CLI command name from an endpoint.
+
+    Strategy: strip the tag suffix (singular or plural) from operationId, kebab-case the rest.
+    Examples: list_users → list, create_user → create, get_user → get
+    """
+    op_id = ep.operation_id
+    tag = ep.tag
+
+    # Build variants of the tag to try stripping from the end of op_id
+    # e.g. tag="users" → try "_users", "_user"
+    # e.g. tag="companies" → try "_companies", "_company", "_companie"
+    singular = tag.rstrip("s") if tag.endswith("s") else tag
+    suffixes_to_try = [f"_{tag}", f"_{singular}", f"_{tag}s"]
+
+    for suffix in suffixes_to_try:
+        if op_id.endswith(suffix):
+            remainder = op_id[: -len(suffix)]
+            if remainder:
+                return _to_kebab(remainder)
+
+    # Try stripping tag as a prefix (e.g. users_list → list)
+    for prefix in [f"{tag}_", f"{singular}_"]:
+        if op_id.startswith(prefix):
+            remainder = op_id[len(prefix):]
+            if remainder:
+                return _to_kebab(remainder)
+
+    # Try extracting just the leading verb if nothing else matched
+    for verb in ("list", "get", "create", "update", "delete", "patch", "send", "trigger"):
+        if op_id.startswith(f"{verb}_") or op_id == verb:
+            return verb
+
+    return _to_kebab(op_id)
+
+
+def _to_kebab(name: str) -> str:
+    """Convert snake_case or camelCase to kebab-case."""
+    name = name.replace("_", "-")
+    name = re.sub(r"([a-z])([A-Z])", r"\1-\2", name).lower()
+    return name
+
+
+def _build_command_model(
+    ep: EndpointInfo,
+    model_cache: dict[str, type[BaseModel]],
+) -> type[BaseModel]:
+    """Build a dynamic Pydantic model combining params + body fields."""
+    from typing import Any
+
+    fields: dict[str, Any] = {}
+
+    # Path params → required fields
+    for p in ep.path_params:
+        py_type = TYPE_MAP.get(p.type, str)
+        fields[p.name] = (py_type, FieldInfo(description=p.name))
+
+    # Query params → optional fields with defaults
+    for p in ep.query_params:
+        py_type = TYPE_MAP.get(p.type, str)
+        if not p.required:
+            py_type = py_type | None
+        default = p.default if p.default is not None else (None if not p.required else ...)
+        fields[p.name] = (py_type, FieldInfo(default=default))
+
+    # Body schema → merge fields from schema_to_model
+    if ep.body_schema:
+        body_model = schema_to_model(
+            f"{ep.tag.title()}{ep.operation_id.title().replace('_', '')}Body",
+            ep.body_schema,
+            doc=ep.summary,
+            _model_cache=model_cache,
+        )
+        for fname, finfo in body_model.model_fields.items():
+            fields[fname] = (finfo.annotation, finfo)
+
+    model_name = f"Cmd_{ep.operation_id}"
+    return create_model(model_name, __doc__=ep.summary or ep.operation_id, **fields)

openapi_cli_gen/output/formatter.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+
+import yaml
+from rich.console import Console
+from rich.table import Table
+
+
+def format_output(
+    data: dict | list,
+    fmt: str = "json",
+    print_output: bool = False,
+) -> str | None:
+    """Format API response data for CLI output."""
+    if fmt == "json":
+        result = json.dumps(data, indent=2, default=str)
+    elif fmt == "yaml":
+        result = yaml.dump(data, default_flow_style=False, sort_keys=False)
+    elif fmt == "raw":
+        result = str(data)
+    elif fmt == "table":
+        _print_table(data)
+        return None
+    else:
+        result = json.dumps(data, indent=2, default=str)
+
+    if print_output:
+        print(result)
+    return result
+
+
+def _print_table(data: dict | list) -> None:
+    """Print data as a rich table."""
+    console = Console()
+    rows = None
+    if isinstance(data, list):
+        rows = data
+    elif isinstance(data, dict):
+        for key in ("items", "results", "data"):
+            if key in data and isinstance(data[key], list):
+                rows = data[key]
+                for k, v in data.items():
+                    if k != key:
+                        console.print(f"[dim]{k}:[/dim] {v}")
+                break
+
+    if rows and len(rows) > 0:
+        table = Table(show_header=True, header_style="bold")
+        keys = list(rows[0].keys())
+        for key in keys:
+            table.add_column(key)
+        for row in rows:
+            table.add_row(*[str(row.get(k, "")) for k in keys])
+        console.print(table)
+    elif isinstance(data, dict):
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("Field")
+        table.add_column("Value")
+        for key, value in data.items():
+            if isinstance(value, (dict, list)):
+                value = json.dumps(value, default=str)
+            table.add_row(str(key), str(value))
+        console.print(table)
+    else:
+        console.print(str(data))

openapi_cli_gen/spec/loader.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import jsonref
+import yaml
+
+
+def load_spec(spec_path: str) -> dict:
+    """Load an OpenAPI spec from a file path, resolve all $ref references.
+
+    Args:
+        spec_path: Path to YAML or JSON OpenAPI spec file.
+
+    Returns:
+        Fully resolved spec as a dict (all $ref inlined).
+
+    Raises:
+        FileNotFoundError: If spec file does not exist.
+    """
+    path = Path(spec_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Spec file not found: {spec_path}")
+
+    text = path.read_text()
+
+    if path.suffix in (".json",):
+        raw = json.loads(text)
+    else:
+        raw = yaml.safe_load(text)
+
+    base_uri = path.absolute().as_uri()
+    return jsonref.replace_refs(raw, base_uri=base_uri)

openapi_cli_gen/spec/parser.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ParamInfo:
+    name: str
+    type: str  # "string", "integer", "number", "boolean"
+    required: bool = False
+    default: object = None
+    enum: list[str] | None = None
+
+
+@dataclass
+class SecuritySchemeInfo:
+    name: str
+    type: str  # "http", "apiKey", "oauth2", "openIdConnect"
+    scheme: str | None = None  # "bearer", "basic" (for http type)
+    header_name: str | None = None  # for apiKey type
+    location: str | None = None  # "header", "query", "cookie" (for apiKey)
+
+
+@dataclass
+class EndpointInfo:
+    operation_id: str
+    tag: str
+    method: str  # "get", "post", "put", "patch", "delete"
+    path: str
+    summary: str = ""
+    path_params: list[ParamInfo] = field(default_factory=list)
+    query_params: list[ParamInfo] = field(default_factory=list)
+    body_schema: dict | None = None
+
+
+HTTP_METHODS = ("get", "post", "put", "patch", "delete")
+
+
+def parse_spec(resolved_spec: dict) -> list[EndpointInfo]:
+    """Parse a resolved OpenAPI spec into a list of EndpointInfo."""
+    endpoints = []
+
+    for path, path_item in resolved_spec.get("paths", {}).items():
+        for method in HTTP_METHODS:
+            operation = path_item.get(method)
+            if not operation:
+                continue
+
+            tag = (operation.get("tags") or ["default"])[0]
+            op_id = operation.get("operationId", f"{method}_{path.strip('/').replace('/', '_')}")
+
+            path_params = []
+            query_params = []
+            for p in operation.get("parameters", []):
+                schema = p.get("schema", {})
+                param = ParamInfo(
+                    name=p["name"],
+                    type=schema.get("type", "string"),
+                    required=p.get("required", False),
+                    default=schema.get("default"),
+                    enum=schema.get("enum"),
+                )
+                if p["in"] == "path":
+                    path_params.append(param)
+                elif p["in"] == "query":
+                    query_params.append(param)
+
+            body_schema = None
+            rb = operation.get("requestBody")
+            if rb:
+                content = rb.get("content", {})
+                json_content = content.get("application/json", {})
+                body_schema = json_content.get("schema")
+
+            endpoints.append(EndpointInfo(
+                operation_id=op_id,
+                tag=tag,
+                method=method,
+                path=path,
+                summary=operation.get("summary", ""),
+                path_params=path_params,
+                query_params=query_params,
+                body_schema=body_schema,
+            ))
+
+    return endpoints
+
+
+def extract_security_schemes(resolved_spec: dict) -> list[SecuritySchemeInfo]:
+    """Extract security scheme info from spec."""
+    schemes = []
+    components = resolved_spec.get("components", {})
+    security_schemes = components.get("securitySchemes", {})
+
+    for name, scheme in security_schemes.items():
+        schemes.append(SecuritySchemeInfo(
+            name=name,
+            type=scheme.get("type", ""),
+            scheme=scheme.get("scheme"),
+            header_name=scheme.get("name"),
+            location=scheme.get("in"),
+        ))
+
+    return schemes

openapi_cli_gen-0.0.1.dist-info/METADATA

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: openapi-cli-gen
+Version: 0.0.1
+Summary: Generate typed Python CLIs from OpenAPI specs with Pydantic model flattening into CLI flags
+Project-URL: Homepage, https://github.com/shivaam/openapi-cli-gen
+Project-URL: Repository, https://github.com/shivaam/openapi-cli-gen
+Project-URL: Issues, https://github.com/shivaam/openapi-cli-gen/issues
+Author: shivaam
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,code-generator,fastapi,openapi,pydantic,typer
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: jsonref>=1.1
+Requires-Dist: openapi-pydantic>=0.5
+Requires-Dist: pydantic-settings>=2.13
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator>=0.56; extra == 'dev'
+Requires-Dist: fastapi>=0.115; extra == 'dev'
+Requires-Dist: jinja2>=3.1; extra == 'dev'
+Requires-Dist: pydanclick>=0.5; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: typer>=0.12; extra == 'dev'
+Requires-Dist: uvicorn>=0.30; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# openapi-cli-gen
+
+**Generate a full CLI from any OpenAPI spec in seconds. Nested request bodies become flat `--flags` automatically.**
+
+[![PyPI](https://img.shields.io/pypi/v/openapi-cli-gen)](https://pypi.org/project/openapi-cli-gen/)
+[![Python](https://img.shields.io/pypi/pyversions/openapi-cli-gen)](https://pypi.org/project/openapi-cli-gen/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+```bash
+# Instead of this:
+curl -X POST /api/users -d '{"name": "John", "address": {"city": "NYC", "state": "NY"}}'
+
+# You get this:
+mycli users create --name John --address.city NYC --address.state NY
+```
+
+No tool existed to take an OpenAPI spec and produce a typed Python CLI where nested request bodies are flattened into individual `--flag` arguments. Until now.
+
+## Why openapi-cli-gen?
+
+- **Zero boilerplate** -- point at a spec, get a working CLI
+- **Nested model flattening** -- `--address.city NYC` not `--data '{"address":{"city":"NYC"}}'`
+- **Works at any depth** -- 1, 2, 3+ levels of nesting with automatic dot-notation
+- **Arrays, dicts, enums** -- all handled (`--tags dev --tags lead`, `--env KEY=val`, `--role {admin,user}`)
+- **Auth from your spec** -- reads `securitySchemes`, wires up `--token` + env vars automatically
+- **Two modes** -- generate a pip-installable package OR run instantly without code generation
+- **Pluggable** -- use standalone or plug API commands into your existing CLI
+
+## Quick Start
+
+```bash
+pip install openapi-cli-gen
+```
+
+### Generate a CLI Package
+
+```bash
+openapi-cli-gen generate --spec https://api.example.com/openapi.json --name mycli
+cd mycli && pip install -e .
+```
+
+Now your users can:
+
+```bash
+mycli users list
+mycli users create --name John --email john@example.com --address.city NYC
+mycli jobs create --retry.backoff.strategy exponential --retry.backoff.initial-delay-ms 2000
+```
+
+### Run Instantly (No Code Generation)
+
+Don't want to generate files? Point directly at any spec:
+
+```bash
+openapi-cli-gen run --spec api.yaml users list --limit 10
+```
+
+### Inspect a Spec
+
+See what commands would be generated before committing:
+
+```bash
+$ openapi-cli-gen inspect --spec api.yaml
+
+API: My API v1.0
+Endpoints: 14
+Groups: 6
+Auth schemes: 2
+
+  users:
+    GET     /users                  List all users
+    POST    /users                  Create a new user [body]
+    GET     /users/{user_id}        Get a user by ID
+  orders:
+    POST    /orders                 Create an order [body]
+  ...
+```
+
+## The Core Feature: Nested Model Flattening
+
+This is what makes openapi-cli-gen different from every other tool. Your API has nested request bodies -- we flatten them into ergonomic CLI flags:
+
+```bash
+# Depth 1: address nested inside user
+mycli users create --name John --address.city NYC --address.state NY
+
+# Depth 2: CEO nested inside company
+mycli companies create --name Acme --ceo.name Bob --ceo.email bob@acme.com
+
+# Depth 3: backoff nested inside retry nested inside job config
+mycli jobs create --name etl --retry.backoff.strategy exponential --retry.backoff.initial-delay-ms 2000
+
+# JSON fallback for anything complex
+mycli users create --address '{"street": "123 Main", "city": "NYC"}'
+
+# Mix both -- dot-notation overrides JSON
+mycli users create --address '{"city": "NYC"}' --address.city SF  # city=SF wins
+```
+
+### Arrays
+
+```bash
+# Repeated flags for primitives
+mycli users create --tags admin --tags reviewer
+# Or comma-separated
+mycli users create --tags admin,reviewer
+# Or JSON
+mycli users create --tags '["admin", "reviewer"]'
+
+# JSON for arrays of objects
+mycli orders create --items '[{"product_id": "abc", "quantity": 2}]'
+```
+
+### Dicts
+
+```bash
+# Key=value syntax
+mycli jobs create --environment JAVA_HOME=/usr/lib/jvm --environment PATH=/usr/bin
+# Or JSON
+mycli jobs create --environment '{"JAVA_HOME": "/usr/lib/jvm"}'
+```
+
+### Enums
+
+```bash
+mycli users create --role admin   # choices shown in --help: {admin, user, viewer}
+mycli users create --role superadmin  # ValidationError: Input should be 'admin', 'user' or 'viewer'
+```
+
+## As a Library
+
+### Build a full CLI from a spec
+
+```python
+from openapi_cli_gen import build_cli
+
+app = build_cli(spec="openapi.yaml", name="mycli")
+app()
+```
+
+### Plug API commands into your existing CLI
+
+Already have a CLI with custom commands? Add auto-generated API commands alongside them:
+
+```python
+from openapi_cli_gen import build_command_group
+
+# Returns {group: {command: CommandInfo}}
+registry = build_command_group(spec="openapi.yaml", name="mycli")
+# Integrate with your existing argparse-based CLI
+```
+
+## Authentication
+
+Auth auto-configures from your spec's `securitySchemes`:
+
+```bash
+# Via environment variable (recommended for CI/CD)
+export MYCLI_TOKEN=sk-xxx
+mycli users list
+
+# Via flag (overrides env var)
+mycli users list --token sk-xxx
+```
+
+| Spec scheme | CLI flag | Env var |
+|---|---|---|
+| Bearer token | `--token` | `{NAME}_TOKEN` |
+| API key | `--api-key` | `{NAME}_API_KEY` |
+| Basic auth | `--username`, `--password` | `{NAME}_USERNAME`, `{NAME}_PASSWORD` |
+
+## How It Works
+
+```
+Your OpenAPI spec (YAML/JSON)
+    |
+    v
+1. Load & resolve all $ref references (jsonref)
+2. Parse into typed models (openapi-pydantic)
+3. Group endpoints by tag -> command groups
+4. Flatten request body schemas into CLI flags (pydantic-settings)
+5. Build CLI with dispatch: mycli <group> <command> --flags
+    |
+    v
+Working CLI in seconds
+```
+
+## Compared to Alternatives
+
+| Feature | openapi-cli-gen | specli | restish | Stainless |
+|---|---|---|---|---|
+| Language | Python | TypeScript | Go | Go |
+| Generates distributable code | Yes | No | No | Yes |
+| Runtime mode (no codegen) | Yes | Yes | Yes | No |
+| Nested model flattening | All depths | Scalars only | No | 2 levels |
+| Typed Pydantic models | Yes | No | No | N/A |
+| Auth from spec | Yes | Partial | Manual | Yes |
+| Pluggable into existing CLI | Yes | No | No | No |
+| Open source | Yes | Yes | Yes | No |
+
+## Supported
+
+- OpenAPI 3.0 and 3.1
+- All HTTP methods (GET, POST, PUT, PATCH, DELETE)
+- Local, external, and circular `$ref` resolution
+- Path parameters, query parameters, request bodies
+- Nested objects, arrays, dicts, enums, nullable fields
+- Bearer token and API key authentication
+- JSON, YAML, table (rich), and raw output formats
+
+## Status
+
+Early release (v0.0.1). Core features work. Roadmap includes Typer output target (rich `--help`, shell completion), auto-pagination, OAuth2, and more.
+
+[Issues and feedback welcome.](https://github.com/shivaam/openapi-cli-gen/issues)
+
+## License
+
+MIT

openapi_cli_gen-0.0.1.dist-info/RECORD

@@ -0,0 +1,24 @@
+openapi_cli_gen/__init__.py,sha256=IVSN7uSg6k-Wp5o3c5SfjvtKbjd5kIiQ8WNdz2h9BKI,245
+openapi_cli_gen/__main__.py,sha256=wWAxiy6PoAGYJ30f9p2N9aAz_VxEUbu4N8ffnEZkiEI,45
+openapi_cli_gen/cli.py,sha256=VADSyWpnPfJNAG68-WVRBUnK0UVeKYOnxKgj8BfI7N8,2184
+openapi_cli_gen/codegen/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openapi_cli_gen/codegen/generator.py,sha256=vjEWJW86U4w25A-K_wTRaeBmKfbh158nTAQOomnmn1Y,1036
+openapi_cli_gen/codegen/templates/__init__.py.jinja2,sha256=8LRwD27OuseSMRaKZtrwvS0mgPXA7fiDdnvHZiqYrmM,55
+openapi_cli_gen/codegen/templates/cli.py.jinja2,sha256=K2ujDNdg6G5ffKeJrnivcz-Que4n2bf5zfJiH1Fd3cE,216
+openapi_cli_gen/codegen/templates/pyproject.toml.jinja2,sha256=ywQiYePi0gqSJvsa3wNQs4HJBNXHHfCD_zJurGS3GGg,316
+openapi_cli_gen/engine/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openapi_cli_gen/engine/auth.py,sha256=YY8RLxJ5Z1YMQm9nKRqtxwq5GMr77HJC4Hf7NDRKQpo,1756
+openapi_cli_gen/engine/builder.py,sha256=oBj6lTHSjx87EvdSAgVsOAlPKVF51qs6xXIkaq3rmUc,4242
+openapi_cli_gen/engine/dispatch.py,sha256=e8zmZ1QmpQ3y6WvHnkkzNDBNSw15FD2R-riI9wyg44Q,1834
+openapi_cli_gen/engine/models.py,sha256=PX-tQbaM1buE-iSPZDVrEJYOZGjQN-RvtxEky7p2yBU,3791
+openapi_cli_gen/engine/registry.py,sha256=D1Di4xEUdLj6uya4sG_zZLbu5JOAyKl1TdN30putZFs,3870
+openapi_cli_gen/output/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openapi_cli_gen/output/formatter.py,sha256=XwyMZGeVdtPHRZ5DenNT0-twUNPTvBJ3jMoAmejXo-4,1961
+openapi_cli_gen/spec/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+openapi_cli_gen/spec/loader.py,sha256=Vp9hdFG1ONF8XgQF4_JyoEbS4IT_ucWwQHJgmED3JGQ,795
+openapi_cli_gen/spec/parser.py,sha256=iAhMpE-CDombfg4yYYGMjNKyJG_CNg1t1Ax291A9v8c,3325
+openapi_cli_gen-0.0.1.dist-info/METADATA,sha256=YlSutjYlewn9QfoBG4vB8bMspPGSQ32IxRgWHUMn2zw,8243
+openapi_cli_gen-0.0.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+openapi_cli_gen-0.0.1.dist-info/entry_points.txt,sha256=SJdj_Damhq_WSvR7GauoATrZrgnIqE9Qtv4kdhjS7VE,61
+openapi_cli_gen-0.0.1.dist-info/licenses/LICENSE,sha256=SK6dycQgq7_7nRsXwgZKO6kt6dtEpx6jQq2FwUd-I4k,1085
+openapi_cli_gen-0.0.1.dist-info/RECORD,,

openapi_cli_gen-0.0.1.dist-info/WHEEL

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

openapi_cli_gen-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openapi-cli-gen = openapi_cli_gen.cli:main

openapi_cli_gen-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 openapi-cli-gen contributors
+
+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.