DDGR(1)

📦
version 2.2 · 3 versions
  • 2.2 · arch rolling, debian trixie, epel 10, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
  • 1.9 · ubuntu jammy
  • 2.1 · debian bookworm
, in arch rolling, debian trixie, epel 10, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu noble, ubuntu resolute, ubuntu stonking

ddgr 💖 the DuckDuckGo-in-your-terminal bestie

okay so first things first, bestie: this whole page is the manual for ddgr, and it lives in the User Commands section of your man pages, and it's ddgr(1). yes it's a man page. yes it's about to be cute. let's GO 🦋

✨ NAME ✨

ddgr — DuckDuckGo from the terminal 🦆💻

✨ SYNOPSIS ✨

ddgr [OPTIONS] [KEYWORD [KEYWORD ...]]

✨ DESCRIPTION ✨

okay so ddgr is a command-line tool that lets you search DuckDuckGo (the html version, specifically) straight from your terminal, no browser tab chaos required 💅 For every result it shows you the title, the URL and the text context. Results come in pages, and there are keyboard shortcuts for flipping between those pages. Every result gets an index number, and you can pop a result URL open in a browser just by using that index. There's no configuration file, because aliases do the exact same job for this utility. And it supports sequential searches in a single instance, which is lowkey the best part. ✨

🌸 Features 🌸

  • 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 🍃

