0
# CLI Interface
1

2
Command-line interface for testing entire projects with file discovery and configuration support. The CLI provides an easy way to run type definition tests from the command line or in CI/CD pipelines.
3

4
## Capabilities
5

6
### Basic Command
7

8
```bash
9
tsd [path] [--typings file] [--files pattern] [--show-diff] [--help] [--version]
10
```
11

12
The CLI searches for a `package.json` file in the current or specified directory, finds type definition files, locates test files, and runs them through the TypeScript compiler for static analysis.
13

14
### Command Options
15

16
#### --typings, -t
17

18
Specify the type definition file to test.
19

20
```bash
21
# Test specific typings file
22
tsd --typings dist/api.d.ts
23

24
# Short form
25
tsd -t dist/api.d.ts
26
```
27

28
**Default behavior:** Uses the `types` property from `package.json`, or falls back to `index.d.ts`.
29

30
#### --files, -f
31

32
Specify test files with glob patterns. Can be used multiple times.
33

34
```bash
35
# Single pattern
36
tsd --files "test-d/**/*.ts"
37

38
# Multiple patterns
39
tsd --files "test-d/**/*.ts" --files "src/**/*.test-d.tsx"
40

41
# Short form
42
tsd -f "**/*.test-d.ts"
43
```
44

45
**Default behavior:** Searches for `*.test-d.ts` and `*.test-d.tsx` files in the project root or `test-d` directory.
46

47
#### --show-diff
48

49
Display type error differences between expected and received types.
50

51
```bash
52
tsd --show-diff
53
```
54

55
This shows detailed diff output when type assertions fail, making it easier to understand type mismatches.
56

57
#### --help
58

59
Display help information.
60

61
```bash
62
tsd --help
63
```
64

65
#### --version
66

67
Display version information.
68

69
```bash
70
tsd --version
71
```
72

73
## Usage Examples
74

75
### Basic Usage
76

77
```bash
78
# Test current directory
79
tsd
80

81
# Test specific directory  
82
tsd /path/to/my-project
83

84
# Test with verbose diff output
85
tsd --show-diff
86
```
87

88
### Custom File Patterns
89

90
```bash
91
# Test specific typings file
92
tsd --typings lib/index.d.ts
93

94
# Test files in multiple directories
95
tsd --files "types/**/*.test-d.ts" --files "src/**/*.test-d.ts"
96

97
# Test TypeScript JSX files
98
tsd --files "**/*.test-d.tsx"
99
```
100

101
### Integration Examples
102

103
#### NPM Scripts
104

105
```json
106
{
107
  "scripts": {
108
    "test:types": "tsd",
109
    "test:types:diff": "tsd --show-diff",
110
    "test:api-types": "tsd --typings dist/api.d.ts --files api-tests/*.test-d.ts"
111
  }
112
}
113
```
114

115
#### CI/CD Pipeline
116

117
```yaml
118
# GitHub Actions
119
- name: Test Type Definitions
120
  run: npm run test:types
121

122
# Or directly
123
- name: Test Type Definitions
124
  run: npx tsd
125
```
126

127
#### Makefile
128

129
```makefile
130
.PHONY: test-types
131
test-types:
132
	npx tsd --show-diff
133

134
.PHONY: test-api-types
135
test-api-types:
136
	npx tsd --typings dist/api.d.ts --files "api-tests/**/*.test-d.ts"
137
```
138

139
## File Discovery Process
140

141
The CLI follows a specific order of operations:
142

143
### 1. Package.json Location
144

145
```bash
146
# Locates package.json in current or specified directory
147
tsd /path/to/project  # Looks for /path/to/project/package.json
148
tsd                   # Looks for ./package.json
149
```
150

151
**Error if not found:** `No package.json file found in <path>. Make sure you are running the command in a Node.js project.`
152

153
### 2. Type Definition File Discovery
154

155
```bash
156
# Priority order:
157
# 1. --typings flag value
158
# 2. "types" field in package.json
159
# 3. "typings" field in package.json  
160
# 4. Same name as "main" field with .d.ts extension
161
# 5. index.d.ts
162
```
163

164
**Example package.json:**
165
```json
166
{
167
  "name": "my-package",
168
  "main": "dist/index.js",
169
  "types": "dist/index.d.ts"
170
}
171
```
172

173
### 3. Test File Discovery
174

175
```bash
176
# Without --files flag, searches for:
177
# 1. <typings-file-name>.test-d.ts
178
# 2. <typings-file-name>.test-d.tsx
179
# 3. Files in test directory (default: test-d/)
180

181
# Example: if typings file is "dist/api.d.ts"
182
# Looks for: api.test-d.ts, api.test-d.tsx, test-d/**/*.ts, test-d/**/*.tsx
183
```
184

185
### 4. Test Directory Configuration
186

