0
# Command Line Interface
1

2
Complete command-line interface for all DuckDuckGo search operations with result saving, downloading, and output formatting options. The CLI provides access to all search functionality through terminal commands.
3

4
## Capabilities
5

6
### CLI Entry Points
7

8
Main CLI interface functions providing command-line access to all search capabilities.
9

10
```python { .api }
11
def cli() -> None:
12
    """Main CLI command group for duckduckgo_search operations."""
13

14
def safe_entry_point() -> None:
15
    """Safe CLI entry point with exception handling."""
16
```
17

18
### CLI Installation and Usage
19

20
The CLI is automatically installed with the package and available through multiple entry points:
21

22
**Via console script (recommended):**
23
```bash
24
ddgs --help
25
```
26

27
**Via Python module:**
28
```bash
29
python -m duckduckgo_search --help
30
```
31

32
### CLI Commands
33

34
#### Version Command
35

36
Display package version information.
37

38
```bash
39
ddgs version
40
```
41

42
#### Text Search Command
43

44
Perform text-based web searches with comprehensive filtering options.
45

46
```bash
47
ddgs text [OPTIONS]
48
```
49

50
**Options:**
51
- `-k, --keywords TEXT` (required): Text search keywords/query
52
- `-r, --region TEXT`: Region code (us-en, ru-ru, etc.)
53
- `-s, --safesearch [on|moderate|off]`: Safe search level (default: moderate)
54
- `-t, --timelimit [d|w|m|y]`: Time filter (day, week, month, year)
55
- `-m, --max_results INTEGER`: Maximum number of results
56
- `-o, --output TEXT`: Output format (csv, json) or filename with extension
57
- `-d, --download`: Download search results
58
- `-dd, --download-directory TEXT`: Custom download directory
59
- `-b, --backend [auto|html|lite]`: Search backend (default: auto)
60
- `-th, --threads INTEGER`: Download threads (default: 10)
61
- `-p, --proxy TEXT`: Proxy URL (e.g., socks5://127.0.0.1:9150)
62
- `-v, --verify`: SSL verification (default: True)
63

64
#### Image Search Command
65

66
Search for images with extensive filtering options.
67

68
```bash
69
ddgs images [OPTIONS]
70
```
71

72
**Options:**
73
- `-k, --keywords TEXT` (required): Image search keywords/query
74
- `-r, --region TEXT`: Region code (default: us-en)
75
- `-s, --safesearch [on|moderate|off]`: Safe search level (default: moderate)
76
- `-t, --timelimit [Day|Week|Month|Year]`: Time filter
77
- `-size, --size [Small|Medium|Large|Wallpaper]`: Image size filter
78
- `-c, --color [color|Monochrome|Red|Orange|Yellow|Green|Blue|Purple|Pink|Brown|Black|Gray|Teal|White]`: Color filter
79
- `-type, --type_image [photo|clipart|gif|transparent|line]`: Image type filter
80
- `-l, --layout [Square|Tall|Wide]`: Layout filter
81
- `-lic, --license_image [any|Public|Share|ShareCommercially|Modify|ModifyCommercially]`: License filter
82
- `-m, --max_results INTEGER`: Maximum number of results
83
- `-o, --output TEXT`: Output format (csv, json) or filename with extension
84
- `-d, --download`: Download image results
85
- `-dd, --download-directory TEXT`: Custom download directory
86
- `-th, --threads INTEGER`: Download threads (default: 10)
87
- `-p, --proxy TEXT`: Proxy URL
88
- `-v, --verify`: SSL verification (default: True)
89

90
#### Video Search Command
91

92
Search for videos with filtering options.
93

94
```bash
95
ddgs videos [OPTIONS]
96
```
97

98
**Options:**
99
- `-k, --keywords TEXT` (required): Video search keywords/query
100
- `-r, --region TEXT`: Region code (default: us-en)
101
- `-s, --safesearch [on|moderate|off]`: Safe search level (default: moderate)
102
- `-t, --timelimit [d|w|m]`: Time filter (day, week, month)
103
- `-res, --resolution [high|standart]`: Video resolution filter
104
- `-d, --duration [short|medium|long]`: Duration filter
105
- `-lic, --license_videos [creativeCommon|youtube]`: License filter
106
- `-m, --max_results INTEGER`: Maximum number of results
107
- `-o, --output TEXT`: Output format (csv, json) or filename with extension
108
- `-p, --proxy TEXT`: Proxy URL
109
- `-v, --verify`: SSL verification (default: True)
110

111
#### News Search Command
112

113
Search for news articles with time-based filtering.
114

115
```bash
116
ddgs news [OPTIONS]
117
```
118

119
**Options:**
120
- `-k, --keywords TEXT` (required): News search keywords/query
121
- `-r, --region TEXT`: Region code (default: us-en)
122
- `-s, --safesearch [on|moderate|off]`: Safe search level (default: moderate)  
123
- `-t, --timelimit [d|w|m|y]`: Time filter (day, week, month, year)
124
- `-m, --max_results INTEGER`: Maximum number of results
125
- `-o, --output TEXT`: Output format (csv, json) or filename with extension
126
- `-p, --proxy TEXT`: Proxy URL
127
- `-v, --verify`: SSL verification (default: True)
128

129
### Usage Examples
130

131
#### Basic Search Commands
132

133
Text search:
134
```bash
135
# Basic text search
136
ddgs text -k "python programming"
137

138
# Text search with filters
139
ddgs text -k "machine learning" -r us-en -t w -m 10
140

141
# Text search with output to file
142
ddgs text -k "data science" -o results.json
143

144
# Text search with CSV output
145
ddgs text -k "web development" -o myresults.csv
146
```
147

148
Image search:
149
```bash
150
# Basic image search
151
ddgs images -k "cats"
152

153
# Image search with filters
154
ddgs images -k "mountains" -size Large -c Green -type photo -m 20
155

156
# Image search with download
157
ddgs images -k "wallpapers" -size Wallpaper -d -m 5
158

159
# Image search with custom download directory
160
ddgs images -k "nature" -dd ./nature_images -d -m 10
161
```
162

163
Video search:
164
```bash
165
# Basic video search  
166
ddgs videos -k "cooking tutorial"
167

168
# Video search with filters
169
ddgs videos -k "programming" -res high -d medium -m 15
170

171
# Video search with Creative Commons filter
172
ddgs videos -k "educational content" -lic creativeCommon -m 10
173
```
174

175
News search:
176
```bash
177
# Basic news search
178
ddgs news -k "technology"
179

180
# Recent news search
181
ddgs news -k "climate change" -t d -m 20
182

183
# Regional news search
184
ddgs news -k "politics" -r uk-en -t w
185
```
186

187
#### Advanced CLI Usage
188

189
Chain multiple searches:
190
```bash
191
# Multiple searches in sequence
192
ddgs text -k "python" -o python_results.json && \
193
ddgs images -k "python logo" -o python_images.json
194
```
195

196
Using proxy:
197
```bash
198
# Search through Tor proxy
199
ddgs text -k "privacy tools" -p socks5://127.0.0.1:9150
200

201
# Search through HTTP proxy
202
ddgs text -k "research" -p http://proxy.example.com:8080
203
```
204

205
Bulk downloading:
206
```bash
207
# Download text search results  
208
ddgs text -k "tutorials" -d -th 20 -m 50
209

210
# Download images with custom directory
211
ddgs images -k "photography" -dd ./photos -d -th 15 -m 30
212
```
213

214
#### Output Format Examples
215

216
JSON output format:
217
```bash
218
# Save as JSON
219
ddgs text -k "example" -o output.json
220

221
# JSON output contains structured data:
222
# [
223
#   {
224
#     "title": "Example Title",
225
#     "href": "https://example.com", 
226
#     "body": "Example description..."
227
#   }
228
# ]
229
```
230

231
CSV output format:
232
```bash
233
# Save as CSV
234
ddgs text -k "example" -o output.csv
235

236
# CSV output contains columns: title,href,body
237
```
238

239
### CLI Configuration
240

241
#### Environment Variables
242

243
Set default proxy via environment variable:
244
```bash
245
export DDGS_PROXY="socks5://127.0.0.1:9150"
246
ddgs text -k "search query"  # Uses DDGS_PROXY automatically
247
```
248

249
#### Proxy Configuration
250

251
Supported proxy formats:
252
- HTTP: `http://proxy.example.com:8080`
253
- HTTPS: `https://proxy.example.com:8080`  
254
- SOCKS5: `socks5://127.0.0.1:9150`
255
- With authentication: `http://user:pass@proxy.example.com:8080`
256
- Tor alias: `tb` (expands to `socks5://127.0.0.1:9150`)
257

258
### Error Handling
259

260
The CLI includes comprehensive error handling:
261

262
```bash
263
# Rate limiting errors are handled gracefully
264
ddgs text -k "query" -m 1000  # May trigger rate limiting
265

266
# Timeout errors with retry suggestions
267
ddgs text -k "query" -p socks5://slow-proxy:9150
268

269
# Invalid parameters are caught and explained
270
ddgs text -k "query" -t invalid_time  # Shows valid options
271
```
272

273
### CLI Output Formats
274

275
#### Interactive Display
276
By default, results are displayed interactively with pagination. Press Enter to view each result.
277

278
#### File Export  
279
Results can be exported to JSON or CSV formats:
280
- JSON: Preserves full data structure
281
- CSV: Flattened format suitable for spreadsheet applications
282

283
#### Download Mode
284
For text and image searches, results can be downloaded to local files:
285
- Text searches: Download linked pages/documents
286
- Image searches: Download image files with metadata-based naming
287

288
### Performance Options
289

290
Threading control for downloads:
291
```bash
292
# Use more threads for faster downloads (default: 10)
293
ddgs images -k "photos" -d -th 20
294

295
# Use fewer threads for slower connections
296
ddgs images -k "photos" -d -th 5
297
```
298

299
### Integration Examples
300

301
Shell scripting integration:
302
```bash
303
#!/bin/bash
304
# Search and process results
305
ddgs news -k "breaking news" -o news.json
306
python -c "
307
import json
308
with open('news.json') as f:
309
    news = json.load(f)
310
    for article in news[:5]:
311
        print(f'{article[\"title\"]} - {article[\"source\"]}')
312
"
313
```
314

315
Automated data collection:
316
```bash
317
# Daily news collection script
318
#!/bin/bash
319
DATE=$(date +%Y%m%d)
320
ddgs news -k "technology news" -t d -o "tech_news_$DATE.json"
321
ddgs news -k "business news" -t d -o "business_news_$DATE.json"
322
```