openapi2cli 0.1.0__py3-none-any.whl

openapi2cli/__init__.py

@@ -0,0 +1,17 @@
+"""api2cli - Generate CLI tools from OpenAPI specs."""
+
+__version__ = "0.1.0"
+
+from .generator import CLIGenerator, GeneratedCLI
+from .parser import Endpoint, OpenAPIParser, Parameter, ParsedSpec
+from .runtime import APIClient
+
+__all__ = [
+    "OpenAPIParser",
+    "ParsedSpec",
+    "Endpoint",
+    "Parameter",
+    "CLIGenerator",
+    "GeneratedCLI",
+    "APIClient",
+]

openapi2cli/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as `python -m api2cli`."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

openapi2cli/cli.py

@@ -0,0 +1,117 @@
+"""Main CLI for openapi2cli."""
+
+import sys
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .generator import CLIGenerator
+from .parser import OpenAPIParser
+
+
+@click.group()
+@click.version_option(version=__version__)
+def main():
+    """openapi2cli - Generate CLI tools from OpenAPI specs.
+
+    Built for AI agents who need to interact with APIs.
+
+    Example:
+
+        # Generate a CLI from a spec
+        openapi2cli generate https://httpbin.org/spec.json --name httpbin
+
+        # Then use it
+        ./httpbin get --output json
+    """
+    pass
+
+
+@main.command()
+@click.argument("spec", type=str)
+@click.option("--name", "-n", required=True, help="Name for the generated CLI")
+@click.option("--output", "-o", type=click.Path(), help="Output file path")
+@click.option("--stdout", is_flag=True, help="Print to stdout instead of file")
+def generate(spec: str, name: str, output: str, stdout: bool):
+    """Generate a CLI from an OpenAPI spec.
+
+    SPEC can be a file path or URL to an OpenAPI 3.x specification.
+
+    Examples:
+
+        openapi2cli generate petstore.yaml --name petstore
+        openapi2cli generate https://api.example.com/openapi.json --name example -o example_cli.py
+    """
+    try:
+        # Parse the spec
+        parser = OpenAPIParser()
+        parsed = parser.parse(spec)
+
+        click.echo(f"Parsed: {parsed.title} v{parsed.version}", err=True)
+        click.echo(f"Found {len(parsed.endpoints)} endpoints", err=True)
+
+        # Generate CLI
+        generator = CLIGenerator()
+        cli = generator.generate(parsed, name=name)
+
+        click.echo(f"Generated {len(cli.groups)} command groups", err=True)
+
+        # Output
+        if stdout:
+            click.echo(cli.to_python())
+        else:
+            output_path = Path(output) if output else Path(f"{name}_cli.py")
+            cli.save(output_path)
+            click.echo(f"Saved to: {output_path}", err=True)
+            click.echo(f"\nUsage: python {output_path} --help", err=True)
+
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+@main.command()
+@click.argument("spec", type=str)
+def inspect(spec: str):
+    """Inspect an OpenAPI spec without generating code.
+
+    Shows the structure of the API: endpoints, parameters, auth, etc.
+    """
+    try:
+        parser = OpenAPIParser()
+        parsed = parser.parse(spec)
+
+        click.echo(f"\n📋 {parsed.title} v{parsed.version}")
+        click.echo(f"   {parsed.description[:100]}..." if len(parsed.description) > 100 else f"   {parsed.description}")
+        click.echo(f"\n🌐 Base URL: {parsed.base_url}")
+
+        # Auth schemes
+        if parsed.auth_schemes:
+            click.echo("\n🔐 Authentication:")
+            for scheme in parsed.auth_schemes:
+                click.echo(f"   - {scheme.name}: {scheme.type}")
+
+        # Endpoints by tag
+        grouped = parsed.group_by_tag()
+        click.echo(f"\n📡 Endpoints ({len(parsed.endpoints)} total):")
+
+        for tag, endpoints in sorted(grouped.items()):
+            click.echo(f"\n   [{tag}]")
+            for ep in endpoints[:5]:  # Show first 5
+                params = ", ".join(p.name for p in ep.parameters[:3])
+                if len(ep.parameters) > 3:
+                    params += "..."
+                click.echo(f"   • {ep.method:6} {ep.path}")
+                if params:
+                    click.echo(f"           params: {params}")
+            if len(endpoints) > 5:
+                click.echo(f"   ... and {len(endpoints) - 5} more")
+
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

openapi2cli/generator.py

