0
# CLI Interface
1

2
Command-line interface for generating Python clients from OpenAPI specifications. The CLI provides a user-friendly way to generate client libraries with various customization options.
3

4
## Capabilities
5

6
### Main Command
7

8
The primary command for generating OpenAPI Python clients from specifications.
9

10
```python { .api }
11
def generate(
12
    url: Optional[str] = None,
13
    path: Optional[Path] = None,
14
    custom_template_path: Optional[Path] = None,
15
    meta: MetaType = MetaType.POETRY,
16
    file_encoding: str = "utf-8",
17
    config_path: Optional[Path] = None,
18
    fail_on_warning: bool = False,
19
    overwrite: bool = False,
20
    output_path: Optional[Path] = None,
21
) -> None:
22
    """
23
    Generate a new OpenAPI Client library.
24
    
25
    Parameters:
26
    - url: A URL to read the OpenAPI document from
27
    - path: A path to the OpenAPI document
28
    - custom_template_path: A path to a directory containing custom template(s)
29
    - meta: The type of metadata to generate (POETRY, SETUP, PDM, UV, NONE)
30
    - file_encoding: Encoding used when writing generated files
31
    - config_path: Path to the config file to use
32
    - fail_on_warning: Exit with error code on warnings
33
    - overwrite: Overwrite the existing client if it exists
34
    - output_path: Path to write the generated code to
35
    """
36
```
37

38
### Version Information
39

40
Display version information and exit.
41

42
```bash
43
openapi-python-client --version
44
```
45

46
### Error Handling
47

48
The CLI provides comprehensive error handling and reporting.
49

50
```python { .api }
51
def handle_errors(errors: Sequence[GeneratorError], fail_on_warning: bool = False) -> None:
52
    """
53
    Turn custom errors into formatted error messages.
54
    
55
    Parameters:
56
    - errors: List of GeneratorError objects to handle
57
    - fail_on_warning: Whether to exit with error code on warnings
58
    """
59
```
60

61
## Usage Examples
62

63
### Basic Generation
64

65
Generate a client from a URL:
66
```bash
67
openapi-python-client generate --url https://api.example.com/openapi.json
68
```
69

70
Generate a client from a local file:
71
```bash
72
openapi-python-client generate --path ./openapi.yaml
73
```
74

75
### Advanced Options
76

77
Generate with custom configuration:
78
```bash
79
openapi-python-client generate \
80
  --url https://api.example.com/openapi.json \
81
  --config config.yaml \
82
  --meta poetry \
83
  --overwrite \
84
  --output-path ./my-client
85
```
86

87
Generate with custom templates:
88
```bash
89
openapi-python-client generate \
90
  --url https://api.example.com/openapi.json \
91
  --custom-template-path ./my-templates
92
```
93

94
Generate with specific encoding:
95
```bash
96
openapi-python-client generate \
97
  --path ./openapi.yaml \
98
  --file-encoding utf-16
99
```
100

101
### Configuration File
102

103
Use a YAML configuration file for complex setups:
104

105
```yaml
106
# config.yaml
107
class_overrides:
108
  VeryLongModelName:
109
    class_name: ShortName
110
    module_name: short_name
111

112
project_name_override: "my-api-client"
113
package_name_override: "my_api_client"
114
post_hooks:
115
  - "ruff check --fix ."
116
  - "ruff format ."
117
  - "mypy ."
118

119
field_prefix: "attr_"
120
http_timeout: 10
121
```
122

123
Then use it:
124
```bash
125
openapi-python-client generate \
126
  --url https://api.example.com/openapi.json \
127
  --config config.yaml
128
```
129

130
## Output Structure
131

132
The CLI generates a complete Python package structure:
133

134
```
135
my-api-client/              # Project directory
136
├── pyproject.toml          # Project metadata
137
├── README.md               # Generated documentation
138
├── .gitignore             # Git ignore rules
139
└── my_api_client/          # Python package
140
    ├── __init__.py         # Package initialization
141
    ├── client.py           # HTTP client classes
142
    ├── errors.py           # Error definitions
143
    ├── types.py            # Type definitions
144
    ├── models/             # Data models
145
    │   ├── __init__.py
146
    │   └── *.py            # Individual model files
147
    └── api/                # API endpoints
148
        ├── __init__.py
149
        └── */              # Tag-based API modules
150
            ├── __init__.py
151
            └── *.py        # Endpoint functions
152
```