0
# Command Line Interface
1

2
Complete CLI interface for performing searches from the command line with support for all search types, output formats, and configuration options. The CLI provides access to all DDGS functionality through a simple command-line interface.
3

4
## Installation and Access
5

6
After installing the ddgs package, the CLI is available as the `ddgs` command:
7

8
```bash
9
pip install ddgs
10
ddgs --help
11
```
12

13
## Capabilities
14

15
### Global Commands
16

17
#### Version Information
18

19
Display the current version of the ddgs package.
20

21
```bash { .api }
22
ddgs version
23
```
24

25
#### Help Information  
26

27
Display help information for the CLI or specific commands.
28

29
```bash { .api }
30
ddgs --help
31
ddgs COMMAND --help
32
```
33

34
### Text Search Command
35

36
Perform text search across multiple search engines with comprehensive filtering and output options.
37

38
```bash { .api }
39
ddgs text [OPTIONS]
40

41
Options:
42
  -q, --query TEXT              Search query (required)
43
  -r, --region TEXT             Search region [default: us-en]
44
  -s, --safesearch [on|moderate|off]  Safety filter level [default: moderate]
45
  -t, --timelimit [d|w|m|y]     Time limit filter
46
  -m, --max_results INTEGER     Maximum results to return [default: 10]
47
  -p, --page INTEGER            Page number [default: 1]  
48
  -b, --backend [auto|all|bing|brave|duckduckgo|google|mojeek|mullvad_brave|mullvad_google|yandex|yahoo|wikipedia]
49
                                Search backend selection [default: auto]
50
  -o, --output TEXT             Output format: csv, json, or filename
51
  -d, --download                Download results flag
52
  -dd, --download-directory TEXT Download directory path
53
  -th, --threads INTEGER        Download threads [default: 10]
54
  -pr, --proxy TEXT             Proxy URL (supports 'tb' for Tor Browser)
55
  -v, --verify / --no-verify    SSL verification [default: verify]
56
  --help                        Show help message
57
```
58

59
**Usage Examples:**
60

61
```bash
62
# Basic text search
63
ddgs text -q "python programming"
64

65
# Advanced text search with filters
66
ddgs text -q "machine learning" -r "us-en" -s "moderate" -t "w" -m 20
67

68
# Search with specific backends
69
ddgs text -q "artificial intelligence" -b "google,bing" -m 50
70

71
# Output to JSON file
72
ddgs text -q "data science" -o results.json
73

74
# Search with proxy
75
ddgs text -q "research topic" -pr "socks5://127.0.0.1:9050"
76

77
# Search without SSL verification
78
ddgs text -q "query" --no-verify
79
```
80

81
### Image Search Command
82

83
Perform image search with size, color, type, layout, and license filtering options.
84

85
```bash { .api }
86
ddgs images [OPTIONS]
87

88
Options:
89
  -q, --query TEXT              Search query (required)
90
  -r, --region TEXT             Search region [default: us-en]
91
  -s, --safesearch [on|moderate|off]  Safety filter level [default: moderate]
92
  -t, --timelimit [d|w|m|y]     Time limit filter
93
  -m, --max_results INTEGER     Maximum results to return [default: 10]
94
  -p, --page INTEGER            Page number [default: 1]
95
  -b, --backend [auto|all|duckduckgo]  Search backend [default: auto]
96
  -size [Small|Medium|Large|Wallpaper]  Image size filter
97
  -c, --color [color|Monochrome|Red|Orange|Yellow|Green|Blue|Purple|Pink|Brown|Black|Gray|Teal|White]
98
                                Color filter
99
  -type, --type_image [photo|clipart|gif|transparent|line]
100
                                Image type filter
101
  -l, --layout [Square|Tall|Wide]  Image layout filter
102
  -lic, --license_image [any|Public|Share|ShareCommercially|Modify|ModifyCommercially]
103
                                License filter
104
  -o, --output TEXT             Output format: csv, json, or filename
105
  -d, --download                Download images flag
106
  -dd, --download-directory TEXT Download directory path
107
  -th, --threads INTEGER        Download threads [default: 10]
108
  -pr, --proxy TEXT             Proxy URL
109
  -v, --verify / --no-verify    SSL verification [default: verify]
110
  --help                        Show help message
111
```
112

