0
# CLI Commands
1

2
Selenium Grid provides a comprehensive command-line interface for starting and managing grid components, with built-in help system, configuration support, and extensible command framework.
3

4
## Capabilities
5

6
### Main Entry Point
7

8
The primary entry point for all grid operations via command-line interface.
9

10
```java { .api }
11
/**
12
 * Main class providing CLI entry point for Selenium Grid
13
 */
14
class Main {
15
    /** Main method that processes command-line arguments and executes commands */
16
    public static void main(String[] args);
17
    
18
    /** Internal constructor for testing */
19
    Main(PrintStream out, PrintStream err, String[] args);
20
    
21
    /** Execute the main logic - used internally */
22
    void go();
23
    
24
    /** Load available CLI commands using ServiceLoader */
25
    private static Set<CliCommand> loadCommands(ClassLoader loader);
26
}
27
```
28

29
**Usage Examples:**
30

31
```bash
32
# Start standalone grid (combined hub and node)
33
java -jar selenium-server-4.33.0.jar standalone
34

35
# Start hub component
36
java -jar selenium-server-4.33.0.jar hub
37

38
# Start node and register with hub
39
java -jar selenium-server-4.33.0.jar node --hub http://hub.example.com:4444
40

41
# Get help information
42
java -jar selenium-server-4.33.0.jar info
43

44
# Show version information
45
java -jar selenium-server-4.33.0.jar --version
46

47
# Show help for specific command
48
java -jar selenium-server-4.33.0.jar hub --help
49
```
50

51
### Hub Command
52

53
Starts the hub component that coordinates session distribution and node management.
54

55
```java { .api }
56
/**
57
 * CLI command for starting Selenium Grid hub
58
 */
59
@AutoService(CliCommand.class)
60
class Hub extends TemplateGridServerCommand {
61
    /** Get command name for CLI */
62
    String getName();
63
    
64
    /** Get roles this command configures */
65
    Set<Role> getConfigurableRoles();
66
    
67
    /** Get command-line flag objects */
68
    Set<Object> getFlagObjects();
69
    
70
    /** Get default configuration for this command */
71
    Config getDefaultConfig();
72
    
73
    /** Create HTTP handlers for the hub */
74
    Handlers<Route> createHandlers(Config config);
75
}
76
```
77

78
**Hub Configuration:**
79

80
```bash
81
# Basic hub startup
82
java -jar selenium-server-4.33.0.jar hub
83

84
# Hub with custom configuration
85
java -jar selenium-server-4.33.0.jar hub \
86
  --port 4444 \
87
  --host 0.0.0.0 \
88
  --session-timeout 300 \
89
  --session-request-timeout 300 \
90
  --healthcheck-interval 120
91

92
# Hub with configuration file
93
java -jar selenium-server-4.33.0.jar hub \
94
  --config hub-config.toml
95
```
96

97
### Standalone Command
98

99
Starts a standalone grid that combines hub and node functionality in a single process.
100

101
```java { .api }
102
/**
103
 * CLI command for starting Selenium Grid in standalone mode
104
 */
105
@AutoService(CliCommand.class)  
106
class Standalone extends TemplateGridServerCommand {
107
    String getName();
108
    Set<Role> getConfigurableRoles();
109
    Set<Object> getFlagObjects();
110
    Config getDefaultConfig();
111
    Handlers<Route> createHandlers(Config config);
112
    
113
    /** Additional standalone-specific configuration */
114
    StandaloneConfig getStandaloneConfig();
115
}
116
```
117

118
**Standalone Configuration:**
119

120
```bash
121
# Basic standalone startup (auto-detects browsers)
122
java -jar selenium-server-4.33.0.jar standalone
123

124
# Standalone with specific browsers
125
java -jar selenium-server-4.33.0.jar standalone \
126
  --detect-drivers \
127
  --max-sessions 4
128

129
# Standalone with custom capabilities
130
java -jar selenium-server-4.33.0.jar standalone \
131
  --config standalone-config.toml
132
```
133

134
### Node Command  
135

136
Starts a node component that executes WebDriver sessions and registers with a hub.
137

138
```java { .api }
139
/**
140
 * CLI command for starting Selenium Grid node
141
 */
142
@AutoService(CliCommand.class)
143
class NodeServer extends TemplateGridServerCommand {
144
    String getName();
145
    String getDescription(); 
146
    Set<Role> getConfigurableRoles(); 
147
    Set<Object> getFlagObjects();
148
    Config getDefaultConfig();
149
    Handlers<Route> createHandlers(Config config);
150
}
151
```
152

153
**Node Configuration:**
154

