0
# CLI Interface
1

2
The openapi-typescript command-line interface provides comprehensive type generation capabilities with extensive configuration options. It supports multiple input formats, advanced type generation features, and integration with build processes.
3

4
## Capabilities
5

6
### Basic Command Structure
7

8
The CLI follows a simple pattern with an input source and optional configuration flags.
9

10
```bash
11
openapi-typescript [input] [options]
12
```
13

14
### Input Sources
15

16
The CLI supports multiple input formats for maximum flexibility.
17

18
```bash
19
# Local file (YAML or JSON)
20
openapi-typescript ./api.yaml
21
openapi-typescript ./api.json
22

23
# Remote URL
24
openapi-typescript https://api.example.com/openapi.json
25
openapi-typescript https://raw.githubusercontent.com/user/repo/main/openapi.yaml
26

27
# Standard input
28
cat api.yaml | openapi-typescript
29
curl https://api.example.com/openapi.json | openapi-typescript
30

31
# Multiple schemas via Redocly config
32
openapi-typescript --redocly ./redocly.yaml
33
```
34

35
### Core Options
36

37
Essential options for basic CLI usage and output control.
38

39
```bash
40
# Help and version
41
openapi-typescript --help
42
openapi-typescript --version
43

44
# Output control
45
openapi-typescript ./api.yaml --output ./types.ts
46
openapi-typescript ./api.yaml -o ./api-types.ts
47

48
# Configuration file
49
openapi-typescript --redocly ./redocly.yaml
50
openapi-typescript -c ./custom-redocly.yaml
51

52
# Validation mode
53
openapi-typescript ./api.yaml --check
54
```
55

56
**Core Options Reference:**
57

58
| Option | Short | Description |
59
|--------|-------|-------------|
60
| `--help` | | Display help information |
61
| `--version` | | Display version number |
62
| `--output` | `-o` | Specify output file path |
63
| `--redocly` | `-c` | Path to Redocly configuration file |
64
| `--check` | | Check that generated types are up-to-date |
65
66
### Type Generation Options
67

68
Options controlling how TypeScript types are generated from OpenAPI schemas.
69

70
```bash
71
# Export types instead of interfaces
72
openapi-typescript ./api.yaml -o ./types.ts --export-type
73

74
# Generate immutable (readonly) types
75
openapi-typescript ./api.yaml -o ./types.ts --immutable
76

77
# Generate true TypeScript enums
78
openapi-typescript ./api.yaml -o ./types.ts --enum
79

80
# Export enum values as arrays
81
openapi-typescript ./api.yaml -o ./types.ts --enum --enum-values
82

83
# Deduplicate enums when using --enum
84
openapi-typescript ./api.yaml -o ./types.ts --enum --dedupe-enums
85
```
86

87
**Type Generation Options Reference:**
88

89
| Option | Description | Example Output |
90
|--------|-------------|----------------|
91
| `--export-type` | Export `type` instead of `interface` | `export type User = { ... }` |
92
| `--immutable` | Generate readonly properties | `readonly name: string` |
93
| `--enum` | Export true TS enums instead of unions | `enum Status { ACTIVE = "active" }` |
94
| `--enum-values` | Export enum values as arrays | `export const StatusValues = ["active", "inactive"]` |
95
| `--dedupe-enums` | Prevent duplicate enum exports | Single enum per unique value set |
96
97
### Schema Handling Options
98

99
Advanced options for customizing how OpenAPI schemas are interpreted and converted.
100

