0
# CLI Usage
1
2
tsx provides a powerful command-line interface for executing TypeScript files directly without compilation, with support for watch mode, REPL, and various execution options.
3
4
## Capabilities
5
6
### Direct Execution
7
8
Execute TypeScript files directly from the command line.
9
10
```bash { .api }
11
tsx [options] <script> [script-args...]
12
```
13
14
**Options:**
15
- `--no-cache`: Disable transformation caching
16
- `--tsconfig <path>`: Custom tsconfig.json path
17
- `--input-type <type>`: Specify input type for evaluation
18
- `--test`: Run Node.js built-in test runner
19
- `--version, -v`: Show version
20
- `--help, -h`: Show help
21
22
**Usage Examples:**
23
24
```bash
25
# Run a TypeScript file
26
tsx server.ts
27
28
# Run with custom tsconfig
29
tsx --tsconfig ./custom-tsconfig.json app.ts
30
31
# Run with arguments passed to script
32
tsx script.ts --arg1 value1 --arg2 value2
33
34
# Disable caching
35
tsx --no-cache slow-script.ts
36
```
37
38
### Watch Mode
39
40
Monitor files for changes and automatically restart execution.
41
42
```bash { .api }
43
tsx watch [options] <script> [script-args...]
44
```
45
46
**Additional Watch Options:**
47
- `--clear-screen`: Clear screen on restart (default: true)
48
- `--no-clear-screen`: Disable screen clearing on restart
49
- `--include <patterns>`: Additional paths & globs to watch
50
- `--exclude <patterns>`: Paths & globs to exclude from watching
51
- `--ignore <patterns>`: Paths & globs to exclude from being watched (deprecated: use --exclude)
52
53
**Usage Examples:**
54
55
```bash
56
# Basic watch mode
57
tsx watch server.ts
58
59
# Watch with specific include/exclude patterns
60
tsx watch --include "src/**/*.ts" --exclude "**/*.test.ts" app.ts
61
62
# Disable screen clearing
63
tsx watch --no-clear-screen server.ts
64
```
65
66
### Evaluation Mode
67
68
Execute TypeScript code directly from command line.
69
70
```bash { .api }
71
tsx -e <code>
72
tsx --eval <code>
73
tsx -p <code>
74
tsx --print <code>
75
```
76
77
**Usage Examples:**
78
79
```bash
80
# Execute TypeScript code
81
tsx -e "console.log('Hello from TypeScript!')"
82
83
# Print expression result
84
tsx -p "Math.PI * 2"
85
86
# Execute with imports
87
tsx -e "import fs from 'fs'; console.log(fs.readdirSync('.'))"
88
```
89
90
### REPL Mode
91
92
Interactive TypeScript REPL with enhanced features.
93
94
```bash { .api }
95
tsx
96
```
97
98
The REPL provides:
99
- TypeScript syntax support
100
- Import statement support
101
- Automatic transformation
102
- Standard Node.js REPL features
103
104
**Usage Examples:**
105
106
```bash
107
# Start REPL
108
tsx
109
110
# In REPL:
111
> const name: string = "tsx"
112
> console.log(`Hello ${name}!`)
113
> import fs from 'fs'
114
> fs.readdirSync('.')
115
```
116
117
### Test Runner Integration
118
119
Integration with Node.js built-in test runner for executing TypeScript test files.
120
121
```bash { .api }
122
tsx --test [test-patterns...]
123
```
124
125
**Features:**
126
- Automatically discovers and runs TypeScript test files
127
- Supports Node.js built-in test runner patterns and options
128
- Works with `.test.ts`, `.test.js`, and other test file patterns
129
- Can be combined with other tsx options like `--no-cache` and `--tsconfig`
130
131
**Usage Examples:**
132
133
```bash
134
# Run all TypeScript test files
135
tsx --test
136
137
# Run specific test patterns
138
tsx --test "**/*.test.ts"
139
140
# Run tests with custom tsconfig
141
tsx --test --tsconfig ./test-tsconfig.json
142
143
# Run tests with caching disabled
144
tsx --test --no-cache
145
146
# Run tests with watch mode
147
tsx watch --test
148
149
# Run tests from specific directory
150
tsx --test "./tests/**/*.test.ts"
151
```
152
153
### Environment Variables
154
155
Control tsx behavior through environment variables.
156
157
```bash { .api }
158
TSX_DISABLE_CACHE=1 # Disable transformation caching
159
TSX_TSCONFIG_PATH=path # Custom tsconfig.json path
160
```
161
162
**Usage Examples:**
163
164
```bash
165
# Run with caching disabled
166
TSX_DISABLE_CACHE=1 tsx script.ts
167
168
# Use custom tsconfig via environment
169
TSX_TSCONFIG_PATH=./my-config.json tsx app.ts
170
```
171
172
### Signal Handling
173
174
tsx properly handles process signals and forwards them to child processes.
175
176
**Supported Signals:**
177
- `SIGINT` (Ctrl+C): Graceful shutdown
178
- `SIGTERM`: Termination request
179
- Process exit codes are preserved from child processes
180
181
### Node.js Integration
182
183
tsx seamlessly integrates with Node.js features:
184
185
- **IPC Support**: Maintains IPC channels when spawned from Node.js processes
186
- **Process Arguments**: Preserves all Node.js arguments and flags
187
- **Module Resolution**: Works with Node.js module resolution algorithms
188
- **Source Maps**: Integrates with Node.js source map support
189
190
**Usage with Node.js flags:**
191
192
```bash
193
# Use Node.js flags with tsx
194
node --inspect tsx script.ts
195
node --experimental-modules tsx app.ts
196
```