0
# CLI Usage
1

2
Command-line interface with comprehensive options for batch processing, automation, and integration into build pipelines.
3

4
## Capabilities
5

6
### Basic CLI Usage
7

8
Run the schema generator directly with npx or as an installed binary.
9

10
```bash
11
# Run with npx (no installation required)
12
npx ts-json-schema-generator --path 'src/**/*.ts' --type 'MyType'
13

14
# Install and run locally
15
npm install ts-json-schema-generator
16
./node_modules/.bin/ts-json-schema-generator --path 'src/**/*.ts' --type 'MyType'
17

18
# Global installation
19
npm install -g ts-json-schema-generator
20
ts-json-schema-generator --path 'src/**/*.ts' --type 'MyType'
21
```
22

23
### Core CLI Options
24

25
Essential options for specifying input sources and target types.
26

27
```bash
28
# Required options
29
-p, --path <path>      # Source file path or glob pattern
30
-t, --type <name>      # Type name to generate schema for
31

32
# Configuration options  
33
-f, --tsconfig <path>  # Custom tsconfig.json path
34
-i, --id <name>        # $id for generated schema
35
-o, --out <file>       # Output file (default: stdout)
36
```
37

38
**Basic Examples:**
39

40
```bash
41
# Generate schema for specific type
42
ts-json-schema-generator --path 'src/api.ts' --type 'ApiResponse'
43

44
# Generate schemas for all exported types
45
ts-json-schema-generator --path 'src/**/*.ts' --type '*'
46

47
# Use custom tsconfig and output to file
48
ts-json-schema-generator \
49
  --path 'src/**/*.ts' \
50
  --type 'User' \
51
  --tsconfig './tsconfig.schema.json' \
52
  --out 'schemas/user.json'
53

54
# Add schema ID
55
ts-json-schema-generator \
56
  --path 'src/types.ts' \
57
  --type 'Product' \
58
  --id 'https://example.com/schemas/product'
59
```
60

61
### Type Exposure Options
62

63
Control which types are included in the generated schema.
64

65
```bash
66
-e, --expose <expose>  # Type exposing (choices: "all", "none", "export", default: "export")
67
```
68

69
**Exposure Examples:**
70

71
```bash
72
# Only exported types (default)
73
ts-json-schema-generator --path 'src/**/*.ts' --type '*' --expose export
74

75
# All types including internal ones
76
ts-json-schema-generator --path 'src/**/*.ts' --type '*' --expose all
77

78
# No type definitions in schema
79
ts-json-schema-generator --path 'src/api.ts' --type 'Response' --expose none
80
```
81

82
### JSDoc Processing Options
83

84
Configure how JSDoc annotations are processed and included in schemas.
85

86
```bash
87
-j, --jsDoc <extended>        # Read JsDoc annotations (choices: "none", "basic", "extended", default: "extended")
88
--markdown-description        # Generate `markdownDescription` in addition to `description`
89
```
90

91
**JSDoc Examples:**
92

93
```bash
94
# Full JSDoc processing (default)
95
ts-json-schema-generator --path 'src/api.ts' --type 'User' --jsDoc extended
96

97
# Basic JSDoc only
98
ts-json-schema-generator --path 'src/api.ts' --type 'User' --jsDoc basic
99

100
# No JSDoc processing
101
ts-json-schema-generator --path 'src/api.ts' --type 'User' --jsDoc none
102

103
# Include markdown descriptions
104
ts-json-schema-generator \
105
  --path 'src/api.ts' \
106
  --type 'User' \
107
  --jsDoc extended \
108
  --markdown-description
109
```
110

111
### Schema Format Options
112

113
Control the output format and structure of generated schemas.
114

115
```bash
116
--minify                      # Minify generated schema (default: false)
117
--unstable                    # Do not sort properties
118
--strict-tuples               # Do not allow additional items on tuples
119
--no-top-ref                  # Do not create a top-level $ref definition
120
--additional-properties       # Allow additional properties for objects with no index signature (default: false)
121
```
122

123
**Format Examples:**
124

125
```bash
126
# Minified output
127
ts-json-schema-generator --path 'src/api.ts' --type 'User' --minify
128

129
# Unsorted properties (preserve source order)  
130
ts-json-schema-generator --path 'src/api.ts' --type 'User' --unstable
131

132
# Strict tuple handling
133
ts-json-schema-generator --path 'src/types.ts' --type 'Coordinates' --strict-tuples
134

135
# No top-level reference
136
ts-json-schema-generator --path 'src/api.ts' --type 'User' --no-top-ref
137

138
# Allow additional properties
139
ts-json-schema-generator --path 'src/api.ts' --type 'User' --additional-properties
140
```
141

142
### Performance Options
143

144
Options to improve generation speed for large codebases.
145

146
```bash
147
--no-type-check               # Skip type checks to improve performance
148
```
149

150
**Performance Examples:**
151

152
```bash
153
# Fast generation (skip type checking)
154
ts-json-schema-generator \
155
  --path 'src/**/*.ts' \
156
  --type '*' \
157
  --no-type-check
158

159
# Full type safety (default)
160
ts-json-schema-generator \
161
  --path 'src/**/*.ts' \
162
  --type '*'
163
```
164

