0
# Command Line Interface
1

2
Node-RED's command-line interface provides tools for running the server, managing node modules, and administrative tasks. The CLI supports both server execution and administrative operations.
3

4
## Capabilities
5

6
### Server Execution
7

8
Start Node-RED server with various configuration options.
9

10
```bash { .api }
11
# Basic server startup
12
node-red
13

14
# With specific options  
15
node-red [options]
16
```
17

18
**Command Line Options:**
19

20
```bash { .api }
21
# Server configuration
22
-p, --port PORT         # Port to listen on (default: 1880)
23
-s, --settings FILE     # Settings file to use (default: ~/.node-red/settings.js)
24
--title TITLE          # Process window title (default: node-red)
25
-u, --userDir DIR      # User directory (default: ~/.node-red)
26

27
# Operation modes
28
-v, --verbose          # Enable verbose output
29
--safe                 # Enable safe mode (starts without flows)
30

31
# Configuration overrides  
32
-D, --define X=Y       # Override settings values dynamically
33

34
# Information
35
--version              # Show version information
36
--help                 # Show help information
37

38
# Privacy
39
--no-telemetry         # Disable usage data sharing
40
```
41

42
**Usage Examples:**
43

44
```bash
45
# Start on custom port
46
node-red -p 1881
47

48
# Use custom settings file
49
node-red -s ./my-settings.js
50

51
# Custom user directory
52
node-red -u ./node-red-data
53

54
# Safe mode (no flows loaded)
55
node-red --safe
56

57
# Verbose logging
58
node-red -v
59

60
# Override settings
61
node-red -D uiHost=127.0.0.1 -D httpNodeRoot=/api
62

63
# Show version
64
node-red --version
65
```
66

67
### Administrative Commands
68

69
Administrative operations using the `admin` command interface.
70

71
```bash { .api }
72
# Admin command syntax
73
node-red admin <command> [options]
74
```
75

76
#### Node Module Management
77

78
```bash { .api }
79
# Install node module
80
node-red admin install <module>[@version]
81

82
# Remove node module  
83
node-red admin remove <module>
84

85
# Enable node module
86
node-red admin enable <module>
87

88
# Disable node module
89
node-red admin disable <module>
90

91
# List installed modules
92
node-red admin list [filter]
93

94
# Search for modules
95
node-red admin search <term>
96

97
# Show module information
98
node-red admin info <module>
99
```
100

101
**Usage Examples:**
102

103
```bash
104
# Install specific node module
105
node-red admin install node-red-contrib-influxdb
106

107
# Install specific version
108
node-red admin install node-red-contrib-postgres@0.6.1
109

110
# Remove module
111
node-red admin remove node-red-contrib-influxdb
112

113
# List all installed modules
114
node-red admin list
115

116
# List core modules only
117
node-red admin list core
118

119
# Search for MQTT nodes
120
node-red admin search mqtt
121

122
# Get module information
123
node-red admin info node-red-contrib-influxdb
124
```
125

126
#### User Management
127

128
```bash { .api }
129
# Initialize user directory
130
node-red admin init
131

132
# Generate password hash  
133
node-red admin hash-pw [password]
134
```
135

136
**Usage Examples:**
137

138
```bash
139
# Initialize new user directory with prompts
140
node-red admin init
141

142
# Generate password hash for settings.js
143
node-red admin hash-pw
144
# Enter password when prompted
145

146
# Generate hash for specific password
147
echo "mypassword" | node-red admin hash-pw
148
```
149

150
### Process Management
151

152
Node-RED can be managed as a system service or run in various modes.
153

154
```bash { .api }
155
# Run as daemon (background process)
156
nohup node-red > node-red.log 2>&1 &
157

158
# Run with process manager
159
pm2 start node-red
160
pm2 start node-red --name "my-node-red"
161

162
# Docker execution
163
docker run -p 1880:1880 nodered/node-red
164

165
# systemd service (example unit file)
166
[Unit]
167
Description=Node-RED
168
After=syslog.target network.target
169

170
[Service]
171
ExecStart=/usr/bin/node-red --userDir /opt/node-red/.node-red
172
Restart=on-failure
173
KillSignal=SIGINT
174
User=nodered
175
Group=nodered
176

177
[Install]
178
WantedBy=multi-user.target
179
```
180

181
### Environment Variables
182

183
Environment variables that affect Node-RED behavior.
184

185
```bash { .api }
186
# Node-RED specific variables
187
NODE_RED_HOME          # Override home directory detection
188
NODE_RED_OPTIONS       # Additional command line options
189

190
# Node.js variables  
191
NODE_ENV               # Environment mode (development, production)
192
NODE_OPTIONS           # Node.js runtime options
193
NODE_PATH              # Additional module search paths
194

195
# System variables
196
HOME                   # User home directory (affects default userDir)
197
PORT                   # Port override (for cloud deployments)
198
```
199

200
**Usage Examples:**
201