@@ -0,0 +1,430 @@
+"""CLI code generator."""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional, Union
+
+from jinja2 import Template
+
+from .parser import AuthScheme, Endpoint, ParsedSpec
+
+
+@dataclass
+class CLIOption:
+    """A CLI option/argument."""
+
+    name: str
+    param_type: str = "str"
+    required: bool = False
+    default: Optional[str] = None
+    help: str = ""
+    is_flag: bool = False
+    multiple: bool = False
+
+
+@dataclass
+class CLICommand:
+    """A CLI command."""
+
+    name: str
+    method: str
+    path: str
+    help: str = ""
+    options: List[CLIOption] = field(default_factory=list)
+    has_body: bool = False
+
+
+@dataclass
+class CLIGroup:
+    """A group of CLI commands (tag)."""
+
+    name: str
+    help: str = ""
+    commands: List[CLICommand] = field(default_factory=list)
+
+
+@dataclass
+class GeneratedCLI:
+    """A generated CLI structure."""
+
+    name: str
+    version: str = "1.0.0"
+    description: str = ""
+    base_url: str = ""
+    groups: List[CLIGroup] = field(default_factory=list)
+    global_options: List[CLIOption] = field(default_factory=list)
+    auth_schemes: List[AuthScheme] = field(default_factory=list)
+
+    def to_python(self) -> str:
+        """Generate Python code for the CLI."""
+        return CLI_TEMPLATE.render(cli=self)
+
+    def to_standalone_script(self) -> str:
+        """Generate a standalone executable script."""
+        code = self.to_python()
+        return f"#!/usr/bin/env python3\n{code}"
+
+    def save(self, path: Union[Path, str]) -> None:
+        """Save the generated CLI to a file."""
+        path = Path(path)
+        code = self.to_standalone_script()
+        path.write_text(code)
+        # Make executable
+        path.chmod(0o755)
+
+
+class CLIGenerator:
+    """Generates CLI code from a parsed OpenAPI spec."""
+
+    def generate(self, spec: ParsedSpec, name: str) -> GeneratedCLI:
+        """Generate a CLI from a parsed spec."""
+        # Generate global options (auth, output format, base URL)
+        global_options = self._generate_global_options(spec)
+
+        # Group endpoints by tag and generate command groups
+        grouped = spec.group_by_tag()
+        groups = []
+
+        for tag, endpoints in grouped.items():
+            group = self._generate_group(tag, endpoints)
+            groups.append(group)
+
+        return GeneratedCLI(
+            name=name,
+            version=spec.version,
+            description=spec.description or f"CLI for {spec.title}",
+            base_url=spec.base_url,
+            groups=groups,
+            global_options=global_options,
+            auth_schemes=spec.auth_schemes,
+        )
+
+    def _generate_global_options(self, spec: ParsedSpec) -> List[CLIOption]:
+        """Generate global CLI options."""
+        options = [
+            CLIOption(
+                name="--output",
+                param_type="str",
+                default="table",
+                help="Output format (json, table, raw)",
+            ),
+            CLIOption(
+                name="--base-url",
+                param_type="str",
+                default=spec.base_url,
+                help="API base URL",
+            ),
+        ]
+
+        # Add auth options based on security schemes
+        for scheme in spec.auth_schemes:
+            if scheme.type == "apiKey":
+                options.append(CLIOption(
+                    name="--api-key",
+                    param_type="str",
+                    help=f"API key ({scheme.param_name})",
+                ))
+            elif scheme.type == "http" and scheme.scheme == "bearer":
+                options.append(CLIOption(
+                    name="--token",
+                    param_type="str",
+                    help="Bearer token for authentication",
+                ))
+
+        # Default auth option if no schemes defined
+        if not any(o.name in ("--api-key", "--token") for o in options):
+            options.append(CLIOption(
+                name="--api-key",
+                param_type="str",
+                help="API key for authentication",
+            ))
+
+        return options
+
+    def _generate_group(self, tag: str, endpoints: List[Endpoint]) -> CLIGroup:
+        """Generate a command group from a tag."""
+        commands = []
+
+        for endpoint in endpoints:
+            cmd = self._generate_command(endpoint)
+            commands.append(cmd)
+
+        return CLIGroup(
+            name=self._sanitize_name(tag),
+            help=f"Commands for {tag}",
+            commands=commands,
+        )
+
+    def _generate_command(self, endpoint: Endpoint) -> CLICommand:
+        """Generate a CLI command from an endpoint."""
+        options = []
+        seen_names = set()
+
+        def add_option(opt: CLIOption) -> None:
+            """Add option if name not already used."""
+            if opt.name not in seen_names:
+                seen_names.add(opt.name)
+                options.append(opt)
+
+        # Add options for parameters
+        for param in endpoint.parameters:
+            add_option(CLIOption(
+                name=param.cli_name,
+                param_type=self._map_type(param.schema_type),
+                required=param.required,
+                default=str(param.default) if param.default is not None else None,
+                help=param.description or f"{param.name} parameter",
+            ))
+
+        # Add options for request body properties
+        has_body = False
+        if endpoint.request_body:
+            has_body = True
+            for prop_name, prop_schema in endpoint.request_body.properties.items():
+                required = prop_name in endpoint.request_body.required_props
+                add_option(CLIOption(
+                    name=f"--{self._sanitize_name(prop_name)}",
+                    param_type=self._map_type(prop_schema.get('type', 'string')),
+                    required=required,
+                    help=prop_schema.get('description', f"{prop_name} field"),
+                ))
+
+            # Also add a --data option for raw JSON input
+            add_option(CLIOption(
+                name="--data",
+                param_type="str",
+                help="Raw JSON data for request body",
+            ))
+
+        return CLICommand(
+            name=endpoint.cli_name,
+            method=endpoint.method,
+            path=endpoint.path,
+            help=endpoint.summary or endpoint.description or f"{endpoint.method} {endpoint.path}",
+            options=options,
+            has_body=has_body,
+        )
+
+    def _sanitize_name(self, name: str) -> str:
+        """Sanitize a name for use as a CLI command/option."""
+        # Convert camelCase to kebab-case
+        name = re.sub(r'([a-z])([A-Z])', r'\1-\2', name)
+        # Replace underscores, spaces, dots with hyphens
+        name = name.replace('_', '-').replace(' ', '-').replace('.', '-')
+        # Remove invalid characters
+        name = re.sub(r'[^a-zA-Z0-9-]', '', name)
+        # Remove consecutive hyphens
+        name = re.sub(r'-+', '-', name)
+        # Remove leading/trailing hyphens
+        name = name.strip('-')
+        return name.lower()
+
+    def _map_type(self, schema_type: str) -> str:
+        """Map OpenAPI type to Python/Click type."""
+        mapping = {
+            'integer': 'int',
+            'number': 'float',
+            'boolean': 'bool',
+            'array': 'str',  # JSON string for arrays
+            'object': 'str',  # JSON string for objects
+        }
+        return mapping.get(schema_type, 'str')
+
+
+# Template for generated CLI - use raw strings to avoid escaping issues
+CLI_TEMPLATE_STR = '''
+"""{{ cli.name }} - Generated CLI for {{ cli.description }}
+
+Auto-generated by openapi2cli. Do not edit manually.
+"""
+
+import json
+import os
+import sys
+from typing import Optional
+
+import click
+import requests
+
+try:
+    from rich.console import Console
+    from rich.table import Table
+    RICH_AVAILABLE = True
+except ImportError:
+    RICH_AVAILABLE = False
+
+
+# Configuration
+BASE_URL = "{{ cli.base_url }}"
+ENV_PREFIX = "{{ cli.name.upper().replace('-', '_') }}"
+
+
+def get_auth_headers(api_key: Optional[str] = None, token: Optional[str] = None) -> dict:
+    """Get authentication headers."""
+    headers = {}
+
+    # Try CLI args first, then env vars
+    key = api_key or os.environ.get(ENV_PREFIX + "_API_KEY")
+    tok = token or os.environ.get(ENV_PREFIX + "_TOKEN")
+
+    if tok:
+        headers["Authorization"] = "Bearer " + tok
+    elif key:
+        {%- for scheme in cli.auth_schemes %}
+        {%- if scheme.type == "apiKey" and scheme.location == "header" %}
+        headers["{{ scheme.param_name }}"] = key
+        {%- endif %}
+        {%- endfor %}
+        {%- if not cli.auth_schemes %}
+        headers["X-API-Key"] = key
+        {%- endif %}
+
+    return headers
+
+
+def format_output(data, output_format: str):
+    """Format output based on requested format."""
+    if output_format == "json":
+        click.echo(json.dumps(data, indent=2))
+    elif output_format == "raw":
+        click.echo(data)
+    elif output_format == "table" and RICH_AVAILABLE:
+        console = Console()
+        if isinstance(data, list) and data:
+            table = Table()
+            first = data[0]
+            if isinstance(first, dict):
+                for key in first.keys():
+                    table.add_column(str(key))
+                for item in data:
+                    if isinstance(item, dict):
+                        table.add_row(*[str(v) for v in item.values()])
+            else:
+                table.add_column("value")
+                for item in data:
+                    table.add_row(str(item))
+            console.print(table)
+        elif isinstance(data, dict):
+            table = Table()
+            table.add_column("Key")
+            table.add_column("Value")
+            for k, v in data.items():
+                table.add_row(str(k), str(v))
+            console.print(table)
+        else:
+            console.print(data)
+    else:
+        click.echo(json.dumps(data, indent=2))
+
+
+def make_request(
+    method: str,
+    path: str,
+    base_url: str,
+    params: dict = None,
+    json_data: dict = None,
+    headers: dict = None,
+    path_params: dict = None,
+):
+    """Make an HTTP request to the API."""
+    if path_params:
+        for key, value in path_params.items():
+            path = path.replace("{" + key + "}", str(value))
+
+    url = base_url.rstrip("/") + path
+
+    try:
+        response = requests.request(
+            method=method,
+            url=url,
+            params=params,
+            json=json_data,
+            headers=headers,
+            timeout=30,
+        )
+        response.raise_for_status()
+
+        try:
+            return response.json()
+        except json.JSONDecodeError:
+            return response.text
+
+    except requests.exceptions.RequestException as e:
+        click.echo("Error: " + str(e), err=True)
+        sys.exit(1)
+
+
+@click.group()
+@click.option("--output", "-o", default="json", help="Output format (json, table, raw)")
+@click.option("--base-url", default=BASE_URL, help="API base URL")
+@click.option("--api-key", envvar=ENV_PREFIX + "_API_KEY", help="API key")
+@click.option("--token", envvar=ENV_PREFIX + "_TOKEN", help="Bearer token")
+@click.version_option(version="{{ cli.version }}")
+@click.pass_context
+def cli(ctx, output, base_url, api_key, token):
+    """{{ cli.description }}"""
+    ctx.ensure_object(dict)
+    ctx.obj["output"] = output
+    ctx.obj["base_url"] = base_url
+    ctx.obj["headers"] = get_auth_headers(api_key, token)
+
+{% for group in cli.groups %}
+
+@cli.group()
+def {{ group.name | replace("-", "_") }}():
+    """{{ group.help }}"""
+    pass
+
+{% for cmd in group.commands %}
+
+@{{ group.name | replace("-", "_") }}.command("{{ cmd.name }}")
+{%- for opt in cmd.options %}
+@click.option("{{ opt.name }}"{% if opt.required %}, required=True{% endif %}{% if opt.default %}, default="{{ opt.default }}"{% endif %}, help="{{ opt.help | replace('"', '\\"') }}")
+{%- endfor %}
+@click.pass_context
+def {{ group.name | replace("-", "_") | replace(".", "_") }}_{{ cmd.name | replace("-", "_") | replace(".", "_") }}(ctx{% for opt in cmd.options %}, {{ opt.name | replace("--", "") | replace("-", "_") | replace(".", "_") }}{% endfor %}):
+    """{{ cmd.help | replace('"', '\\"') }}"""
+    path_params = {}
+    query_params = {}
+    body_data = {}
+
+    {%- for opt in cmd.options %}
+    {%- set var_name = opt.name | replace("--", "") | replace("-", "_") %}
+    if {{ var_name }} is not None:
+        {%- if "id" in opt.name.lower() and "{" in cmd.path %}
+        path_params["{{ opt.name | replace("--", "") | replace("-", "") }}"] = {{ var_name }}
+        {%- elif opt.name == "--data" %}
+        body_data = json.loads({{ var_name }})
+        {%- elif cmd.has_body and opt.name != "--data" %}
+        body_data["{{ opt.name | replace("--", "") | replace("-", "_") }}"] = {{ var_name }}
+        {%- else %}
+        query_params["{{ opt.name | replace("--", "") }}"] = {{ var_name }}
+        {%- endif %}
+    {%- endfor %}
+
+    result = make_request(
+        method="{{ cmd.method }}",
+        path="{{ cmd.path }}",
+        base_url=ctx.obj["base_url"],
+        params=query_params or None,
+        json_data=body_data or None,
+        headers=ctx.obj["headers"],
+        path_params=path_params or None,
+    )
+
+    format_output(result, ctx.obj["output"])
+{% endfor %}
+{% endfor %}
+
+
+def main():
+    """Main entry point."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()
+'''
+
+CLI_TEMPLATE = Template(CLI_TEMPLATE_STR)

