CLI WIZARD

Generate modern CLIs from OpenAPI specifications.

Table of Contents

• Features
• Installation
• Usage
• Configuration
• Commands
• Issues
• License

Features

Code Generation

• Generate complete Python CLI projects from OpenAPI v3 specifications
• Automatic command grouping based on OpenAPI tags
• Automatic help generation for all commands
• Clean, colored terminal output
• --debug flag for verbose logging, with credentials redacted from the output
• Built-in API client with configurable base URL and timeout
• SSL/TLS support with custom CA certificate bundles
• --ca-file option to specify custom CA certificates at runtime
• --no-verify-ssl flag to disable certificate verification

Customization

• YAML-based configuration for full customization
• Configurable output directory and package name
• Tag inclusion/exclusion filters
• Custom command naming via TagMapping and CommandMapping
• Customizable splash screen with color support
• Configurable logging with colors, file output, and rotation

Developer Experience

• Generated projects are pip-installable out of the box
• Auto-generated pyproject.toml and VERSION
• Auto-generated README.md with commands and configuration reference
• Auto-generated DEVELOPMENT.md, CHANGELOG.md and LICENSE
• Test suite for the generated CLI, ready to run
• tox.ini with test, lint, type, format and coverage environments, plus a Makefile wrapping them
• Pre-commit configuration running ruff and mypy
• Optional GitHub setup (IncludeGithubWorkflows): test, release, docs, PR validation, CodeQL, changelog and labeler workflows, plus Dependabot, issue and PR templates, and CODEOWNERS
• Resources (CA certs, splash files) bundled in the package
• Profile management for storing credentials and settings

Installation

pip install cli-wizard

Usage

Step 1: Prepare Your OpenAPI Specification

Ensure you have an OpenAPI v3 specification file (JSON or YAML format). For example, openapi.yaml:

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /users:
    get:
      operationId: listUsers
      summary: List all users
      tags:
        - Users
      responses:
        '200':
          description: OK

Step 2: Generate the CLI

Run the generate command, passing the OpenAPI spec and a project name:

cli-wizard generate --api openapi.yaml --project-name "My CLI"

This creates a complete Python CLI project in the my-cli directory: the command name derives from the project name, and every other setting takes its default. Pass --output to write it elsewhere.

Step 3: Install the Generated CLI

Navigate to the generated project and install it:

pip install -e my-cli

Step 4: Use Your CLI

Your CLI is now ready to use:

my-cli --help
my-cli users list-users

Step 5: Customize with a Configuration File

To go beyond the defaults, create a cli-wizard.yaml file with the settings you want to change. Every parameter is optional:

ProjectName: "My CLI"
DefaultBaseUrl: "https://api.example.com"

# Customize the splash screen
SplashFile: "splash.txt"
SplashColor: "#00FFFF"

# Filter which tags to include
IncludeTags:
  - Users
  - Products

Then generate from it. The project lands in the current directory, in a directory named after CommandName:

cli-wizard generate --configuration cli-wizard.yaml --api openapi.yaml

Starting Without a Specification

To start from scratch instead, run bootstrap. It prompts for the main settings, writes a commented cli-wizard.yaml, and generates a basic CLI from it, without API commands. The CLI lands in the current directory, in a directory named after CommandName; pass --output to write it elsewhere:

cli-wizard bootstrap --configuration cli-wizard.yaml

Then edit the configuration, point Api at your specification, and rebuild with cli-wizard generate --configuration cli-wizard.yaml.

Configuration

See configuration reference for full documentation. See the examples directory for complete configuration examples.

Commands

cli-wizard generate

Generate a CLI from an OpenAPI specification, with an optional configuration file.

cli-wizard generate [OPTIONS]

Options:

• --api, -a - Path to the OpenAPI spec file, YAML or JSON. Without it and without Api in the configuration, the CLI is generated without API commands
• --configuration, -c - Path to the cli-wizard.yaml configuration file. Without it, every parameter takes its default
• --project-name, -p - Human-readable project name; the generated command name derives from it, unless the configuration sets it
• --output, -o - Output directory (default: a directory named after CommandName in the current directory)
• --force, -f - Skip the confirmation prompt when the output directory is not empty

cli-wizard bootstrap

Bootstrap a new CLI project interactively, without an OpenAPI specification. It does two things: it writes a configuration file to evolve the project from, then generates a basic CLI from that file, without API commands, in the output directory.

cli-wizard bootstrap [OPTIONS]

Options:

• --configuration, -c - Path for the cli-wizard.yaml configuration file (default: ./cli-wizard.yaml). An existing file is overwritten, after confirmation, without keeping any of its values
• --output, -o - Output directory of the basic CLI (default: a directory named after CommandName in the current directory)
• --force, -f - Skip the confirmation prompts to overwrite an existing configuration file or to write into a non-empty directory

Issues

Please report any issues or feature requests on the GitHub Issues page.

License

This project is licensed under the MIT License. See the LICENSE file for details.