202
```bash
203
# Set environment mode
204
NODE_ENV=production node-red
205

206
# Increase Node.js memory limit
207
NODE_OPTIONS="--max-old-space-size=4096" node-red
208

209
# Custom home directory
210
NODE_RED_HOME=/opt/node-red node-red
211

212
# Cloud deployment with PORT override
213
PORT=8080 node-red
214
```
215

216
### Configuration Files
217

218
Location and structure of Node-RED configuration files.
219

220
#### Settings File Location
221

222
```bash { .api }
223
# Default locations (in order of precedence)
224
./settings.js           # Current directory
225
~/.node-red/settings.js # User directory  
226
/usr/local/lib/node_modules/node-red/settings.js # Global installation
227
```
228

229
#### User Directory Structure
230

231
```bash { .api }
232
~/.node-red/           # Default user directory
233
├── settings.js        # Main configuration file
234
├── flows.json         # Flow definitions  
235
├── flows_cred.json    # Encrypted credentials
236
├── .sessions.json     # Editor sessions
237
├── .config.json       # Editor configuration
238
├── lib/              # Custom modules directory
239
├── node_modules/     # Installed node modules
240
└── projects/         # Git projects (if enabled)
241
```
242

243
### Logging and Debugging
244

245
Command-line options and techniques for debugging Node-RED.
246

247
```bash { .api }
248
# Enable debug logging
249
DEBUG=red:* node-red
250

251
# Specific debug categories
252
DEBUG=red:runtime:* node-red
253
DEBUG=red:comms,red:api node-red
254

255
# Verbose output
256
node-red -v
257

258
# Safe mode for troubleshooting
259
node-red --safe
260

261
# Custom log level in settings
262
node-red -D logging.console.level=debug
263
```
264

265
**Debug Categories:**
266

267
- `red:*` - All Node-RED debug output
268
- `red:runtime:*` - Runtime system debugging
269
- `red:comms` - WebSocket communication
270
- `red:api` - HTTP API calls
271
- `red:registry` - Node registry operations
272
- `red:storage` - Storage operations
273

274
### Integration Examples
275

276
Common patterns for integrating Node-RED CLI in deployment scenarios.
277

278
#### Docker Deployment
279

280
```dockerfile
281
FROM nodered/node-red:latest
282

283
# Copy custom settings
284
COPY settings.js /data/settings.js
285

286
# Install additional nodes
287
RUN npm install node-red-contrib-influxdb
288

289
# Expose port
290
EXPOSE 1880
291

292
# Start Node-RED
293
CMD ["node-red", "--userDir", "/data"]
294
```
295

296
#### Kubernetes Deployment
297

298
```yaml
299
apiVersion: apps/v1
300
kind: Deployment
301
metadata:
302
  name: node-red
303
spec:
304
  replicas: 1
305
  selector:
306
    matchLabels:
307
      app: node-red
308
  template:
309
    metadata:
310
      labels:
311
        app: node-red
312
    spec:
313
      containers:
314
      - name: node-red
315
        image: nodered/node-red:latest
316
        ports:
317
        - containerPort: 1880
318
        env:
319
        - name: NODE_ENV
320
          value: "production"
321
        command: ["node-red"]
322
        args: ["--userDir", "/data", "--verbose"]
323
        volumeMounts:
324
        - name: node-red-data
325
          mountPath: /data
326
```
327

328
#### Startup Scripts
329

330
```bash
331
#!/bin/bash
332
# node-red-startup.sh
333

334
export NODE_ENV=production
335
export NODE_OPTIONS="--max-old-space-size=2048"
336

337
# Start Node-RED with custom configuration
338
node-red \
339
  --userDir /opt/node-red/data \
340
  --settings /opt/node-red/config/settings.js \
341
  --port 1880 \
342
  --verbose \
343
  > /var/log/node-red.log 2>&1 &
344

345
echo $! > /var/run/node-red.pid
346
echo "Node-RED started with PID $(cat /var/run/node-red.pid)"
347
```
348

349
## Exit Codes
350

351
Node-RED CLI exit codes and their meanings.
352

353
```bash { .api }
354
0    # Success
355
1    # General error
356
2    # Invalid arguments  
357
3    # Node.js version incompatible
358
130  # Interrupted (Ctrl+C)
359
```
360

361
## Troubleshooting
362

363
Common CLI issues and solutions.
364

365
### Permission Issues
366

367
```bash
368
# Fix npm permissions for global install
369
sudo chown -R $(whoami) ~/.npm
370
sudo chown -R $(whoami) /usr/local/lib/node_modules
371

372
# Or use n or nvm for Node.js management
373
```
374

375
### Port Already in Use
376

377
```bash
378
# Find process using port 1880
379
lsof -i :1880
380
netstat -tulpn | grep :1880
381

382
# Use different port
383
node-red -p 1881
384
```
385

386
### Module Installation Issues
387

388
```bash
389
# Clear npm cache
390
npm cache clean --force
391

392
# Rebuild native modules
393
npm rebuild
394

395
# Install with specific registry
396
node-red admin install --registry=https://registry.npmjs.org/ <module>
397
```