ddgr.1

.TH "DDGR" "1" "29 Dec 2023" "Version 2.2" "User Commands"
.SH NAME
ddgr \- DuckDuckGo from the terminal
.SH SYNOPSIS
.B ddgr [OPTIONS] [KEYWORD [KEYWORD ...]]
.SH DESCRIPTION
.B ddgr
is a command-line tool to search DuckDuckGo (html version). \fBddgr\fR shows the title, URL and text context for each result. Results are fetched in pages. Keyboard shortcuts are available for page navigation. Results are indexed and a result URL can be opened in a browser using the index number. There is no configuration file as aliases serve the same purpose for this utility. Supports sequential searches in a single instance.
.PP
.B Features
.PP
  * Fast and clean; custom color
  * Designed for maximum readability at minimum space
  * Instant answers (supported by DDG html version)
  * Custom number of results per page
  * Navigation, browser integration
  * Search and option completion scripts (Bash, Fish, Zsh)
  * DuckDuckGo Bangs (along with completion)
  * Open the first result in browser (I'm Feeling Ducky)
  * REPL for continuous searches
  * Keywords (e.g. `filetype:mime`, `site:somesite.com`)
  * Limit search by time, specify region, disable safe search
  * HTTPS proxy support, optionally disable User Agent
  * Do Not Track set by default
  * Supports custom url handler script or cmdline utility
  * Thoroughly documented, man page with examples
  * Minimal dependencies
.SH OPTIONS
.TP
.BI "-h, --help"
Show help text and exit.
.TP
.BI "-n, --num=" N
Show N results per page (default 10). N must be between 0 and 25. N=0 disables fixed paging and shows actual number of results fetched per page.
.TP
.BI "-r, --reg=" REG
Region-specific search e.g. 'us-en' for US (default); visit https://duckduckgo.com/params.
.TP
.BI "-C, --nocolor"
Disable color output.
.TP
.BI "--colors=" COLORS
Set output colors. Refer to the \fBCOLORS\fR section below for details.
.TP
.BI "-j, --ducky"
Open the first result in a web browser; implies \fB--noprompt\fR. Feeling Ducky?
.TP
.BI "-t, --time=" SPAN
Time limit search [d=past day, w=past week, m=past month, y=past year] (default=any time).
.TP
.BI "-w, --site=" SITE
Search a site using DuckDuckGo.
.TP
.BI "-x, --expand"
Expand URLs instead of showing only the domain name (default).
.TP
.BI "-p, --proxy=" URI
Tunnel traffic through an HTTP proxy. \fIURI\fR is of the form \fI[http[s]://][user:pwd@]host[:port]\fR. The proxy server must support HTTP CONNECT tunneling and must not block port 443 for the relevant DuckDuckGo hosts. If a proxy is not explicitly given, the \fIhttps_proxy\fR or \fIHTTPS_PROXY\fR environment variable (if available) is used instead.
.TP
.BI "--unsafe"
Disable safe search.
.TP
.BI "--noua"
Disable user agent. Results are fetched faster.
.TP
.BI "--json"
Output in JSON format; implies \fB--noprompt\fR.
.TP
.BI "-i, --instant"
Retrieves only an instant answer.
.TP
.BI "--gb, --gui-browser"
Open a bang directly in a GUI browser.
.TP
.BI "--np, --noprompt"
Perform search and exit; do not prompt for further interactions.
.TP
.BI "--rev, --reverse"
List the entries in reversed order.
.TP
.BI "--url-handler=" UTIL
Custom script or command-line utility to open urls with.
.TP
.BI "--show-browser-logs"
Do not suppress browser output when opening result in browser; that is, connect stdout and stderr of the browser to ddgr's stdout and stderr instead of /dev/null. By default, browser output is suppressed (due to certain graphical browsers spewing messages to console) unless the \fBBROWSER\fR environment variable is a known text-based browser: elinks, links, lynx, w3m or www-browser.
.TP
.BI "-v, --version"
Show version number and exit.
.TP
.BI "-d, --debug"
Enable debugging.
.SH OMNIPROMPT KEYS
.TP
.BI "n, p, f"
Fetch the next, previous or first set of search results.
.TP
.BI "index"
Open the result corresponding to index in browser.
.TP
.BI o " [index|range|a ...]"
Open space-separated result indices, numeric ranges or all indices, if 'a' is specified, in the browser.
.TP
.BI O " [index|range|a ...]"
Works similar to key 'o', but tries to ignore text-based browsers (even if BROWSER is set) and open links in a GUI browser.
.TP
.BI d " keywords"
Initiate a new DuckDuckGo search for \fIkeywords\fR with original options. This key should be used to search omniprompt keys (including itself) and indices.
.TP
.BI "x"
Toggle url expansion.
.TP
.BI "c index"
Copy url to clipboard.
.TP
.BI "q, ^D, double Enter"
Exit ddgr.
.TP
.BI "?"
Show omniprompt help.
.TP
.BI *
Any other string initiates a new search with original options.
.SH COLORS
\fBddgr\fR allows you to customize the color scheme via a six-letter string, reminiscent of BSD \fBLSCOLORS\fR. The six letters represent the colors of
.IP - 2
indices
.PD 0 \" Change paragraph spacing to 0 in the list
.IP - 2
titles
.IP - 2
URLs
.IP - 2
metadata/publishing info
.IP - 2
abstracts
.IP - 2
prompts
.PD 1 \" Restore paragraph spacing
.TP
respectively. The six-letter string is passed in either as the argument to the \fB--colors\fR option, or as the value of the environment variable \fBDDGR_COLORS\fR.
.TP
We offer the following colors/styles:
.TS
tab(;) box;
l|l
-|-
l|l.
Letter;Color/Style
a;black
b;red
c;green
d;yellow
e;blue
f;magenta
g;cyan
h;white
i;bright black
j;bright red
k;bright green
l;bright yellow
m;bright blue
n;bright magenta
o;bright cyan
p;bright white
A-H;bold version of the lowercase-letter color
I-P;bold version of the lowercase-letter bright color
x;normal
X;bold
y;reverse video
Y;bold reverse video
.TE
.TP
.TP
The default colors string is \fIoCdgxy\fR, which stands for
.IP - 2
bright cyan indices
.PD 0 \" Change paragraph spacing to 0 in the list
.IP - 2
bold green titles
.IP - 2
yellow URLs
.IP - 2
cyan metadata/publishing info
.IP - 2
normal abstracts
.IP - 2
reverse video prompts
.PD 1 \" Restore paragraph spacing
.TP
Note that
.IP - 2
Bright colors (implemented as \ex1b[90m - \ex1b[97m) may not be available in all color-capable terminal emulators;
.IP - 2
Some terminal emulators draw bold text in bright colors instead;
.IP - 2
Some terminal emulators only distinguish between bold and bright colors via a default-off switch.
.TP
Please consult the manual of your terminal emulator as well as \fIhttps://en.wikipedia.org/wiki/ANSI_escape_code\fR for details.
.SH ENVIRONMENT
.TP
.BI BROWSER
Overrides the default browser. Ref:
.I http://docs.python.org/library/webbrowser.html
.TP
.BI DDGR_COLORS
Refer to the \fBCOLORS\fR section.
.TP
.BI DISABLE_PROMPT_COLOR
Force a plain omniprompt if you are facing issues with colors at the prompt.
.TP
.BI "HTTPS_PROXY, https_proxy"
Refer to the \fB--proxy\fR option.
.SH EXAMPLES
.PP
.IP 1. 4
DuckDuckGo \fBhello world\fR:
.PP
.EX
.IP
.B ddgr hello world
.EE
.PP
.IP 2. 4
\fBI'm Feeling Ducky\fR search:
.PP
.EX
.IP
.B ddgr -j lucky ducks
.EE
.PP
.IP 3. 4
\fBDuckDuckGo Bang\fR search 'hello world' in Wikipedia:
.PP
.EX
.IP
.B ddgr !w hello world
.B ddgr \e!w hello world  // bash-specific, need to escape ! on bash
.EE
.PP
.IP "" 4
Bangs work at the omniprompt too. To look up bangs, visit https://duckduckgo.com/bang?#bangs-list.
.PP
.IP 4. 4
\fBBang alias\fR to fire from the cmdline, open results in a GUI browser and exit:
.PP
.EX
.IP
.B alias bang='ddgr --gb --np'
.IP
.B bang !w hello world
.B bang \e!w hello world  // bash-specific, need to escape ! on bash
.EE
.PP
.IP 5. 4
\fBWebsite specific\fR search:
.PP
.EX
.IP
.B ddgr -w amazon.com digital camera
.EE
.PP
.IP "" 4
Site specific search continues at omniprompt.
.EE
.PP
.IP 6. 4
Search for a \fBspecific file type\fR:
.PP
.EX
.IP
.B ddgr instrumental filetype:mp3
.EE
.PP
.IP 7. 4
Fetch results on IPL cricket from \fBIndia\fR in \fBEnglish\fR:
.PP
.EX
.IP
.B ddgr -r in-en IPL cricket
.EE
.PP
.IP "" 4
To find your region parameter token visit https://duckduckgo.com/params.
.PP
.IP 8. 4
Search \fBquoted text\fR:
.PP
.EX
.IP
.B ddgr it\(rs's a \(rs\(dqbeautiful world\(rs\(dq in spring
.EE
.PP
.IP 9. 4
Show \fBcomplete urls\fR in search results (instead of only domain name):
.PP
.EX
.IP
.B ddgr -x ddgr
.EE
.PP
.IP 10. 4
Use a \fBcustom color scheme\fR, e.g., one warm color scheme designed for Solarized Dark:
.PP
.EX
.IP
.B ddgr --colors bjdxxy hello world
.IP
.B DDGR_COLORS=bjdxxy ddgr hello world
.EE
.PP
.IP 11. 4
Tunnel traffic through an \fBHTTPS proxy\fR, e.g., a local Privoxy instance listening on port 8118:
.PP
.EX
.IP
.B ddgr --proxy localhost:8118 hello world
.EE
.PP
.IP "" 4
By default the environment variable \fIhttps_proxy\fR (or \fIHTTPS_PROXY\fR) is used, if defined.
.EE
.PP
.IP 12. 4
Look up \fBn\fR, \fBp\fR, \fBo\fR, \fBO\fR, \fBq\fR, \fBd keywords\fR or a result index at the \fBomniprompt\fR: as the omniprompt recognizes these keys or index strings as commands, you need to prefix them with \fBd\fR, e.g.,
.PP
.EX
.PD 0
.IP
.B d n
.IP
.B d d keywords
.IP
.B d 1
.PD
.EE
.SH AUTHOR
Arun Prakash Jana <engineerarun@gmail.com>
.SH HOME
.I https://github.com/jarun/ddgr
.SH REPORTING BUGS
.I https://github.com/jarun/ddgr/issues
.SH LICENSE
Copyright \(co 2016-2026 Arun Prakash Jana <engineerarun@gmail.com>
.PP
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
.br
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.