155
```bash
156
# Basic node startup  
157
java -jar selenium-server-4.33.0.jar node \
158
  --hub http://hub.example.com:4444
159

160
# Node with specific configuration
161
java -jar selenium-server-4.33.0.jar node \
162
  --hub http://hub.example.com:4444 \
163
  --port 5555 \
164
  --max-sessions 2 \
165
  --detect-drivers
166

167
# Node with custom capabilities
168
java -jar selenium-server-4.33.0.jar node \
169
  --hub http://hub.example.com:4444 \
170
  --config node-config.toml
171
```
172

173
### Info Command
174

175
Displays system information and grid configuration details.
176

177
```java { .api }
178
/**
179
 * CLI command for displaying grid information
180
 */
181
@AutoService(CliCommand.class)
182
class InfoCommand extends TemplateGridCommand {  
183
    String getName();
184
    Set<Role> getConfigurableRoles();
185
    Set<Object> getFlagObjects();
186
    Config getDefaultConfig();
187
    
188
    /** Configure and return executable for info display */
189
    Executable configure(PrintStream out, PrintStream err, String... args);
190
}
191
```
192

193
**Info Command Usage:**
194

195
```bash
196
# Display system information
197
java -jar selenium-server-4.33.0.jar info
198

199
# Output includes:
200
# - Selenium version
201
# - Java version and vendor
202
# - Operating system details  
203
# - Available WebDriver binaries
204
# - Default configuration values
205
```
206

207
### Event Bus Command
208

209
Starts a standalone event bus server for distributed grid communication.
210

211
```java { .api }
212
/**
213
 * CLI command for starting standalone event bus
214
 */
215
@AutoService(CliCommand.class)
216
class EventBusCommand extends TemplateGridCommand {
217
    String getName();
218
    String getDescription();
219
    Set<Role> getConfigurableRoles();
220
    Set<Object> getFlagObjects();
221
    Config getDefaultConfig();
222
    boolean isShown(); // Returns false - hidden command
223
    
224
    /** Configure and return executable for event bus */
225
    Executable configure(PrintStream out, PrintStream err, String... args);
226
}
227
```
228

229
**Event Bus Configuration:**
230

231
```bash
232
# Start standalone event bus (hidden command)
233
java -jar selenium-server-4.33.0.jar event-bus
234

235
# Event bus with custom ports
236
java -jar selenium-server-4.33.0.jar event-bus \
237
  --port 5557 \
238
  --publish tcp://*:4442 \
239
  --subscribe tcp://*:4443
240
```
241

242
### Completion Command
243

244
Generates shell autocompletion scripts for the selenium CLI.
245

246
```java { .api }
247
/**
248
 * CLI command for generating shell autocompletions
249
 */
250
@AutoService(CliCommand.class)
251
class CompletionCommand implements CliCommand {
252
    String getName();
253
    String getDescription();
254
    Set<Role> getConfigurableRoles();
255
    Set<Object> getFlagObjects();
256
    
257
    /** Configure and return executable for completion generation */
258
    Executable configure(PrintStream out, PrintStream err, String... args);
259
}
260
```
261

262
**Completion Usage:**
263

264
```bash
265
# Generate bash completion script
266
java -jar selenium-server-4.33.0.jar completion bash
267

268
# Generate zsh completion script  
269
java -jar selenium-server-4.33.0.jar completion zsh
270

271
# Generate fish completion script
272
java -jar selenium-server-4.33.0.jar completion fish
273
```
274

275
### Distributor Server Command
276

277
Starts a standalone distributor component for session distribution and node management.
278

279
```java { .api }
280
/**
281
 * CLI command for starting standalone distributor server
282
 */
283
@AutoService(CliCommand.class)
284
class DistributorServer extends TemplateGridServerCommand {
285
    String getName();
286
    String getDescription();
287
    Set<Role> getConfigurableRoles();
288
    Set<Object> getFlagObjects();
289
    Config getDefaultConfig();
290
    Handlers<Route> createHandlers(Config config);
291
}
292
```
293

294
### Router Server Command
295

296
Starts a standalone router component for routing WebDriver requests.
297

298
```java { .api }
299
/**
300
 * CLI command for starting standalone router server
301
 */
302
@AutoService(CliCommand.class)
303
class RouterServer extends TemplateGridServerCommand {
304
    String getName();
305
    String getDescription();
306
    Set<Role> getConfigurableRoles();
307
    Set<Object> getFlagObjects();
308
    Config getDefaultConfig();
309
    Handlers<Route> createHandlers(Config config);
310
}
311
```
312

313
### Session Map Server Command
314

