0
# CLI Integration
1

2
Command-line interfaces for executing TypeScript files and interactive REPL sessions with comprehensive configuration options and execution modes.
3

4
## Capabilities
5

6
### Main CLI Binary
7

8
Primary command-line interface with full TypeScript execution and REPL support.
9

10
```typescript { .api }
11
// Available as ts-node binary
12
// Executes TypeScript files or starts interactive REPL
13
// Usage: ts-node [options] [script] [arguments]
14
```
15

16
**Usage Examples:**
17

18
```bash
19
# Execute TypeScript file
20
ts-node script.ts
21

22
# Start interactive REPL
23
ts-node
24

25
# Execute with compiler options
26
ts-node --compiler-options '{"strict":true}' script.ts
27

28
# Transpile-only mode for faster execution
29
ts-node --transpile-only script.ts
30

31
# Execute inline TypeScript code
32
ts-node --eval "console.log('Hello, TypeScript!')"
33
```
34

35
### Working Directory CLI
36

37
CLI that changes working directory before execution.
38

39
```typescript { .api }
40
// Available as ts-node-cwd binary
41
// Changes to script directory before execution
42
// Usage: ts-node-cwd [options] <script> [arguments]
43
```
44

45
**Usage Examples:**
46

47
```bash
48
# Execute script from its directory
49
ts-node-cwd /path/to/project/script.ts
50

51
# Useful for scripts that expect to run from their directory
52
ts-node-cwd ../other-project/build-script.ts
53
```
54

55
### ESM CLI
56

57
CLI with native ECMAScript module support.
58

59
```typescript { .api }
60
// Available as ts-node-esm binary  
61
// Enables ESM support automatically
62
// Usage: ts-node-esm [options] [script] [arguments]
63
```
64

65
**Usage Examples:**
66

67
```bash
68
# Execute TypeScript with ESM support
69
ts-node-esm esm-script.ts
70

71
# Start ESM REPL
72
ts-node-esm
73

74
# With experimental specifier resolution
75
ts-node-esm --experimental-specifier-resolution=node script.ts
76
```
77

78
### Script Execution CLI
79

80
Script execution without REPL functionality for production environments.
81

82
```typescript { .api }
83
// Available as ts-node-script binary
84
// Script-only execution, no REPL
85
// Usage: ts-node-script [options] <script> [arguments]
86
```
87

88
**Usage Examples:**
89

90
```bash
91
# Execute script without REPL fallback
92
ts-node-script production-script.ts
93

94
# Faster startup for scripts that don't need REPL
95
ts-node-script --transpile-only batch-processor.ts
96
```
97

98
### Transpile-Only CLI
99

100
Fast transpile-only CLI that skips type checking for maximum performance.
101

102
```typescript { .api }
103
// Available as ts-node-transpile-only binary
104
// Forces transpileOnly: true mode
105
// Usage: ts-node-transpile-only [options] [script] [arguments]
106
```
107

108
**Usage Examples:**
109

110
```bash
111
# Fast execution without type checking
112
ts-node-transpile-only large-script.ts
113

114
# Development mode with fast iteration
115
ts-node-transpile-only dev-server.ts
116
```
117

118
### Legacy Script CLI
119

120
Deprecated alias for ts-node-script.
121

122
```typescript { .api }
123
// Available as ts-script binary (deprecated)
124
// Alias for ts-node-script
125
// Usage: ts-script [options] <script> [arguments]
126
// Note: Use ts-node-script instead
127
```
128

129
**Usage Examples:**
130

131
```bash
132
# Deprecated - use ts-node-script instead
133
ts-script script.ts
134

135
# Recommended replacement
136
ts-node-script script.ts
137
```
138

139
## CLI Options
140

141
### Common CLI Options
142

143
Options available across all CLI binaries.
144

145
```bash
146
# Compilation Options
147
--transpile-only        # Skip type checking (faster)
148
--type-check           # Force type checking
149
--compiler-host        # Use compiler host API
150
--files                # Load files from tsconfig.json
151

152
# Project Options  
153
--project <path>       # Path to tsconfig.json
154
--skip-project         # Skip project config resolution
155
--cwd <path>           # Working directory
156

157
# Compiler Options
158
--compiler <name>      # TypeScript compiler package
159
--compiler-options <json>  # JSON compiler options
160
--transpiler <name>    # Alternative transpiler
161

162
# SWC Integration
163
--swc                  # Use SWC transpiler
164

165
# Output Options
166
--pretty               # Pretty diagnostic formatter
167
--emit                 # Emit compiled files
168
--log-error           # Log errors to stderr
169

170
# Ignore Options
171
--ignore <pattern>     # Ignore file patterns  
172
--skip-ignore         # Skip ignore patterns
173
--ignore-diagnostics <codes>  # Ignore diagnostic codes
174

175
# ESM Options (ts-node-esm)
176
--experimental-specifier-resolution <mode>  # 'node' or 'explicit'
177
--experimental-ts-import-specifiers         # Allow .ts in imports
178

179
# Execution Options
180
--eval <code>         # Execute inline code
181
--print <code>        # Execute and print result
182
--require <module>    # Require modules before execution
183

184
# REPL Options  
185
--interactive         # Force interactive mode
186
--experimental-repl-await  # Enable top-level await in REPL
187

188
# Debug Options
189
--show-config         # Show resolved configuration
190
--help                # Show help message
191
--version             # Show version information
192
```
193

