0
# CLI Interface
1

2
Command-line interface providing direct access to speed testing functionality with extensive options for output formatting, server selection, and test configuration. Available through both `speedtest-cli` and `speedtest` commands.
3

4
```python
5
import speedtest
6
```
7

8
## Capabilities
9

10
### Main Entry Points
11

12
Primary CLI functions that handle command-line execution and argument processing.
13

14
```python { .api }
15
def main():
16
    """
17
    Main entry point for CLI commands.
18
    Called by both 'speedtest' and 'speedtest-cli' console scripts.
19
    """
20

21
def shell():
22
    """
23
    Main CLI logic and argument processing.
24
    Handles all command-line options and executes appropriate tests.
25
    """
26
```
27

28
### Argument Processing
29

30
Parse and validate command-line arguments with comprehensive option support.
31

32
```python { .api }
33
def parse_args():
34
    """
35
    Parse command-line arguments.
36
    
37
    Returns:
38
    argparse.Namespace: Parsed arguments with all CLI options
39
    """
40

41
def validate_optional_args(args):
42
    """
43
    Validate parsed command-line arguments.
44
    
45
    Parameters:
46
    - args (argparse.Namespace): Parsed arguments to validate
47
    
48
    Raises:
49
    SpeedtestCLIError: Invalid argument combinations or values
50
    """
51
```
52

53
### Output Functions
54

55
Specialized output functions for CLI formatting and display.
56

57
```python { .api }
58
def printer(string, quiet=False, debug=False, error=False, **kwargs):
59
    """
60
    Print output with formatting control.
61
    
62
    Parameters:
63
    - string (str): Text to print
64
    - quiet (bool): Suppress output if True (default: False)
65
    - debug (bool): Only print if DEBUG is True (default: False)
66
    - error (bool): Print to stderr (default: False)
67
    - **kwargs: Additional print() arguments
68
    """
69

70
def csv_header(delimiter=','):
71
    """
72
    Print CSV header row for CLI output.
73
    
74
    Parameters:
75
    - delimiter (str): CSV field delimiter (default: ',')
76
    """
77

78
def version():
79
    """Print version information."""
80
```
81

82
### Signal Handling
83

84
```python { .api }
85
def ctrl_c(shutdown_event):
86
    """
87
    Handle Ctrl+C signal during test execution.
88
    
89
    Parameters:
90
    - shutdown_event (threading.Event): Event to signal shutdown
91
    """
92
```
93

94
## Command-Line Usage
95

96
### Basic Usage
97

98
```bash
99
# Run full speed test
100
speedtest-cli
101

102
# Alternative command
103
speedtest
104
```
105

106
### Common Options
107

108
```bash
109
# Test download only
110
speedtest-cli --no-upload
111

112
# Test upload only  
113
speedtest-cli --no-download
114

115
# Use single connection (simulates file transfer)
116
speedtest-cli --single
117

118
# Show results in bytes instead of bits
119
speedtest-cli --bytes
120

121
# Generate shareable results URL
122
speedtest-cli --share
123
```
124

125
### Output Formats
126

127
```bash
128
# Simple output (less verbose)
129
speedtest-cli --simple
130

131
# JSON output
132
speedtest-cli --json
133

134
# CSV output
135
speedtest-cli --csv
136

137
# CSV with custom delimiter
138
speedtest-cli --csv --csv-delimiter ';'
139

140
# CSV with header row
141
speedtest-cli --csv --csv-header
142
```
143

144
### Server Selection
145

146
```bash
147
# List available servers
148
speedtest-cli --list
149

150
# Use specific server by ID
151
speedtest-cli --server 4954
152

153
# Exclude specific servers
154
speedtest-cli --exclude 1234,5678
155

156
# Use Mini server
157
speedtest-cli --mini http://speedtest.example.com/mini
158
```
159

160
### Connection Options
161