315
Starts a standalone session map server for session tracking.
316

317
```java { .api }
318
/**
319
 * CLI command for starting standalone session map server
320
 */
321
@AutoService(CliCommand.class)
322
class SessionMapServer extends TemplateGridServerCommand {
323
    String getName();
324
    String getDescription();
325
    Set<Role> getConfigurableRoles();
326
    Set<Object> getFlagObjects();
327
    Config getDefaultConfig();
328
    Handlers<Route> createHandlers(Config config);
329
}
330
```
331

332
### Session Queue Server Command
333

334
Starts a standalone session queue server for request queuing.
335

336
```java { .api }
337
/**
338
 * CLI command for starting standalone session queue server
339
 */
340
@AutoService(CliCommand.class)
341
class NewSessionQueueServer extends TemplateGridServerCommand {
342
    String getName();
343
    String getDescription();
344
    Set<Role> getConfigurableRoles();
345
    Set<Object> getFlagObjects();
346
    Config getDefaultConfig();
347
    Handlers<Route> createHandlers(Config config);
348
}
349
```
350

351
### Command Base Classes
352

353
Abstract base classes that provide common functionality for grid commands.
354

355
```java { .api }
356
/**
357
 * Base class for all grid CLI commands
358
 */
359
abstract class TemplateGridCommand implements CliCommand {
360
    /** Get command name for CLI parsing */
361
    abstract String getName();
362
    
363
    /** Get help text for this command */
364
    String getDescription();
365
    
366
    /** Get roles this command can configure */
367
    Set<Role> getConfigurableRoles();
368
    
369
    /** Get command-line flag definition objects */
370
    Set<Object> getFlagObjects();
371
    
372
    /** Get default configuration for this command */  
373
    Config getDefaultConfig();
374
    
375
    /** Configure command with parsed arguments */
376
    Executable configure(PrintStream out, PrintStream err, String... args);
377
    
378
    /** Common configuration processing */
379
    protected Config buildConfig(String... args);
380
}
381

382
/**
383
 * Base class for server-type grid commands (hub, standalone)
384
 */
385
abstract class TemplateGridServerCommand extends TemplateGridCommand {
386
    /** Create HTTP route handlers for this server */
387
    abstract Handlers<Route> createHandlers(Config config);
388
    
389
    /** Start the server with configured handlers */
390
    @Override
391
    Executable configure(PrintStream out, PrintStream err, String... args);
392
    
393
    /** Common server startup logic */
394
    protected Server<?> startServer(Config config, Handlers<Route> handlers);
395
}
396
```
397

398
### Configuration Integration
399

400
Commands integrate with the configuration system for flexible setup.
401

402
```java { .api }
403
/**
404
 * Default configuration providers for each command type
405
 */
406
class DefaultHubConfig implements Config {
407
    // Provides default hub configuration values
408
}
409

410
class DefaultStandaloneConfig implements Config {
411
    // Provides default standalone configuration values  
412
}
413

414
class DefaultNodeConfig implements Config {
415
    // Provides default node configuration values
416
}
417

418
class DefaultDistributorConfig implements Config {
419
    // Provides default distributor configuration values
420
}
421

422
class DefaultSessionMapConfig implements Config {
423
    // Provides default session map configuration values
424
}
425

426
class DefaultRouterConfig implements Config {
427
    // Provides default router configuration values
428
}
429

430
class DefaultNewSessionQueueConfig implements Config {
431
    // Provides default session queue configuration values
432
}
433

434
/**
435
 * Command-line flag definitions
436
 */
437
class StandaloneFlags {
438
    @Parameter(names = {"--port", "-p"}, description = "Port to listen on")
439
    int port = 4444;
440
    
441
    @Parameter(names = {"--host"}, description = "IP or hostname to bind to")
442
    String host = "0.0.0.0";
443
    
444
    @Parameter(names = {"--max-sessions"}, description = "Maximum concurrent sessions")
445
    int maxSessions = Runtime.getRuntime().availableProcessors();
446
    
447
    @Parameter(names = {"--detect-drivers"}, description = "Auto-detect WebDriver executables")
448
    boolean detectDrivers = true;
449
}
450

451
class InfoFlags {
452
    @Parameter(names = {"--config-help"}, description = "Show configuration options")
453
    boolean configHelp = false;
454
}
455
```
456

457
## Command Extension
458

459
### Custom Commands
460

