Metadata-Version: 2.4
Name: cli-wizard
Version: 3.0.0
Summary: Generate modern CLIs from OpenAPI specifications
Author-email: Giacomo Marciani <giacomo.marciani@gmail.com>
License: MIT
Project-URL: Homepage, https://gmarciani.github.io/cli-wizard/
Project-URL: Repository, https://github.com/gmarciani/cli-wizard
Project-URL: Issues, https://github.com/gmarciani/cli-wizard/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click~=8.4
Requires-Dist: Jinja2~=3.1
Requires-Dist: pydantic~=2.13
Requires-Dist: PyYAML~=6.0
Requires-Dist: requests~=2.34
Requires-Dist: ruff~=0.16.2
Dynamic: license-file

# CLI WIZARD

<div align="center">
<img src="https://raw.githubusercontent.com/gmarciani/cli-wizard/main/resources/brand/banner.png" alt="cli-wizard-banner" width="500">

[![PyPI version](https://img.shields.io/pypi/v/cli-wizard.svg)](https://pypi.org/project/cli-wizard)
[![Python versions](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue.svg)](https://pypi.org/project/cli-wizard)
[![License](https://img.shields.io/github/license/gmarciani/cli-wizard.svg)](https://github.com/gmarciani/cli-wizard/blob/main/LICENSE)
[![Build status](https://img.shields.io/github/actions/workflow/status/gmarciani/cli-wizard/test.yaml?branch=main)](https://github.com/gmarciani/cli-wizard/actions)
[![Tests](https://img.shields.io/github/actions/workflow/status/gmarciani/cli-wizard/test.yaml?branch=main&label=tests)](https://github.com/gmarciani/cli-wizard/actions)
[![Coverage](https://img.shields.io/codecov/c/github/gmarciani/cli-wizard)](https://codecov.io/gh/gmarciani/cli-wizard)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-261230.svg)](https://github.com/astral-sh/ruff)
[![Downloads](https://img.shields.io/pypi/dm/cli-wizard.svg)](https://pypi.org/project/cli-wizard)

</div>

Generate modern CLIs from OpenAPI specifications.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Commands](#commands)
- [Issues](#issues)
- [License](#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

```shell
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`:

```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:

```shell
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:

```shell
pip install -e my-cli
```

### Step 4: Use Your CLI

Your CLI is now ready to use:

```shell
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:

```yaml
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`:

```shell
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:

```shell
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](https://gmarciani.github.io/cli-wizard/configuration.html) for full documentation.
See the [examples](examples/) directory for complete configuration examples.

## Commands

### cli-wizard generate

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

```shell
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.

```shell
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](https://github.com/gmarciani/cli-wizard/issues) page.

## License

This project is licensed under the MIT License. See the [LICENSE](https://github.com/gmarciani/cli-wizard/blob/main/LICENSE) file for details.