165
### Advanced Options
166

167
Specialized options for custom schema generation needs.
168

169
```bash
170
--functions <functions>              # How to handle functions (choices: "fail", "comment", "hide", default: "comment")
171
--no-ref-encode                      # Do not encode references
172
--validation-keywords [value]        # Provide additional validation keywords to include (default: [])
173
```
174

175
**Advanced Examples:**
176

177
```bash
178
# Hide function types
179
ts-json-schema-generator --path 'src/api.ts' --type 'Config' --functions hide
180

181
# Fail on function types
182
ts-json-schema-generator --path 'src/api.ts' --type 'Config' --functions fail
183

184
# Don't encode references
185
ts-json-schema-generator --path 'src/api.ts' --type 'User' --no-ref-encode
186

187
# Include custom validation keywords
188
ts-json-schema-generator \
189
  --path 'src/api.ts' \
190
  --type 'User' \
191
  --validation-keywords format \
192
  --validation-keywords pattern
193
```
194

195
### Help and Version
196

197
Get CLI help and version information.
198

199
```bash
200
-V, --version                 # Output the version number
201
-h, --help                    # Display help for command
202
```
203

204
### Complete CLI Examples
205

206
Real-world usage scenarios combining multiple options.
207

208
**API Schema Generation:**
209

210
```bash
211
ts-json-schema-generator \
212
  --path 'src/api/**/*.ts' \
213
  --type '*' \
214
  --tsconfig './tsconfig.json' \
215
  --jsDoc extended \
216
  --markdown-description \
217
  --out 'dist/api-schemas.json' \
218
  --id 'https://api.example.com/schemas' \
219
  --additional-properties \
220
  --validation-keywords format \
221
  --validation-keywords pattern
222
```
223

224
**Fast Development Build:**
225

226
```bash
227
ts-json-schema-generator \
228
  --path 'src/types.ts' \
229
  --type 'UserProfile' \
230
  --no-type-check \
231
  --minify \
232
  --functions hide \
233
  --out 'temp/user-schema.json'
234
```
235

236
**Strict Production Build:**
237

238
```bash
239
ts-json-schema-generator \
240
  --path 'src/**/*.ts' \
241
  --type '*' \
242
  --tsconfig './tsconfig.prod.json' \
243
  --expose export \
244
  --jsDoc extended \
245
  --strict-tuples \
246
  --functions fail \
247
  --out 'dist/schemas/complete.json'
248
```
249

250
### Path Pattern Guidelines
251

252
Best practices for path patterns and file selection.
253

254
```bash
255
# Single file
256
--path 'src/types.ts'
257

258
# All TypeScript files in directory  
259
--path 'src/*.ts'
260

261
# Recursive directory search
262
--path 'src/**/*.ts'
263

264
# Multiple patterns (use multiple --path options or shell expansion)
265
--path 'src/**/*.ts' --path 'lib/**/*.ts'
266

267
# Quote patterns to prevent shell expansion
268
--path 'src/**/*.ts'  # Good
269
--path src/**/*.ts    # Bad - shell will expand before passing to CLI
270
```
271

272
### Output Handling
273

274
Control where generated schemas are written.
275

276
```bash
277
# Write to stdout (default)
278
ts-json-schema-generator --path 'src/api.ts' --type 'User'
279

280
# Write to file
281
ts-json-schema-generator --path 'src/api.ts' --type 'User' --out 'user.schema.json'
282

283
# Create output directories automatically
284
ts-json-schema-generator --path 'src/api.ts' --type 'User' --out 'schemas/api/user.json'
285
```
286

287
### Error Handling
288

289
CLI error handling and exit codes.
290

291
```bash
292
# Exit code 0: Success
293
# Exit code 1: Error (type errors, file not found, etc.)
294

295
# Capture errors in scripts
296
if ! ts-json-schema-generator --path 'src/api.ts' --type 'User'; then
297
  echo "Schema generation failed"
298
  exit 1
299
fi
300
```
301

302
### Integration Examples
303

304
Common integration patterns for build tools and CI/CD.
305

306
**npm scripts:**
307

308
```json
309
{
310
  "scripts": {
311
    "build:schemas": "ts-json-schema-generator --path 'src/**/*.ts' --type '*' --out 'dist/schemas.json'",
312
    "dev:schemas": "ts-json-schema-generator --path 'src/**/*.ts' --type '*' --no-type-check --out 'temp/schemas.json'"
313
  }
314
}
315
```
316

317
**Makefile:**
318

319
```makefile
320
schemas:
321
	ts-json-schema-generator \
322
		--path 'src/**/*.ts' \
323
		--type '*' \
324
		--tsconfig './tsconfig.json' \
325
		--out 'dist/schemas.json'
326

327
.PHONY: schemas
328
```
329

330
**GitHub Actions:**
331

332
```yaml
333
- name: Generate schemas
334
  run: |
335
    npx ts-json-schema-generator \
336
      --path 'src/**/*.ts' \
337
      --type '*' \
338
      --out 'dist/schemas.json'
339
```