461
```java
462
// Create custom grid commands
463
@AutoService(CliCommand.class)
464
public class CustomGridCommand extends TemplateGridCommand {
465
    
466
    @Override
467
    public String getName() {
468
        return "custom";
469
    }
470
    
471
    @Override
472
    public String getDescription() {
473
        return "Custom grid command for specialized operations";
474
    }
475
    
476
    @Override
477
    public Set<Role> getConfigurableRoles() {
478
        return Set.of(Role.of("custom"));
479
    }
480
    
481
    @Override
482
    public Executable configure(PrintStream out, PrintStream err, String... args) {
483
        Config config = buildConfig(args);
484
        
485
        return () -> {
486
            // Custom command logic
487
            out.println("Executing custom grid command");
488
            performCustomOperation(config);
489
        };
490
    }
491
    
492
    private void performCustomOperation(Config config) {
493
        // Implementation specific to custom command
494
    }
495
}
496
```
497

498
### Plugin System
499

500
```java
501
// Bootstrap support for loading custom commands from JARs
502
public class Bootstrap {
503
    /** Main method that supports loading extension JARs */
504
    public static void main(String[] args);
505
    
506
    /** Load commands from external JAR files */
507
    static Set<CliCommand> loadPluginCommands(Path... jarPaths);
508
    
509
    /** Bootstrap with custom ClassLoader for extensions */
510
    static void bootstrapWithPlugins(String[] args, Path... extensionJars);
511
}
512
```
513

514
**Plugin Usage:**
515

516
```bash
517
# Load custom commands from extension JARs
518
java -cp selenium-server-4.33.0.jar:my-extension.jar \
519
  org.openqa.selenium.grid.Bootstrap custom --option value
520

521
# Extension JARs can contain additional @AutoService(CliCommand.class) implementations
522
```
523

524
## Configuration Files
525

526
### TOML Configuration Example
527

528
```toml
529
# hub-config.toml
530
[server]  
531
port = 4444
532
host = "0.0.0.0"
533
max-threads = 24
534

535
[distributor]
536
healthcheck-interval = "120s"
537
reject-unsupported-caps = true
538

539
[sessionmap]
540
implementation = "org.openqa.selenium.grid.sessionmap.redis.RedisSessionMap"
541

542
[sessionqueue]
543
implementation = "org.openqa.selenium.grid.sessionqueue.local.LocalNewSessionQueue"
544
request-timeout = "300s"
545

546
[events]
547
implementation = "org.openqa.selenium.events.zeromq.ZeroMqEventBus"
548
publish = "tcp://*:4442"
549
subscribe = "tcp://*:4443"
550
```
551

552
### JSON Configuration Example
553

554
```json
555
{
556
  "server": {
557
    "port": 5555,
558
    "host": "0.0.0.0"
559
  },
560
  "node": {
561
    "max-sessions": 2,  
562
    "session-timeout": "300s",
563
    "heartbeat-period": "60s"
564
  },
565
  "docker": {
566
    "images": {
567
      "chrome": "selenium/node-chrome:latest",
568
      "firefox": "selenium/node-firefox:latest"  
569
    }
570
  }
571
}
572
```
573

574
## Help System
575

576
```bash
577
# Global help
578
java -jar selenium-server-4.33.0.jar --help
579

580
# Command-specific help  
581
java -jar selenium-server-4.33.0.jar hub --help
582
java -jar selenium-server-4.33.0.jar node --help
583
java -jar selenium-server-4.33.0.jar standalone --help
584

585
# Configuration help
586
java -jar selenium-server-4.33.0.jar info --config-help
587

588
# Version information
589
java -jar selenium-server-4.33.0.jar --version
590
```
591

592
## Environment Variables
593

594
```bash
595
# Common environment variables used by commands
596
SE_PORT=4444                    # Server port
597
SE_HOST=0.0.0.0                # Server host  
598
SE_MAX_SESSIONS=4              # Maximum concurrent sessions
599
SE_SESSION_TIMEOUT=300         # Session timeout in seconds
600
SE_REGISTRATION_SECRET=secret  # Node registration secret
601
SE_HUB_URL=http://hub:4444     # Hub URL for node registration
602

603
# Configuration file location
604
SE_CONFIG_FILE=/etc/selenium/grid.toml
605

606
# Java system properties can also be used
607
java -Dselenium.grid.port=4444 -jar selenium-server-4.33.0.jar hub
608
```
609

610
## Process Management
611

612
```bash
613
# Start as background daemon
614
nohup java -jar selenium-server-4.33.0.jar hub > hub.log 2>&1 &
615

616
# With systemd service
617
systemctl start selenium-hub
618
systemctl enable selenium-hub
619

620
# Docker deployment
621
docker run -d -p 4444:4444 selenium/hub:4.33.0
622

623
# Docker compose for full grid
624
docker-compose up -d hub chrome firefox
625
```