Welcome to Ducker’s documentation!

First Steps with Ducker

Purpose

The purpose of Ducker is to provide a quick way to make internet searches using DuckDuckGo without getting out of the command-line interface. It is very useful for people using an operating system without GUI and for people who like using the terminal for everything.

Install Ducker

Ducker works with Python 3 in any operating system with Python. Install it running the following command:

pip install ducker

Use it

Once installed, you can use it with duck or ducker commands. Imagine that you are looking for cheap skateboards, you can make Ducker launch a search with the following command:

duck buy cheap skateboard

Making advanced searches

From Ducker you can do pretty much the same that you can do with DuckDuckGo. It has options to search for images, videos and websites, to filter results by date, by website... To check out every available option execute duck -h.

You can search for images of ducks executing duck -i ducks or the long form duck --image-search ducks. It’s very intuitive.

You can also use DuckDuckGo bangs and other nice features of DuckDuckGo. Note that you must escape the exclamation mark (!) in Bash when using bangs. To go directly to the website of the first search result you can execute ducker ! freakspot.net or duck \\freakspot.net. You can make this types of searches more comfortable to type using aliases for your shell (see Customization).

DuckDuckGo makes spell corrections sometimes. If you don’t want your spelling to be corrected by DuckDuckGo, then use the --exact flag.

You can even filter results by date with the -t and --time options. You must specify the time limit: a (any time), d (past day), w (past week), m (past month). For instance, ducker -t d cats will get you the results from the past day related to cats.

If you just want to output the search results pages you can use the --np and --noprompt options, which will perform the search, output it in the terminal and exit. If you prefer to output it in JSON format, you can use the --json parameter.

Interactive mode

Ducker comes with a powerful interactive mode, that allows you to view the information about results and open them from it. It can also be used to show more or less results at will. You can even specify the proxy of your network, if you have one. If you find a bunch of useful results and you want to open them at the same time, you can. For example, execute o 1 3 4, if you want to open the results 1, 3 and 5. To check out every option inside the interactive mode, just type ? and press Enter.

To launch the interactive mode, just execute Ducker without any arguments. You can also specify command-line options. Most options work both in interactive and in non-interactive mode.

If you don’t like the appearence of the interactive mode, you can change it specifying the terminal colors using the option --colors. For more information about that check Colors of the interactive mode. Or if you don’t like colors, you can use the option --nocolors.

Autocompletion

Ducker comes with autocompletion files for Bash and for Fish. If you have any of those shells, you should get autocompletion support when you install Ducker with pip. When you install Ducker manually, you must copy the file autocompletion/ducker.bash to /etc/bash_completion.d/ if you use Bash, or copy the file autocompletion/ducker.fish to /etc/fish/functions or to ~/.config/fish/functions if you use Fish.

Customization

Aliases

If you use an option of Ducker very often, you should consider making a shortcut for it in your shell. In Bash-like shells, you can make aliases. Let’s say we want to add an option to search for articles in Wikipedia; we can create a Bash alias for that.

alias wikipedia='ducker \!w'

After that, calling wikipedia in the shell will open the main page of wikipedia, and calling wikipedia free software would open the “Free software” article from wikipedia. Note that we’re using DuckDuckGo bangs and that the exclamation mark (!) must be escaped in Bash. To make Bash remember your alias for your next sessions you must add it to your .bashrc file.

Colors of the interactive mode

Ducker allows you to customize the color scheme via a six-letter string, reminiscent of BSD LSCOLORS. The six letters represent the colors of:

  • indices,
  • titles,
  • URLs,
  • nothing (may probably be used in a later version),
  • abstracts,
  • and prompts

respectively. The six-letter string is passed in either as the argument to the –colors option.

We offer the following colors/styles:

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

The default colors string is GKlgxy, which stands for

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

Note that:

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