113
**Usage Examples:**
114

115
```bash
116
# Basic image search
117
ddgs images -q "sunset landscape"
118

119
# Filtered image search
120
ddgs images -q "logo design" -size "Large" -c "Blue" -type "transparent"
121

122
# Download images
123
ddgs images -q "nature photos" -d -dd "./downloads" -th 5
124

125
# High-resolution wallpapers
126
ddgs images -q "mountain wallpaper" -size "Wallpaper" -l "Wide"
127
```
128

129
### News Search Command
130

131
Perform news search across news sources with date filtering.
132

133
```bash { .api }
134
ddgs news [OPTIONS]
135

136
Options:
137
  -q, --query TEXT              Search query (required)
138
  -r, --region TEXT             Search region [default: us-en]
139
  -s, --safesearch [on|moderate|off]  Safety filter level [default: moderate]
140
  -t, --timelimit [d|w|m|y]     Time limit filter
141
  -m, --max_results INTEGER     Maximum results to return [default: 10]
142
  -p, --page INTEGER            Page number [default: 1]
143
  -b, --backend [auto|all|duckduckgo|yahoo]  Search backend [default: auto]
144
  -o, --output TEXT             Output format: csv, json, or filename
145
  -pr, --proxy TEXT             Proxy URL
146
  -v, --verify / --no-verify    SSL verification [default: verify]
147
  --help                        Show help message
148
```
149

150
**Usage Examples:**
151

152
```bash
153
# Recent news search
154
ddgs news -q "climate change" -t "d" -m 20
155

156
# Business news from specific source
157
ddgs news -q "stock market" -b "yahoo" -m 15
158

159
# Export news to CSV
160
ddgs news -q "technology trends" -o "tech_news.csv"
161
```
162

163
### Video Search Command
164

165
Perform video search with resolution, duration, and license filtering.
166

167
```bash { .api }
168
ddgs videos [OPTIONS]
169

170
Options:
171
  -q, --query TEXT              Search query (required)
172
  -r, --region TEXT             Search region [default: us-en]
173
  -s, --safesearch [on|moderate|off]  Safety filter level [default: moderate]
174
  -t, --timelimit [d|w|m]       Time limit filter (videos support d/w/m only)
175
  -m, --max_results INTEGER     Maximum results to return [default: 10]
176
  -p, --page INTEGER            Page number [default: 1]
177
  -b, --backend [auto|all|duckduckgo]  Search backend [default: auto]
178
  -res, --resolution [high|standard]  Video resolution filter
179
  -dur, --duration [short|medium|long]  Video duration filter
180
  -lic, --license_videos [creativeCommon|youtube]  Video license filter
181
  -o, --output TEXT             Output format: csv, json, or filename
182
  -pr, --proxy TEXT             Proxy URL
183
  -v, --verify / --no-verify    SSL verification [default: verify]
184
  --help                        Show help message
185
```
186

187
**Usage Examples:**
188

189
```bash
190
# Basic video search
191
ddgs videos -q "python tutorial"
192

193
# High-quality, short videos
194
ddgs videos -q "quick recipes" -res "high" -dur "short" -m 10
195

196
# Creative Commons videos
197
ddgs videos -q "educational content" -lic "creativeCommon"
198
```
199

200
### Book Search Command
201

202
Perform book search across book databases and archives.
203

204
```bash { .api }
205
ddgs books [OPTIONS]
206

207
Options:
208
  -q, --query TEXT              Search query (required)
209
  -m, --max_results INTEGER     Maximum results to return [default: 10]
210
  -p, --page INTEGER            Page number [default: 1]
211
  -b, --backend [auto|all|annasarchive]  Search backend [default: auto]
212
  -o, --output TEXT             Output format: csv, json, or filename
213
  -pr, --proxy TEXT             Proxy URL
214
  -v, --verify / --no-verify    SSL verification [default: verify]
215
  --help                        Show help message
216
```
217

218
**Usage Examples:**
219

