OpenAPI to Click CLI Generator

A Python tool that automatically generates command-line interfaces from OpenAPI 3.x specifications. It wraps openapi-python-client and creates Click-based CLIs for easy API interaction.

What This Skill Does

This skill helps you work with the OpenAPI Click CLI Generator repository, which converts OpenAPI specifications into fully functional Python CLI applications. The generator validates OpenAPI specs, generates a Python API client, and creates an intuitive Click-based command-line interface.

Instructions for AI Agent

When working with this codebase, follow these guidelines:

1. Understanding the Project Structure

2. Development Workflow

**Setting up the environment:**

```bash

Install dependencies and create virtual environment

uv sync

Activate virtual environment

source .venv/bin/activate

```

**Running the generator:**

```bash

Basic usage

uv run python app/main.py <OPENAPI_SPEC_PATH> <OUTPUT_PATH>

With custom template

uv run python app/main.py <OPENAPI_SPEC_PATH> <OUTPUT_PATH> --template-path TEMPLATE_PATH

Example with test spec

uv run python app/main.py test_spec.json ./output

```

**Running tests:**

```bash

Run all tests

uv run pytest tests

Run specific test file

uv run pytest tests/test_main.py

Run specific test with verbose output

uv run pytest -v tests/test_main.py::TestOpenAPISpec::test_valid_spec

```

3. Core Generation Pipeline

The CLI generation follows this sequence (found in `app/main.py:129-169`):

1. **Validation** - Verify file format (YAML/JSON) and validate OpenAPI 3.x spec using Pydantic model

2. **Client Generation** - Invoke openapi-python-client to generate Python API client

3. **Package Setup** - Add `__init__.py` files and update `pyproject.toml`

4. **Template Rendering** - Generate CLI code using Jinja2 template with endpoint mappings

5. **Output** - Write `cli.py` to output directory

4. Key Implementation Details

**OpenAPI Validation:**

**operationId Handling Convention:**

**Client Package Discovery:**

**Template Rendering:**

5. Generated Output Structure

When generation completes successfully, the output directory contains:

```

output/

├── pyproject.toml (from openapi-python-client)

├── {client_package_name}/ (auto-named from spec)

│ ├── __init__.py

│ ├── api/

│ │ └── default/

│ │ └── {operation_id}.py (one per endpoint)

│ └── models/

└── cli.py (Click CLI - generated from template)

```

6. Testing Strategy

When adding or modifying features:

7. Common Tasks

**Adding a new template variable:**

1. Extract the data in `app/main.py` (in the template rendering section around line 98-123)

2. Pass it to the template context

3. Use it in `templates/cli_template.jinja2`

**Modifying the CLI structure:**

1. Edit `templates/cli_template.jinja2` for output changes

2. Update template rendering logic in `app/main.py` if new data is needed

3. Add tests in `tests/test_main.py` to verify the changes

**Supporting a new OpenAPI version:**

1. Update the `OpenAPISpec` Pydantic model in `app/main.py`

2. Adjust validation logic as needed

3. Add test cases for the new version

8. Important Constraints

9. Debugging Tips

Example Usage

```bash

Generate CLI from a local OpenAPI spec

uv run python app/main.py openapi.yaml ./my_cli

Generate CLI from JSON spec with custom template

uv run python app/main.py api_spec.json ./output --template-path ./custom_templates

Run tests to verify changes

uv run pytest -v tests

```