101
```bash
102
# Treat all objects as having additional properties
103
openapi-typescript ./api.yaml -o ./types.ts --additional-properties
104

105
# Use 'unknown' for empty objects instead of Record<string, never>
106
openapi-typescript ./api.yaml -o ./types.ts --empty-objects-unknown
107

108
# Ignore default values when determining non-nullable types
109
openapi-typescript ./api.yaml -o ./types.ts --default-non-nullable=false
110

111
# Make all properties required by default
112
openapi-typescript ./api.yaml -o ./types.ts --properties-required-by-default
113

114
# Generate tuples with length constraints from arrays
115
openapi-typescript ./api.yaml -o ./types.ts --array-length
116

117
# Convert paths to template literal types
118
openapi-typescript ./api.yaml -o ./types.ts --path-params-as-types
119

120
# Sort object properties alphabetically
121
openapi-typescript ./api.yaml -o ./types.ts --alphabetize
122

123
# Exclude deprecated schema elements
124
openapi-typescript ./api.yaml -o ./types.ts --exclude-deprecated
125
```
126

127
**Schema Handling Options Reference:**
128

129
| Option | Description | Impact |
130
|--------|-------------|--------|
131
| `--additional-properties` | Treat objects as `additionalProperties: true` | Allows arbitrary properties |
132
| `--empty-objects-unknown` | Use `unknown` for empty objects | `unknown` instead of `Record<string, never>` |
133
| `--default-non-nullable` | Consider defaults in nullability | More precise optional/required handling |
134
| `--properties-required-by-default` | Make all properties required | Override OpenAPI required arrays |
135
| `--array-length` | Generate tuples with constraints | `[string, string]` instead of `string[]` |
136
| `--path-params-as-types` | Use template literals for paths | `/users/${string}` instead of string |
137
| `--alphabetize` | Sort properties alphabetically | Consistent property ordering |
138
| `--exclude-deprecated` | Skip deprecated elements | Cleaner generated types |
139
140
### Advanced Options
141

142
Specialized options for complex scenarios and advanced use cases.
143

144
```bash
145
# Export schema types at root level
146
openapi-typescript ./api.yaml -o ./types.ts --root-types
147

148
# Don't add "Schema" prefix to root types
149
openapi-typescript ./api.yaml -o ./types.ts --root-types --root-types-no-schema-prefix
150

151
# Generate ApiPaths enum for all paths
152
openapi-typescript ./api.yaml -o ./types.ts --make-paths-enum
153

154
# Generate path parameter types automatically  
155
openapi-typescript ./api.yaml -o ./types.ts --generate-path-params
156
```
157

158
**Advanced Options Reference:**
159

160
| Option | Description | Result |
161
|--------|-------------|--------|
162
| `--root-types` | Export schemas as root-level types | `export type User = ...` alongside components |
163
| `--root-types-no-schema-prefix` | Remove "Schema" prefix from root types | `User` instead of `UserSchema` |
164
| `--make-paths-enum` | Create enum of all API paths | `enum ApiPaths { GetUsers = "/users" }` |
165
| `--generate-path-params` | Generate path parameter types automatically | Additional parameter type definitions |
166
167
### Multiple Schema Configuration
168

169
For complex projects with multiple OpenAPI schemas, use Redocly configuration files.
170

171
**redocly.yaml example:**
172

173
```yaml
174
apis:
175
  users:
176
    root: ./schemas/users.yaml
177
    x-openapi-ts:
178
      output: ./types/users.ts
179
      export-type: true
180
      immutable: true
181
  
182
  products:
183
    root: ./schemas/products.yaml
184
    x-openapi-ts:
185
      output: ./types/products.ts
186
      enum: true
187
      alphabetize: true
188

189
  combined:
190
    root: ./schemas/combined.yaml
191
    x-openapi-ts:
192
      output: ./types/api.ts
193
      path-params-as-types: true
194
      make-paths-enum: true
195
```
196

197
```bash
198
# Generate types for all configured schemas
199
openapi-typescript --redocly ./redocly.yaml
200
```
201

202
### Common Usage Patterns
203

204
Practical examples for typical development scenarios.
205

206
**Basic Development Workflow:**
207