openapi2cli/parser.py

@@ -0,0 +1,325 @@
+"""OpenAPI spec parser."""
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+import requests
+import yaml
+
+
+@dataclass
+class Parameter:
+    """An API endpoint parameter."""
+
+    name: str
+    location: str  # path, query, header, cookie
+    required: bool = False
+    description: str = ""
+    schema_type: str = "string"
+    default: Any = None
+    enum: List[str] = field(default_factory=list)
+
+    @property
+    def cli_name(self) -> str:
+        """Convert to CLI option name."""
+        # petId -> pet-id, api_key -> api-key
+        name = re.sub(r'([a-z])([A-Z])', r'\1-\2', self.name)
+        name = name.replace('_', '-').lower()
+        return f"--{name}"
+
+
+@dataclass
+class RequestBody:
+    """Request body schema."""
+
+    content_type: str = "application/json"
+    required: bool = False
+    properties: Dict[str, Any] = field(default_factory=dict)
+    required_props: List[str] = field(default_factory=list)
+
+
+@dataclass
+class AuthScheme:
+    """Authentication scheme."""
+
+    name: str
+    type: str  # apiKey, http, oauth2, openIdConnect
+    location: str = ""  # header, query, cookie (for apiKey)
+    scheme: str = ""  # bearer, basic (for http)
+    param_name: str = ""  # name of the header/query param
+
+
+@dataclass
+class Endpoint:
+    """An API endpoint."""
+
+    path: str
+    method: str
+    operation_id: str = ""
+    summary: str = ""
+    description: str = ""
+    tags: List[str] = field(default_factory=list)
+    parameters: List[Parameter] = field(default_factory=list)
+    request_body: Optional[RequestBody] = None
+    security: List[str] = field(default_factory=list)
+
+    @property
+    def cli_name(self) -> str:
+        """Generate CLI command name."""
+        if self.operation_id:
+            # getPetById -> get-pet-by-id -> get (simplified)
+            name = re.sub(r'([a-z])([A-Z])', r'\1-\2', self.operation_id)
+            name = name.lower()
+
+            # Simplify common patterns
+            # getPetById -> get, listPets -> list, addPet -> add
+            parts = name.split('-')
+            if len(parts) >= 2:
+                # Keep first part and maybe second if it's meaningful
+                verb = parts[0]
+                if verb in ('get', 'list', 'find', 'add', 'create', 'update', 'delete', 'remove'):
+                    if len(parts) > 2 and parts[-1] not in ('by', 'all'):
+                        # get-pet-by-id -> get-by-id
+                        return '-'.join([verb] + parts[2:])
+                    return verb
+            return name
+
+        # Fallback: method + simplified path
+        path_parts = [p for p in self.path.split('/') if p and not p.startswith('{')]
+        if path_parts:
+            return f"{self.method.lower()}-{'-'.join(path_parts[-2:])}"
+        return self.method.lower()
+
+
+@dataclass
+class ParsedSpec:
+    """A parsed OpenAPI specification."""
+
+    title: str
+    version: str
+    description: str = ""
+    base_url: str = ""
+    endpoints: List[Endpoint] = field(default_factory=list)
+    auth_schemes: List[AuthScheme] = field(default_factory=list)
+
+    def group_by_tag(self) -> Dict[str, List[Endpoint]]:
+        """Group endpoints by their tags."""
+        groups: Dict[str, List[Endpoint]] = {}
+
+        for endpoint in self.endpoints:
+            tags = endpoint.tags or ["default"]
+            for tag in tags:
+                if tag not in groups:
+                    groups[tag] = []
+                groups[tag].append(endpoint)
+
+        return groups
+
+
+class OpenAPIParser:
+    """Parser for OpenAPI 3.x specifications."""
+
+    def parse(self, source: Union[str, Path]) -> ParsedSpec:
+        """Parse an OpenAPI spec from a file path or URL."""
+        raw = self._load_spec(source)
+        return self._parse_spec(raw)
+
+    def _load_spec(self, source: Union[str, Path]) -> dict:
+        """Load spec from file or URL."""
+        if isinstance(source, Path):
+            source = str(source)
+
+        # Check if URL
+        if source.startswith(('http://', 'https://')):
+            response = requests.get(source, timeout=30)
+            response.raise_for_status()
+            content = response.text
+            # Detect format
+            if source.endswith('.yaml') or source.endswith('.yml'):
+                return yaml.safe_load(content)
+            try:
+                return json.loads(content)
+            except json.JSONDecodeError:
+                return yaml.safe_load(content)
+
+        # Local file
+        path = Path(source)
+        content = path.read_text()
+
+        if path.suffix in ('.yaml', '.yml'):
+            return yaml.safe_load(content)
+        return json.loads(content)
+
+    def _parse_spec(self, raw: dict) -> ParsedSpec:
+        """Parse raw spec dict into ParsedSpec."""
+        info = raw.get('info', {})
+
+        # Get base URL from servers
+        servers = raw.get('servers', [])
+        base_url = servers[0]['url'] if servers else ""
+
+        # Parse endpoints
+        endpoints = self._parse_paths(raw.get('paths', {}), raw)
+
+        # Parse auth schemes
+        auth_schemes = self._parse_security_schemes(
+            raw.get('components', {}).get('securitySchemes', {})
+        )
+
+        return ParsedSpec(
+            title=info.get('title', 'API'),
+            version=info.get('version', '1.0.0'),
+            description=info.get('description', ''),
+            base_url=base_url,
+            endpoints=endpoints,
+            auth_schemes=auth_schemes,
+        )
+
+    def _parse_paths(self, paths: dict, spec: dict) -> List[Endpoint]:
+        """Parse paths into endpoints."""
+        endpoints = []
+
+        for path, methods in paths.items():
+            # Handle path-level parameters
+            path_params = self._parse_parameters(
+                methods.get('parameters', []), spec
+            )
+
+            for method, details in methods.items():
+                if method in ('get', 'post', 'put', 'patch', 'delete', 'head', 'options'):
+                    endpoint = self._parse_endpoint(
+                        path, method.upper(), details, spec, path_params
+                    )
+                    endpoints.append(endpoint)
+
+        return endpoints
+
+    def _parse_endpoint(
+        self,
+        path: str,
+        method: str,
+        details: dict,
+        spec: dict,
+        path_params: List[Parameter]
+    ) -> Endpoint:
+        """Parse a single endpoint."""
+        # Parse parameters (combine path-level and operation-level)
+        params = path_params.copy()
+        params.extend(
+            self._parse_parameters(details.get('parameters', []), spec)
+        )
+
+        # Parse request body
+        request_body = None
+        if 'requestBody' in details:
+            request_body = self._parse_request_body(details['requestBody'], spec)
+
+        # Get security requirements
+        security = []
+        for sec in details.get('security', []):
+            security.extend(sec.keys())
+
+        return Endpoint(
+            path=path,
+            method=method,
+            operation_id=details.get('operationId', ''),
+            summary=details.get('summary', ''),
+            description=details.get('description', ''),
+            tags=details.get('tags', []),
+            parameters=params,
+            request_body=request_body,
+            security=security,
+        )
+
+    def _parse_parameters(self, params: list, spec: dict) -> List[Parameter]:
+        """Parse parameters."""
+        result = []
+
+        for param in params:
+            # Handle $ref
+            if '$ref' in param:
+                param = self._resolve_ref(param['$ref'], spec)
+
+            schema = param.get('schema', {})
+
+            result.append(Parameter(
+                name=param.get('name', ''),
+                location=param.get('in', 'query'),
+                required=param.get('required', False),
+                description=param.get('description', ''),
+                schema_type=schema.get('type', 'string'),
+                default=schema.get('default'),
+                enum=schema.get('enum', []),
+            ))
+
+        return result
+
+    def _parse_request_body(self, body: dict, spec: dict) -> RequestBody:
+        """Parse request body."""
+        # Handle $ref
+        if '$ref' in body:
+            body = self._resolve_ref(body['$ref'], spec)
+
+        content = body.get('content', {})
+
+        # Prefer JSON
+        content_type = 'application/json'
+        if content_type not in content:
+            content_type = next(iter(content.keys()), 'application/json')
+
+        schema = content.get(content_type, {}).get('schema', {})
+
+        # Handle $ref in schema
+        if '$ref' in schema:
+            schema = self._resolve_ref(schema['$ref'], spec)
+
+        properties = schema.get('properties', {})
+        required_props = schema.get('required', [])
+
+        return RequestBody(
+            content_type=content_type,
+            required=body.get('required', False),
+            properties=properties,
+            required_props=required_props,
+        )
+
+    def _parse_security_schemes(self, schemes: dict) -> List[AuthScheme]:
+        """Parse security schemes."""
+        result = []
+
+        for name, details in schemes.items():
+            scheme_type = details.get('type', '')
+
+            auth = AuthScheme(
+                name=name,
+                type=scheme_type,
+            )
+
+            if scheme_type == 'apiKey':
+                auth.location = details.get('in', 'header')
+                auth.param_name = details.get('name', '')
+            elif scheme_type == 'http':
+                auth.scheme = details.get('scheme', 'bearer')
+
+            result.append(auth)
+
+        return result
+
+    def _resolve_ref(self, ref: str, spec: dict) -> dict:
+        """Resolve a $ref pointer."""
+        if not ref.startswith('#/'):
+            return {}
+
+        parts = ref[2:].split('/')
+        current = spec
+
+        for part in parts:
+            if isinstance(current, dict) and part in current:
+                current = current[part]
+            else:
+                return {}
+
+        return current if isinstance(current, dict) else {}

