Initial api2cli implementation

- OpenAPI 3.x parser (YAML/JSON, local/URL)
- CLI generator using Click
- Runtime for API calls + CLI execution
- 37 tests (unit + integration)
- CI with Python 3.9-3.12
- Full README with examples

Built for AI agents who need CLI tools from API specs.

Author: king-olaf[bot]

.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      
+      - name: Lint with ruff
+        run: ruff check api2cli/ tests/
+      
+      - name: Run unit tests
+        run: pytest tests/ -v -m "not integration" --tb=short
+      
+      - name: Run integration tests
+        run: pytest tests/ -v -m "integration" --tb=short
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+      
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+        continue-on-error: true

.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.venv/
+env/
+venv/

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.

README.md

@@ -0,0 +1,234 @@
+# api2cli 🔧
+
+[![CI](https://github.com/Olafs-World/api2cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Olafs-World/api2cli/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/api2cli.svg)](https://pypi.org/project/api2cli/)
+[![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
+$ api2cli 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 api2cli
+```
+
+## Quick Start
+
+### Generate a CLI
+
+```bash
+# From a URL
+api2cli generate https://petstore3.swagger.io/api/v3/openapi.json --name petstore
+
+# From a local file
+api2cli 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
+api2cli 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
+
+### `api2cli generate`
+
+```
+api2cli 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
+```
+
+### `api2cli inspect`
+
+```
+api2cli inspect SPEC
+
+Arguments:
+  SPEC          OpenAPI spec (file path or URL)
+```
+
+### Python API
+
+```python
+from api2cli 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/api2cli.git
+cd api2cli
+
+# 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>

api2cli/__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",
+]

api2cli/__main__.py

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