194
### CLI Configuration Examples
195

196
```bash
197
# Development setup with fast compilation
198
ts-node --transpile-only \
199
        --compiler-options '{"target":"ES2020","strict":false}' \
200
        --ignore 'node_modules' \
201
        src/dev-server.ts
202

203
# Production-like setup with full type checking
204
ts-node --type-check \
205
        --pretty \
206
        --files \
207
        --project tsconfig.prod.json \
208
        src/app.ts
209

210
# ESM project with path mapping
211
ts-node-esm --experimental-specifier-resolution=node \
212
            --compiler-options '{"baseUrl":".","paths":{"@/*":["src/*"]}}' \
213
            src/index.ts
214

215
# Debug mode with comprehensive output
216
ts-node --show-config \
217
        --log-error \
218
        --pretty \
219
        --compiler-options '{"traceResolution":true}' \
220
        debug-script.ts
221
```
222

223
## CLI Integration Patterns
224

225
### NPM Scripts Integration
226

227
```json
228
{
229
  "scripts": {
230
    "start": "ts-node src/index.ts",
231
    "start:fast": "ts-node-transpile-only src/index.ts", 
232
    "start:esm": "ts-node-esm src/index.ts",
233
    "dev": "ts-node --transpile-only --watch src/dev-server.ts",
234
    "build": "ts-node build-script.ts",
235
    "test": "ts-node --transpile-only test/runner.ts",
236
    "repl": "ts-node",
237
    "debug": "ts-node --show-config --log-error src/index.ts"
238
  }
239
}
240
```
241

242
### Environment-Based CLI Usage
243

244
```bash
245
#!/bin/bash
246
# start.sh - Environment-aware startup script
247

248
if [ "$NODE_ENV" = "development" ]; then
249
    exec ts-node-transpile-only src/index.ts
250
elif [ "$NODE_ENV" = "production" ]; then  
251
    exec ts-node --type-check --files src/index.ts
252
else
253
    exec ts-node src/index.ts
254
fi
255
```
256

257
### Docker Integration
258

259
```dockerfile
260
FROM node:18-alpine
261

262
WORKDIR /app
263
COPY package*.json ./
264
RUN npm ci
265

266
COPY . .
267

268
# Use appropriate CLI for container environment
269
CMD ["ts-node-script", "--transpile-only", "src/index.ts"]
270
```
271

272
### Process Manager Integration
273

274
```json
275
{
276
  "apps": [{
277
    "name": "my-app",
278
    "script": "ts-node-script",
279
    "args": ["--transpile-only", "src/index.ts"],
280
    "watch": ["src"],
281
    "ignore_watch": ["node_modules", "logs"],
282
    "env": {
283
      "NODE_ENV": "development"
284
    }
285
  }]
286
}
287
```
288

289
## Advanced CLI Usage
290

291
### CLI API Integration
292

293
```typescript
294
// Custom CLI wrapper
295
import { main, BootstrapState } from "ts-node/dist/bin";
296

297
const customBootstrap: BootstrapState = {
298
  parseArgvResult: {
299
    // Custom argument parsing
300
  },
301
  phase2Result: {
302
    // Custom phase 2 configuration
303
  }
304
};
305

306
// Start custom CLI
307
main(['--transpile-only', 'script.ts'], customBootstrap);
308
```
309

310
### Conditional CLI Execution
311

312
```javascript
313
// conditional-cli.js
314
const { spawn } = require('child_process');
315
const fs = require('fs');
316

317
// Choose CLI based on project structure
318
const hasTsConfig = fs.existsSync('tsconfig.json');
319
const packageJson = JSON.parse(fs.readFileSync('package.json', 'utf8'));
320
const isESM = packageJson.type === 'module';
321

322
let command = 'ts-node';
323
let args = [];
324

325
if (isESM) {
326
  command = 'ts-node-esm';
327
  args.push('--experimental-specifier-resolution=node');
328
}
329

330
if (!hasTsConfig) {
331
  args.push('--transpile-only');
332
}
333

334
args.push('src/index.ts');
335

336
spawn(command, args, { stdio: 'inherit' });
337
```
338

339
### CLI with Custom TypeScript Compiler
340

341
```bash
342
# Use specific TypeScript version
343
ts-node --compiler typescript@4.9.5 script.ts
344

345
# Use fork of TypeScript compiler
346
ts-node --compiler @my-org/typescript script.ts
347

348
# Use nightly TypeScript build
349
ts-node --compiler typescript@next script.ts
350
```
351

352
### Performance Monitoring
353

354
```bash
355
# Monitor CLI performance
356
time ts-node --show-config script.ts
357

358
# Memory usage monitoring
359
node --max-old-space-size=4096 ts-node script.ts
360

361
# CPU profiling
362
node --prof ts-node script.ts
363
node --prof-process isolate-*.log > profile.txt
364
```
365

366
### CLI Error Handling
367

368
```bash
369
# Graceful error handling in scripts
370
set -e  # Exit on error
371

372
# Capture ts-node errors
373
if ! ts-node script.ts 2>errors.log; then
374
    echo "TypeScript compilation failed:"
375
    cat errors.log
376
    exit 1
377
fi
378

379
# Ignore specific diagnostic codes
380
ts-node --ignore-diagnostics 2307,2345 script.ts
381
```