openapi2cli/runtime.py

@@ -0,0 +1,170 @@
+"""Runtime for executing API calls and running generated CLIs."""
+
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Union
+
+import requests
+
+
+@dataclass
+class CLIResult:
+    """Result of running a CLI command."""
+
+    exit_code: int
+    output: str
+    error: str = ""
+
+
+class APIClient:
+    """HTTP client for making API requests."""
+
+    def __init__(
+        self,
+        base_url: str,
+        auth_header: Optional[str] = None,
+        auth_value: Optional[str] = None,
+        api_key_param: Optional[str] = None,
+        api_key_value: Optional[str] = None,
+        timeout: int = 30,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.auth_header = auth_header
+        self.auth_value = auth_value
+        self.api_key_param = api_key_param
+        self.api_key_value = api_key_value
+        self.timeout = timeout
+        self.session = requests.Session()
+
+    def _get_headers(self) -> dict:
+        """Get request headers including auth."""
+        headers = {"Content-Type": "application/json"}
+
+        if self.auth_header and self.auth_value:
+            headers[self.auth_header] = self.auth_value
+
+        return headers
+
+    def _get_params(self, params: Optional[dict]) -> dict:
+        """Get query parameters including API key if configured."""
+        result = params.copy() if params else {}
+
+        if self.api_key_param and self.api_key_value:
+            result[self.api_key_param] = self.api_key_value
+
+        return result
+
+    def _build_url(self, path: str, path_params: Optional[dict] = None) -> str:
+        """Build full URL with path parameter substitution."""
+        if path_params:
+            for key, value in path_params.items():
+                path = path.replace(f"{{{key}}}", str(value))
+
+        return f"{self.base_url}{path}"
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[dict] = None,
+        json_data: Optional[dict] = None,
+        path_params: Optional[dict] = None,
+    ) -> requests.Response:
+        """Make an HTTP request."""
+        url = self._build_url(path, path_params)
+        headers = self._get_headers()
+        query_params = self._get_params(params)
+
+        return self.session.request(
+            method=method,
+            url=url,
+            params=query_params or None,
+            json=json_data,
+            headers=headers,
+            timeout=self.timeout,
+        )
+
+    def get(
+        self,
+        path: str,
+        params: Optional[dict] = None,
+        path_params: Optional[dict] = None,
+    ) -> requests.Response:
+        """Make a GET request."""
+        return self.request("GET", path, params=params, path_params=path_params)
+
+    def post(
+        self,
+        path: str,
+        json_data: Optional[dict] = None,
+        params: Optional[dict] = None,
+        path_params: Optional[dict] = None,
+    ) -> requests.Response:
+        """Make a POST request."""
+        return self.request(
+            "POST", path, params=params, json_data=json_data, path_params=path_params
+        )
+
+    def put(
+        self,
+        path: str,
+        json_data: Optional[dict] = None,
+        params: Optional[dict] = None,
+        path_params: Optional[dict] = None,
+    ) -> requests.Response:
+        """Make a PUT request."""
+        return self.request(
+            "PUT", path, params=params, json_data=json_data, path_params=path_params
+        )
+
+    def delete(
+        self,
+        path: str,
+        params: Optional[dict] = None,
+        path_params: Optional[dict] = None,
+    ) -> requests.Response:
+        """Make a DELETE request."""
+        return self.request("DELETE", path, params=params, path_params=path_params)
+
+    def patch(
+        self,
+        path: str,
+        json_data: Optional[dict] = None,
+        params: Optional[dict] = None,
+        path_params: Optional[dict] = None,
+    ) -> requests.Response:
+        """Make a PATCH request."""
+        return self.request(
+            "PATCH", path, params=params, json_data=json_data, path_params=path_params
+        )
+
+
+class CLIRunner:
+    """Runner for executing generated CLIs."""
+
+    def __init__(self, script_path: Union[Path, str]):
+        self.script_path = Path(script_path)
+
+    def run(self, args: List[str], env: Optional[dict] = None) -> CLIResult:
+        """Run the CLI with given arguments."""
+        import os
+
+        full_env = os.environ.copy()
+        if env:
+            full_env.update(env)
+
+        result = subprocess.run(
+            [sys.executable, str(self.script_path)] + args,
+            capture_output=True,
+            text=True,
+            env=full_env,
+            timeout=60,
+        )
+
+        return CLIResult(
+            exit_code=result.returncode,
+            output=result.stdout,
+            error=result.stderr,
+        )