187
```json
188
{
189
  "name": "my-package",
190
  "tsd": {
191
    "directory": "type-tests"
192
  }
193
}
194
```
195

196
```bash
197
# Uses custom directory instead of default "test-d"
198
tsd  # Will look in type-tests/ directory
199
```
200

201
## Output Format
202

203
### Success Output
204

205
```bash
206
$ tsd
207
# No output when all tests pass (exit code 0)
208
```
209

210
### Error Output
211

212
```bash
213
$ tsd
214

215
    index.test-d.ts
216
    ✖  10:20  Argument of type 'string' is not assignable to parameter of type 'number'.
217

218
$ echo $?
219
1
220
```
221

222
### With --show-diff
223

224
```bash
225
$ tsd --show-diff
226

227
    index.test-d.ts
228
    ✖  10:20  Argument of type 'string' is not assignable to parameter of type 'number'.
229

230
    - Expected
231
    + Received
232

233
    - number
234
    + string
235
```
236

237
### Multiple Files
238

239
```bash
240
$ tsd
241

242
    api.test-d.ts
243
    ✖  5:15   Property 'foo' does not exist on type 'ApiResponse'.
244
    
245
    utils.test-d.ts
246
    ⚠  12:8   Type 'deprecated' is deprecated.
247
    ✖  15:10  Expected 2 arguments, but got 3.
248
```
249

250
## Exit Codes
251

252
- **0**: All tests passed (no errors)
253
- **1**: Type errors found or CLI error occurred
254

255
**Note:** Warnings do not cause non-zero exit codes.
256

257
## Configuration
258

259
### TypeScript Compiler Options
260

261
Default configuration applied by TSD:
262

263
```json
264
{
265
  "strict": true,
266
  "jsx": "react",
267
  "target": "es2020",
268
  "lib": ["es2020", "dom", "dom.iterable"],
269
  "module": "commonjs",
270
  "esModuleInterop": true,
271
  "noUnusedLocals": false,
272
  "moduleResolution": "node",
273
  "skipLibCheck": false
274
}
275
```
276

277
### Custom Configuration via package.json
278

279
```json
280
{
281
  "name": "my-package",
282
  "tsd": {
283
    "directory": "my-test-dir",
284
    "compilerOptions": {
285
      "strict": false,
286
      "target": "es2015"
287
    }
288
  }
289
}
290
```
291

292
### TypeScript Config File
293

294
TSD respects `tsconfig.json` in the project root:
295

296
```json
297
{
298
  "compilerOptions": {
299
    "strict": true,
300
    "exactOptionalPropertyTypes": true
301
  }
302
}
303
```
304

305
**Note:** `moduleResolution` and `skipLibCheck` options cannot be overridden.
306

307
## Error Scenarios
308

309
### Common Error Messages
310

311
```bash
312
# Missing package.json
313
$ tsd /invalid/path
314
Error: No `package.json` file found in `/invalid/path`. Make sure you are running the command in a Node.js project.
315

316
# Missing type definition file
317
$ tsd --typings missing.d.ts
318
Error: The type definition `missing.d.ts` does not exist at `/current/path/missing.d.ts`. Is the path correct? Create one and try again.
319

320
# No test files found
321
$ tsd
322
Error: The test file `index.test-d.ts` or `index.test-d.tsx` does not exist in `/current/path`. Create one and try again.
323

324
# No test files matching pattern
325
$ tsd --files "nonexistent/**/*.ts"
326
Error: Could not find any test files with the given pattern(s). Create one and try again.
327
```
328

329
### Debugging Tips
330

331
```bash
332
# Check what files TSD is finding
333
ls -la *.test-d.ts test-d/
334

335
# Verify package.json configuration
336
cat package.json | grep -A 5 '"tsd"'
337

338
# Check TypeScript configuration
339
cat tsconfig.json
340

341
# Run with explicit paths for debugging
342
tsd --typings dist/index.d.ts --files "test-d/**/*.test-d.ts"
343
```
344

345
## Advanced Usage Patterns
346

347
### Monorepo Testing
348

349
```bash
350
# Test specific package in monorepo
351
tsd packages/api
352
tsd packages/utils --typings dist/index.d.ts
353

354
# Test all packages
355
for pkg in packages/*; do
356
  echo "Testing $pkg"
357
  tsd "$pkg"
358
done
359
```
360

361
### Conditional Testing
362

363
```bash
364
# Only test if type files exist
365
if [ -f "dist/index.d.ts" ]; then
366
  tsd --typings dist/index.d.ts
367
else
368
  echo "No type definitions found, skipping tests"
369
fi
370
```
371

372
### Pre-commit Hooks
373

374
```bash
375
# .git/hooks/pre-commit
376
#!/bin/bash
377
echo "Running type definition tests..."
378
if ! tsd; then
379
  echo "Type tests failed! Commit aborted."
380
  exit 1
381
fi
382
```