✨ OPTIONS ✨

  • -h, --help — shows the help text and dips. 👋
  • -n, --num=N — show N results per page (default 10). N has to be between 0 and 25. and listen, N=0 is a whole vibe: it disables fixed paging and just shows the actual number of results fetched per page. 🍓
  • -r, --reg=REG — region-specific search, like 'us-en' for US (that's the default btw); go visit https://duckduckgo.com/params to find yours. 🌍
  • -C, --nocolor — disables color output. (sad but valid, sometimes you just want plain 🥲)
  • --colors=COLORS — set your output colors. details live in the COLORS section below, keep scrolling bestie 👇
  • -j, --ducky — opens the first result in a web browser; it implies --noprompt. Feeling Ducky? 🦆✨
  • -t, --time=SPAN — time-limit your search [d=past day, w=past week, m=past month, y=past year] (default=any time). ⏳
  • -w, --site=SITE — search a site using DuckDuckGo. 🔍
  • -x, --expand — expand URLs instead of showing only the domain name (this is the default, iconic behaviour). 💅
  • -p, --proxy=URI — tunnel traffic through an HTTP proxy. URI looks like [http[s]://][user:pwd@]host[:port]. The proxy server must support HTTP CONNECT tunneling and must not block port 443 for the relevant DuckDuckGo hosts. If you don't explicitly hand over a proxy, the https_proxy or HTTPS_PROXY environment variable (if it's available) gets used instead. 🚇
  • --unsafe — disable safe search. (living dangerously, no cap 🫣)
  • --noua — disable user agent. Results are fetched faster. 🏃♀️
  • --json — output in JSON format; implies --noprompt. 🤖
  • --gb, --gui-browser — open a bang directly in a GUI browser. 🖥️
  • --np, --noprompt — perform the search and exit; don't prompt for any further interactions. 🚪
  • --rev, --reverse — list the entries in reversed order. 🔄
  • --url-handler=UTIL — custom script or command-line utility to open urls with. 🛠️
  • --show-browser-logs — do not suppress browser output when opening a result in a 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 (because certain graphical browsers just be spewing messages to console) — unless the BROWSER environment variable is a known text-based browser: elinks, links, lynx, w3m or www-browser. 🗣️
  • -v, --version — show the version number and exit. 🔢
  • -d, --debug — enable debugging. 🐛

✨ OMNIPROMPT KEYS ✨

  • n, p, f — fetch the next, previous or first set of search results. ⏮️⏭️
  • index — open the result corresponding to index in the browser. 🌐
  • o [index|range|a ...] — open space-separated result indices, numeric ranges, or all indices (if 'a' is specified) in the browser. 🫶
  • O [index|range|a ...] — works similar to key 'o', but it tries to ignore text-based browsers (even if BROWSER is set) and open links in a GUI browser instead. 🖥️
  • d keywords — initiate a new DuckDuckGo search for keywords with the original options. You use this key to search omniprompt keys (including itself!) and indices. iykyk 👀
  • x — toggle url expansion. 🔀
  • c index — copy url to clipboard. 📋
  • q, ^D, double Enter — exit ddgr. bye bestie 💜
  • ? — show omniprompt help. ❓
  • * — any other string initiates a new search with the original options. 🌟

✨ COLORS ✨

ddgr lets you customize the color scheme via a six-letter string, which is giving major BSD LSCOLORS energy. Those six letters represent the colors of:

  • indices
  • titles
  • URLs
  • metadata/publishing info
  • abstracts
  • prompts

respectively. (in that exact order, don't mix them up 🎀)

You pass that six-letter string in either as the argument to the --colors option, or as the value of the environment variable DDGR_COLORS. ✨

Here's the menu of colors/styles, no tables needed, we're doing bullets because we're cute like that:

  • 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

The default colors string is oCdgxy, which stands for:

  • bright cyan indices
  • bold green titles
  • yellow URLs
  • cyan metadata/publishing info
  • normal abstracts
  • reverse video prompts

Now, some tea you need to know ☕:

  • Bright colors (implemented as \x1b[90m - \x1b[97m) may not be available in all color-capable terminal emulators;
  • Some terminal emulators draw bold text in bright colors instead;
  • Some terminal emulators only distinguish between bold and bright colors via a default-off switch.

Please consult the manual of your terminal emulator as well as https://en.wikipedia.org/wiki/ANSI_escape_code for details. 🧚

✨ ENVIRONMENT ✨

  • BROWSER — overrides the default browser. Ref: http://docs.python.org/library/webbrowser.html
  • DDGR_COLORS — refer to the COLORS section. 🎨
  • DISABLE_PROMPT_COLOR — force a plain omniprompt if you're facing issues with colors at the prompt. 🙈
  • HTTPS_PROXY, https_proxy — refer to the --proxy option. 🚇

✨ EXAMPLES ✨

  1. DuckDuckGo hello world:
ddgr hello world
  1. I'm Feeling Ducky search:
ddgr -j lucky ducks
  1. DuckDuckGo Bang search 'hello world' in Wikipedia:
ddgr !w hello world
ddgr \!w hello world // bash-specific, need to escape ! on bash

Bangs work at the omniprompt too. To look up bangs, visit https://duckduckgo.com/bang?#bangs-list. ❗

  1. Bang alias to fire from the cmdline, open results in a GUI browser and exit:
alias bang='ddgr --gb --np'

bang !w hello world
bang \!w hello world // bash-specific, need to escape ! on bash
  1. Website specific search:
ddgr -w amazon.com digital camera

Site specific search continues at omniprompt. 🛍️

  1. Search for a specific file type:
ddgr instrumental filetype:mp3
  1. Fetch results on IPL cricket from India in English:
ddgr -r in-en IPL cricket

To find your region parameter token visit https://duckduckgo.com/params. 🏏

  1. Search quoted text:
ddgr it\'s a \"beautiful world\" in spring
  1. Show complete urls in search results (instead of only domain name):
ddgr -x ddgr
  1. Use a custom color scheme, e.g., one warm color scheme designed for Solarized Dark:
ddgr --colors bjdxxy hello world

DDGR_COLORS=bjdxxy ddgr hello world
  1. Tunnel traffic through an HTTPS proxy, e.g., a local Privoxy instance listening on port 8118:
ddgr --proxy localhost:8118 hello world

By default the environment variable https_proxy (or HTTPS_PROXY) is used, if defined. 🚇

  1. Look up n, p, o, O, q, d keywords or a result index at the omniprompt: as the omniprompt recognizes these keys or index strings as commands, you need to prefix them with d, e.g.,
d n
d d keywords
d 1

✨ AUTHOR ✨

Arun Prakash Jana <engineerarun@gmail.com> 👑

✨ HOME ✨

https://github.com/jarun/ddgr 🏠

✨ REPORTING BUGS ✨

https://github.com/jarun/ddgr/issues 🐛 (be nice, they're doing great)

✨ LICENSE ✨

Copyright © 2016-2024 Arun Prakash Jana <engineerarun@gmail.com>

License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

fr fr, that's a real "no warranty" — like, to the extent permitted by law, none. bestie said it, not me. 💀

and that's the whole page, bestie 🎀 this manual is Version 2.2, dated 29 Dec 2023, and it goes out to you from the User Commands section of the man pages as ddgr(1). now go search something, you're gonna slay 🦆💅✨

📦 where this page comes from