208
```bash
209
# Generate types from local schema
210
openapi-typescript ./api/openapi.yaml --output ./src/types/api.ts
211

212
# Watch mode with file watcher (external tool)
213
npx nodemon --watch api/openapi.yaml --exec "openapi-typescript ./api/openapi.yaml -o ./src/types/api.ts"
214
```
215

216
**Production Build Integration:**
217

218
```bash
219
# Validate schema and generate types
220
openapi-typescript ./api/openapi.yaml --check --output ./dist/types.ts
221

222
# Advanced production settings
223
openapi-typescript ./api/openapi.yaml \
224
  --output ./dist/types.ts \
225
  --export-type \
226
  --immutable \
227
  --alphabetize \
228
  --exclude-deprecated \
229
  --enum
230
```
231

232
**Multi-API Project:**
233

234
```bash
235
# Generate types for multiple related APIs
236
openapi-typescript ./schemas/auth.yaml -o ./src/types/auth.ts --export-type
237
openapi-typescript ./schemas/users.yaml -o ./src/types/users.ts --export-type
238
openapi-typescript ./schemas/orders.yaml -o ./src/types/orders.ts --export-type
239
```
240

241
**Remote Schema Processing:**
242

243
```bash
244
# Fetch and process remote schema
245
openapi-typescript https://api.github.com/spec/openapi.json \
246
  --output ./types/github.ts \
247
  --immutable \
248
  --alphabetize
249

250
# Process with additional validation
251
openapi-typescript https://petstore.swagger.io/v2/swagger.json \
252
  --output ./types/petstore.ts \
253
  --check \
254
  --enum \
255
  --path-params-as-types
256
```
257

258
### Exit Codes and Error Handling
259

260
The CLI provides meaningful exit codes for integration with build systems and CI/CD pipelines.
261

262
**Exit Codes:**
263

264
- `0` - Success
265
- `1` - General error (invalid schema, file not found, etc.)
266
- `2` - Validation error (when using `--check`)
267
- `3` - Network error (for remote URLs)
268

269
**Error Examples:**
270

271
```bash
272
# Schema validation failure
273
$ openapi-typescript ./invalid-schema.yaml
274
Error: Schema validation failed: ...
275
$ echo $?
276
1
277

278
# Check mode with outdated types
279
$ openapi-typescript ./api.yaml --check --output ./types.ts
280
Error: Generated types are out of date
281
$ echo $?
282
2
283

284
# Network error
285
$ openapi-typescript https://invalid-url.com/schema.json
286
Error: Failed to fetch schema from URL
287
$ echo $?
288
3
289
```
290

291
### Integration Examples
292

293
Common patterns for integrating with build tools and development workflows.
294

295
**package.json scripts:**
296

297
```json
298
{
299
  "scripts": {
300
    "types:generate": "openapi-typescript ./api/schema.yaml -o ./src/types/api.ts",
301
    "types:check": "openapi-typescript ./api/schema.yaml --check -o ./src/types/api.ts",
302
    "types:watch": "nodemon --watch api/ --exec npm run types:generate",
303
    "prebuild": "npm run types:check"
304
  }
305
}
306
```
307

308
**GitHub Actions workflow:**
309

310
```yaml
311
name: Generate Types
312
on: [push, pull_request]
313
jobs:
314
  types:
315
    runs-on: ubuntu-latest
316
    steps:
317
      - uses: actions/checkout@v3
318
      - uses: actions/setup-node@v3
319
        with:
320
          node-version: '18'
321
      - run: npm ci
322
      - run: openapi-typescript ./api/schema.yaml --check -o ./src/types/api.ts
323
```
324

325
**Makefile integration:**
326

327
```makefile
328
.PHONY: types-generate types-check
329

330
types-generate:
331
	openapi-typescript ./api/schema.yaml -o ./src/types/api.ts --export-type --immutable
332

333
types-check:
334
	openapi-typescript ./api/schema.yaml --check -o ./src/types/api.ts
335

336
build: types-check
337
	npm run build
338
```