220
```bash
221
# Book search
222
ddgs books -q "machine learning textbook"
223

224
# Programming books with results export
225
ddgs books -q "python programming" -m 30 -o "programming_books.json"
226
```
227

228
## Output Formats
229

230
### Console Output (Default)
231

232
Results are displayed in the console with formatted output showing titles, URLs, and descriptions.
233

234
### JSON Output
235

236
```bash
237
# Output to console as JSON
238
ddgs text -q "query" -o json
239

240
# Save to JSON file
241
ddgs text -q "query" -o results.json
242
```
243

244
### CSV Output
245

246
```bash
247
# Output to console as CSV
248
ddgs text -q "query" -o csv
249

250
# Save to CSV file  
251
ddgs text -q "query" -o results.csv
252
```
253

254
## Configuration Options
255

256
### Proxy Configuration
257

258
```bash
259
# Use system proxy
260
ddgs text -q "query" -pr "http://proxy.example.com:8080"
261

262
# Use SOCKS proxy
263
ddgs text -q "query" -pr "socks5://127.0.0.1:9050"
264

265
# Use Tor Browser (shortcut)
266
ddgs text -q "query" -pr "tb"
267
```
268

269
### SSL Verification
270

271
```bash
272
# Disable SSL verification (not recommended)
273
ddgs text -q "query" --no-verify
274

275
# Enable SSL verification (default)
276
ddgs text -q "query" --verify
277
```
278

279
### Region and Language Settings
280

281
```bash
282
# US English (default)
283
ddgs text -q "query" -r "us-en"
284

285
# German Germany
286
ddgs text -q "query" -r "de-de"
287

288
# UK English
289
ddgs text -q "query" -r "uk-en"
290

291
# Russian Russia
292
ddgs text -q "query" -r "ru-ru"
293
```
294

295
### Safety Filters
296

297
```bash
298
# Strict filtering
299
ddgs text -q "query" -s "on"
300

301
# Moderate filtering (default)
302
ddgs text -q "query" -s "moderate"
303

304
# No filtering
305
ddgs text -q "query" -s "off"
306
```
307

308
### Time Filters
309

310
```bash
311
# Last day
312
ddgs text -q "query" -t "d"
313

314
# Last week
315
ddgs text -q "query" -t "w"
316

317
# Last month
318
ddgs text -q "query" -t "m"
319

320
# Last year
321
ddgs text -q "query" -t "y"
322
```
323

324
## Advanced Usage
325

326
### Batch Processing
327

328
```bash
329
#!/bin/bash
330
# Batch search script
331

332
queries=("machine learning" "artificial intelligence" "data science")
333
for query in "${queries[@]}"; do
334
    echo "Searching for: $query"
335
    ddgs text -q "$query" -m 20 -o "${query// /_}_results.json"
336
    sleep 2  # Rate limiting
337
done
338
```
339

340
### Pipeline Integration
341

342
```bash
343
# Use with other command-line tools
344
ddgs text -q "python libraries" -o json | jq '.[] | .title'
345

346
# Extract URLs only
347
ddgs text -q "research papers" -o json | jq -r '.[] | .href'
348

349
# Count results
350
ddgs text -q "statistics" -o json | jq '. | length'
351
```
352

353
### Download Automation
354

355
```bash
356
# Download images automatically
357
ddgs images -q "stock photos" -d -dd "./stock_images" -th 8 -m 50
358

359
# Download with specific naming
360
ddgs images -q "logos" -d -dd "./company_logos" -th 4
361
```
362

363
## Error Handling
364

365
The CLI returns appropriate exit codes:
366

367
- **0**: Success
368
- **1**: General error (invalid arguments, network issues)
369
- **2**: Rate limit exceeded
370
- **3**: Timeout error
371

372
```bash
373
# Check exit status
374
ddgs text -q "query"
375
if [ $? -eq 0 ]; then
376
    echo "Search successful"
377
else
378
    echo "Search failed with code $?"
379
fi
380
```
381

382
## Environment Variables
383

384
Set environment variables for default configuration:
385

386
```bash
387
export DDGS_PROXY="socks5://127.0.0.1:9050"
388
export DDGS_TIMEOUT="15"
389
ddgs text -q "query"  # Uses environment proxy and timeout
390
```