openapi2cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: openapi2cli
+Version: 0.1.0
+Summary: Generate CLI tools from OpenAPI specs — built for AI agents
+Project-URL: Homepage, https://github.com/Olafs-World/openapi2cli
+Project-URL: Repository, https://github.com/Olafs-World/openapi2cli
+Project-URL: Documentation, https://github.com/Olafs-World/openapi2cli#readme
+Author-email: Olaf <olaf.bot@agentmail.to>
+License: MIT
+License-File: LICENSE
+Keywords: agents,api,cli,code-generation,openapi,swagger
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: jinja2>=3.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.25
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# openapi2cli 🔧
+
+[![CI](https://github.com/Olafs-World/openapi2cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Olafs-World/openapi2cli/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/openapi2cli.svg)](https://pypi.org/project/openapi2cli/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Generate CLI tools from OpenAPI specs.** Built for AI agents who need to interact with APIs.
+
+```bash
+# Generate a CLI from any OpenAPI spec
+$ openapi2cli generate https://httpbin.org/spec.json --name httpbin
+
+# Use it immediately
+$ ./httpbin_cli.py get --output json
+{
+  "url": "https://httpbin.org/get",
+  "headers": { ... }
+}
+```
+
+## Why?
+
+AI agents are great at executing CLI commands. They're less great at crafting HTTP requests from memory. This tool bridges the gap:
+
+1. **OpenAPI spec** → any API with a spec becomes usable
+2. **CLI generation** → instant `--help`, tab completion, validation
+3. **No code changes** → just point at a spec and go
+
+## Installation
+
+```bash
+pip install openapi2cli
+```
+
+## Quick Start
+
+### Generate a CLI
+
+```bash
+# From a URL
+openapi2cli generate https://petstore3.swagger.io/api/v3/openapi.json --name petstore
+
+# From a local file
+openapi2cli generate ./api-spec.yaml --name myapi --output myapi
+```
+
+### Use the Generated CLI
+
+```bash
+# See available commands
+./petstore --help
+
+# List pets
+./petstore pet find-by-status --status available
+
+# Add a pet (with auth)
+export PETSTORE_API_KEY=your-key
+./petstore pet add --name "Fluffy" --status available
+
+# JSON output for scripting
+./petstore pet get --pet-id 123 --output json | jq '.name'
+```
+
+### Inspect a Spec
+
+```bash
+# See what's in a spec without generating
+openapi2cli inspect https://httpbin.org/spec.json
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| 🔍 **Auto-discovery** | Parses OpenAPI 3.x specs (YAML or JSON) |
+| 🏷️ **Smart grouping** | Commands grouped by API tags |
+| 🔐 **Auth support** | API keys, Bearer tokens, env vars |
+| 📊 **Output formats** | JSON, table, or raw |
+| ⚡ **Fast generation** | Single command, instant CLI |
+| 🤖 **Agent-friendly** | Self-documenting with `--help` |
+
+## Configuration
+
+### Authentication
+
+Generated CLIs support multiple auth methods:
+
+```bash
+# Via environment variable (recommended)
+export PETSTORE_API_KEY=your-key
+./petstore pet list
+
+# Via CLI option
+./petstore --api-key your-key pet list
+
+# Bearer token
+export PETSTORE_TOKEN=your-bearer-token
+./petstore pet list
+```
+
+The env var prefix is derived from the CLI name (uppercase, underscores).
+
+### Base URL Override
+
+```bash
+# Use a different API server
+./petstore --base-url https://staging.petstore.io/api pet list
+```
+
+### Output Formats
+
+```bash
+# JSON (default, good for piping)
+./petstore pet list --output json
+
+# Table (human-readable, requires rich)
+./petstore pet list --output table
+
+# Raw (API response as-is)
+./petstore pet list --output raw
+```
+
+## Generated CLI Structure
+
+For a spec with tags `pet`, `store`, `user`:
+
+```
+petstore
+├── pet
+│   ├── add          # POST /pet
+│   ├── get          # GET /pet/{petId}
+│   ├── update       # PUT /pet
+│   ├── delete       # DELETE /pet/{petId}
+│   └── find-by-status
+├── store
+│   ├── order
+│   └── inventory
+└── user
+    ├── create
+    ├── login
+    └── logout
+```
+
+## API Reference
+
+### `openapi2cli generate`
+
+```
+openapi2cli generate SPEC --name NAME [--output PATH] [--stdout]
+
+Arguments:
+  SPEC          OpenAPI spec (file path or URL)
+
+Options:
+  -n, --name    CLI name (required)
+  -o, --output  Output file path (default: {name}_cli.py)
+  --stdout      Print to stdout instead of file
+```
+
+### `openapi2cli inspect`
+
+```
+openapi2cli inspect SPEC
+
+Arguments:
+  SPEC          OpenAPI spec (file path or URL)
+```
+
+### Python API
+
+```python
+from openapi2cli import OpenAPIParser, CLIGenerator
+
+# Parse a spec
+parser = OpenAPIParser()
+spec = parser.parse("https://api.example.com/openapi.json")
+
+print(f"API: {spec.title}")
+print(f"Endpoints: {len(spec.endpoints)}")
+
+# Generate CLI
+generator = CLIGenerator()
+cli = generator.generate(spec, name="example")
+
+# Save to file
+cli.save("example_cli.py")
+
+# Or get the code
+code = cli.to_python()
+```
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/Olafs-World/openapi2cli.git
+cd openapi2cli
+
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/ -v
+
+# Run only unit tests (no API calls)
+pytest tests/ -v -m "not integration"
+```
+
+## How It Works
+
+1. **Parse** - Load OpenAPI 3.x spec (YAML/JSON, local/URL)
+2. **Extract** - Pull endpoints, parameters, auth schemes, request bodies
+3. **Generate** - Create Click-based CLI with proper groups and options
+4. **Output** - Save as standalone Python script (executable)
+
+The generated CLI uses `requests` for HTTP and optionally `rich` for pretty output.
+
+## Limitations
+
+- OpenAPI 3.x only (not Swagger 2.0)
+- No file upload support yet
+- Complex nested request bodies may need `--data` JSON flag
+- OAuth2 flows not fully implemented (use `--token` with pre-obtained tokens)
+
+## License
+
+MIT © [Olaf](https://olafs-world.vercel.app)
+
+---
+
+<p align="center">
+  <i>Built by an AI who got tired of writing curl commands 🤖</i>
+</p>

openapi2cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+openapi2cli/__init__.py,sha256=tbcK5dHpbnX8UP8b9yLidCZF02eOVwb2Z15w80XatIs,371
+openapi2cli/__main__.py,sha256=YemrHLS5fqMtkTuPMAnCmPLHN0nqfB6OC-mRMGFCccA,106
+openapi2cli/cli.py,sha256=szav-4w2LMlogvTBfDKilPerCvrnyZCDRSlZpqHSZMg,3660
+openapi2cli/generator.py,sha256=IhVSCHEh6KfNRmaeK8_xU8ZhExU7I0Ok0RJj-6XcnBI,13476
+openapi2cli/parser.py,sha256=02q24MUBKss-1CDJ0vvI5qwDlio3FBpV7PbtOpa_Qo4,10155
+openapi2cli/runtime.py,sha256=5Vo6pt-KShC2MjX63BvfJ-e4TW670owbDvMVvbrf2Zk,4877
+openapi2cli-0.1.0.dist-info/METADATA,sha256=OaPAPIEp3cyW7G5GWW6QXEuxkpejJLBHLdxje1ekCKY,6778
+openapi2cli-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+openapi2cli-0.1.0.dist-info/entry_points.txt,sha256=PYoT4cTlCmdI6m1-yOM58pA2rRpkt667UKBaq386tEk,53
+openapi2cli-0.1.0.dist-info/licenses/LICENSE,sha256=R6wp-QnWz5hcOS9xs_DAAzChQm-ir9s5IQyVsVRXzz4,1061
+openapi2cli-0.1.0.dist-info/RECORD,,

openapi2cli-0.1.0.dist-info/WHEEL

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

openapi2cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openapi2cli = openapi2cli.cli:main

openapi2cli-0.1.0.dist-info/licenses/LICENSE

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