0
# CLI Commands
1

2
WebdriverIO CLI provides comprehensive command-line interface for test execution, interactive development, project configuration, and plugin management.
3

4
## Capabilities
5

6
### Run Command
7

8
Execute WebdriverIO test suite with extensive configuration options. This is the default command when no explicit command is specified.
9

10
```bash { .api }
11
wdio run <configPath> [options]
12

13
# Options:
14
--watch                     # Run in watch mode for development
15
--hostname, -h <hostname>   # Automation driver host address
16
--port, -p <port>          # Automation driver port
17
--path <path>              # Path to WebDriver endpoints (default "/")
18
--user, -u <user>          # Username for cloud service authentication
19
--key, -k <key>            # Access key for cloud service authentication
20
--logLevel, -l <level>     # Logging verbosity: trace|debug|info|warn|error|silent
21
--bail <number>            # Stop after N test failures
22
--baseUrl <url>            # Base URL for tests
23
--waitforTimeout <ms>      # Default wait timeout in milliseconds
24
--framework <framework>    # Test framework: mocha|jasmine|cucumber
25
--reporters <reporters>    # Test reporters configuration
26
--suite <suites>           # Test suites to execute (repeatable)
27
--spec <specs>             # Specific spec files to run (repeatable)
28
--exclude <patterns>       # Patterns to exclude from execution (repeatable)
29
--coverage                 # Enable code coverage collection
30
--updateSnapshots <mode>   # Snapshot update mode: all|new|none
31
--tsConfigPath <path>      # TypeScript configuration file path
32
--repeat <count>           # Repeat specific specs and/or suites N times
33
--shard <current>/<total>  # Run tests in parallel shards
34
```
35

36
**Usage Examples:**
37

38
```bash
39
# Basic test execution
40
wdio run wdio.conf.js
41

42
# Run specific suite
43
wdio run wdio.conf.js --suite regression
44

45
# Run specific specs
46
wdio run wdio.conf.js --spec ./tests/login.js --spec ./tests/checkout.js
47

48
# Run with custom configuration
49
wdio run wdio.conf.js --baseUrl https://staging.example.com --logLevel debug
50

51
# Run in watch mode for development
52
wdio run wdio.conf.js --watch
53

54
# Run with cloud service credentials
55
wdio run wdio.conf.js --user $SAUCE_USERNAME --key $SAUCE_ACCESS_KEY
56
```
57

58
### REPL Command
59

60
Interactive WebDriver session for manual testing and debugging.
61

62
```bash { .api }
63
wdio repl <option> [capabilities] [options]
64

65
# Parameters:
66
<option>         # Browser or device option (chrome, firefox, safari, edge, etc.)
67
[capabilities]   # JSON capabilities string or file path
68

69
# Options:
70
--platformVersion, -v <version>  # OS version for mobile devices
71
--deviceName, -d <device>        # Device name for mobile devices  
72
--udid, -u <udid>               # Device UDID for mobile devices
73
--hostname, -h <hostname>        # WebDriver server hostname
74
--port, -p <port>               # WebDriver server port
75
--user, -u <user>               # Cloud service username
76
--key, -k <key>                 # Cloud service access key
77
```
78

79
**Usage Examples:**
80

81
```bash
82
# Start Chrome REPL session
83
wdio repl chrome
84

85
# Start mobile device REPL
86
wdio repl android --deviceName "Pixel 4" --platformVersion "11"
87

88
# Start cloud REPL session
89
wdio repl chrome -u $SAUCE_USERNAME -k $SAUCE_ACCESS_KEY
90

91
# Start with custom capabilities
92
wdio repl chrome '{"browserName": "chrome", "browserVersion": "latest"}'
93
```
94

95
### Config Command
96

97
Interactive configuration wizard for setting up WebdriverIO projects.
98

99
```bash { .api }
100
wdio config [options]
101

102
# Options:
103
--yes      # Skip prompts and use default values
104
--dev      # Install packages as dev dependencies
105
```
106

107
**Usage Examples:**
108

109
```bash
110
# Start configuration wizard
111
wdio config
112

113
# Quick setup with defaults
114
wdio config --yes
115
```
116

117
### Install Command
118

119
Install WebdriverIO services, reporters, frameworks, or plugins.
120

121
```bash { .api }
122
wdio install <type> <name> [options]
123

124
# Parameters:
125
<type>    # Package type: service|reporter|framework|plugin
126
<name>    # Package name (without @wdio/ prefix)
127

128
# Options:
129
--config <path>  # Configuration file path
130
--dev           # Install as dev dependency
131
```
132

133
**Usage Examples:**
134

135
```bash
136
# Install a reporter
137
wdio install reporter spec
138

139
# Install a service
140
wdio install service chromedriver
141

142
# Install a framework
143
wdio install framework mocha
144

145
# Install with custom config file
146
wdio install service sauce --config ./custom.conf.js
147
```
148

149
## Common Patterns
150

151
### Default Command Behavior
152

153
When no command is specified, WebdriverIO CLI defaults to the `run` command:
154

155
```bash
156
# These commands are equivalent:
157
wdio wdio.conf.js
158
wdio run wdio.conf.js
159
```
160

161
### Configuration File Discovery
162

163
The CLI supports automatic configuration file discovery:
164

165
```bash
166
# Looks for wdio.conf.js in current directory
167
wdio run
168

169
# Explicit configuration file
170
wdio run ./config/wdio.staging.conf.js
171
```
172

173
### Environment Variable Support
174

175
Many options can be set via environment variables:
176

177
```bash
178
# Set credentials via environment
179
export WDIO_USER=username
180
export WDIO_KEY=accesskey
181
wdio run wdio.conf.js
182

183
# Override log level
184
export WDIO_LOG_LEVEL=debug
185
wdio run wdio.conf.js
186
```
187

188
## Types
189

190
### Command Arguments
191

192
```typescript { .api }
193
interface RunCommandArguments {
194
  configPath: string;
195
  coverage?: boolean;
196
  watch?: boolean;
197
  hostname?: string;
198
  port?: number;
199
  path?: string;
200
  user?: string;
201
  key?: string;
202
  logLevel?: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
203
  bail?: number;
204
  baseUrl?: string;
205
  shard?: Options.ShardOptions;
206
  waitforTimeout?: number;
207
  framework?: string;
208
  reporters?: Reporters.ReporterEntry[];
209
  suite?: string[];
210
  spec?: string[];
211
  exclude?: string[];
212
  mochaOpts?: WebdriverIO.MochaOpts;
213
  jasmineOpts?: WebdriverIO.JasmineOpts;
214
  cucumberOpts?: WebdriverIO.CucumberOpts;
215
  updateSnapshots?: Options.Testrunner['updateSnapshots'];
216
  tsConfigPath?: string;
217
  repeat?: number;
218
  ignoredWorkerServices?: string[];
219
}
220

221
interface ReplCommandArguments {
222
  platformVersion: string;
223
  deviceName: string;
224
  udid: string;
225
  option: string;
226
  capabilities: string;
227
}
228

229
interface InstallCommandArguments {
230
  config?: string;
231
  type: 'service' | 'reporter' | 'framework' | 'plugin';
232
  name: string;
233
}
234
```