162
```bash
163
# Set timeout (default: 10 seconds)
164
speedtest-cli --timeout 30
165

166
# Use HTTPS connections
167
speedtest-cli --secure
168

169
# Bind to specific source address
170
speedtest-cli --source 192.168.1.100
171

172
# Skip upload pre-allocation (uses less memory)
173
speedtest-cli --no-pre-allocate
174
```
175

176
### Help and Version
177

178
```bash
179
# Show help
180
speedtest-cli --help
181

182
# Show version
183
speedtest-cli --version
184
```
185

186
## CLI Output Examples
187

188
### Default Output
189

190
```
191
Retrieving speedtest.net configuration...
192
Testing from Example ISP (192.168.1.100)...
193
Retrieving speedtest.net server list...
194
Selecting best server based on ping...
195
Hosted by Example Host (City, State) [25.30 km]: 15.474 ms
196
Testing download speed................................................................................
197
Download: 85.44 Mbit/s
198
Testing upload speed....................................................................................................
199
Upload: 9.77 Mbit/s
200
```
201

202
### Simple Output
203

204
```
205
Ping: 15.474 ms
206
Download: 85.44 Mbit/s
207
Upload: 9.77 Mbit/s
208
```
209

210
### JSON Output
211

212
```json
213
{
214
    "download": 85436474.26,
215
    "upload": 9774343.65,
216
    "ping": 15.474,
217
    "server": {
218
        "id": "4954",
219
        "host": "speedtest.example.com:8080",
220
        "name": "City, State",
221
        "country": "Country",
222
        "sponsor": "Example Host",
223
        "lat": "40.7128",
224
        "lon": "-74.0060",
225
        "distance": 25.30
226
    },
227
    "timestamp": "2023-10-01T14:30:45.123456Z",
228
    "bytes_sent": 31457280,
229
    "bytes_received": 125829120,
230
    "share": null
231
}
232
```
233

234
### CSV Output
235

236
```
237
Server ID,Sponsor,Server Name,Timestamp,Distance,Ping,Download,Upload,Share,IP Address
238
4954,Example Host,"City, State",2023-10-01T14:30:45.123456Z,25.30,15.474,85436474.26,9774343.65,,192.168.1.100
239
```
240

241
## CLI Integration Examples
242

243
### Shell Scripting
244

245
```bash
246
#!/bin/bash
247
# Basic speed test with error handling
248
if speedtest-cli --simple > /tmp/speedtest.log 2>&1; then
249
    echo "Speed test completed successfully"
250
    cat /tmp/speedtest.log
251
else
252
    echo "Speed test failed"
253
    exit 1
254
fi
255
```
256

257
### JSON Processing
258

259
```bash
260
#!/bin/bash
261
# Extract specific values from JSON output
262
RESULT=$(speedtest-cli --json)
263
DOWNLOAD=$(echo "$RESULT" | python -c "import sys, json; print(json.load(sys.stdin)['download'])")
264
UPLOAD=$(echo "$RESULT" | python -c "import sys, json; print(json.load(sys.stdin)['upload'])")
265

266
echo "Download: $(echo "scale=2; $DOWNLOAD / 1000000" | bc) Mbps"
267
echo "Upload: $(echo "scale=2; $UPLOAD / 1000000" | bc) Mbps"
268
```
269

270
### Monitoring Script
271

272
```bash
273
#!/bin/bash
274
# Regular speed test monitoring
275
LOG_FILE="/var/log/speedtest.csv"
276

277
# Add header if file doesn't exist
278
if [ ! -f "$LOG_FILE" ]; then
279
    speedtest-cli --csv-header > "$LOG_FILE"
280
fi
281

282
# Append test results
283
speedtest-cli --csv >> "$LOG_FILE"
284
```
285

286
### Automated Testing
287

288
```bash
289
#!/bin/bash
290
# Test with specific server and timeout
291
SERVER_ID="4954"
292
TIMEOUT="30"
293

294
speedtest-cli \
295
    --server "$SERVER_ID" \
296
    --timeout "$TIMEOUT" \
297
    --json \
298
    --secure > "speedtest_$(date +%Y%m%d_%H%M%S).json"
299
```