🦆 DuckDuckGo

██████╗ ██████╗  ██████╗
██╔══██╗██╔══██╗██╔════╝
██║  ██║██║  ██║██║  ███╗
██║  ██║██║  ██║██║   ██║
██████╔╝██████╔╝╚██████╔╝
╚═════╝ ╚═════╝  ╚═════╝

Search and advanced search in DuckDuckGo
========================================

📖 Table of Contents

• Installation
• Features
• Library Usage
• Search Parameters
• Usage
• Options
• Contributing
• License

🚀 Installation

To install duckduckgo cli, use the following Cargo command:

cargo install --locked duckduckgo --all-features

To use it as a library, add it to your Cargo.toml:

[dependencies]
duckduckgo = "0.2.1"

✨ Features

• 🔍 Simple and advanced search: Perform DuckDuckGo searches using basic queries or advanced search operators.
• ⚙️ Search operators: Refine results using DuckDuckGo-compatible filters (e.g. site, filetype, intitle).
• 🛡️ Safe search toggle: Enable or disable family-friendly search filtering.
• 🖨️ Output formatting: Choose between list or detailed formats for displaying results.
• 🧮 Result limiting: Limit the number of results returned (default is 10).
• 🧭 Backend selection: Use --backend to choose the search backend (Auto, HTML, or API).
• 🌐 Custom user agent: Spoof or specify a user agent string for requests.
• 🧩 Cookie control: Enable or disable cookie handling for requests.
• 🕵️ Proxy support: Route requests through a custom HTTP or SOCKS proxy.
• 🐛 Verbose mode: Print debug information for troubleshooting.
• 🎨 ANSI-colored output: Enjoy beautiful, readable output right in your terminal.
• 🔧 Full URL parameter support: Typed enums for every DuckDuckGo URL setting (region, theme, font, colour, …).

🚗 CLI Usage

Learn how to use the duckduckgo and explore its features with the following examples:

Perform a basic search:

ddg --query "rust lang"

Use search operators:

ddg --query "rust lang" --operators "+tutorial"

Enable safe search:

ddg --query "rust lang" --safe

Set the output format to detailed:

ddg --query "rust lang" --format

Limit the number of results to 3:

ddg --query "rust lang" --limit 3

Set user agent:

ddg --query "rust lang" --user-agent "chrome"

Set Different Backends:

# news
ddg --query "rust lang" --backend news

# images
ddg --query "rust lang" --backend images

# lite
ddg --query "rust lang" --backend lite

Set cookie for subsequent requests:

ddg --query "rust lang" --cookie

Set proxy:

ddg --query "rust lang" --proxy "socks5://192.168.1.1:9000"

🎨 Options

📚 Library Usage

Simple browser (zero-configuration)

use duckduckgo::browser::Browser;
use duckduckgo::response::ResultFormat;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let browser = Browser::new();
    browser.search("rust lang", true, ResultFormat::List, Some(5), None).await?;
    Ok(())
}

Configuring the browser with BrowserBuilder

use duckduckgo::browser::Browser;
use duckduckgo::response::ResultFormat;
use duckduckgo::user_agents::get;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let user_agent = get("firefox").unwrap();

    let browser = Browser::builder()
        .user_agent(user_agent)
        .cookie_store(true)
        // .proxy("socks5://127.0.0.1:9050")  // optional
        .build()?;

    browser.search("rust lang", true, ResultFormat::Detailed, Some(5), None).await?;
    Ok(())
}

Image search

use duckduckgo::browser::Browser;
use duckduckgo::user_agents::get;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let browser = Browser::new();
    let images = browser.images("ferris crab", "us-en", true, Some(3), get("firefox").unwrap()).await?;
    for img in images {
        println!("{}: {}", img.title, img.image);
    }
    Ok(())
}

News search

use duckduckgo::browser::Browser;
use duckduckgo::user_agents::get;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let browser = Browser::new();
    let news = browser.news("Rust programming", "us-en", true, Some(5), get("firefox").unwrap()).await?;
    for article in news {
        println!("[{}] {} — {}", article.date, article.title, article.url);
    }
    Ok(())
}

Lite search

use duckduckgo::browser::Browser;
use duckduckgo::user_agents::get;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let browser = Browser::new();
    let results = browser.lite_search("systems programming", "wt-wt", Some(3), get("firefox").unwrap()).await?;
    for r in results {
        println!("{}\n{}", r.title, r.url);
    }
    Ok(())
}

🔧 Search Parameters

The params module provides strongly-typed enums for every documented DuckDuckGo URL parameter. Pass a SearchParams instance to search(), advanced_search(), or search_operators().

use duckduckgo::browser::Browser;
use duckduckgo::response::ResultFormat;
use duckduckgo::params::{SearchParams, Region, SafeSearch, Theme, Size, Font, Toggle};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let params = SearchParams::new()
        .region(Region::UsEn)
        .safe_search(SafeSearch::Moderate)
        .theme(Theme::Dark)
        .size(Size::Large)
        .link_font(Font::Verdana)
        .full_urls(Toggle::On)
        .source("my_app");

    let browser = Browser::new();
    browser.search("rust lang", false, ResultFormat::List, Some(5), Some(&params)).await?;
    Ok(())
}

Available Parameter Groups

🤝 Contributing

Contributions and feedback are welcome! If you'd like to contribute, report an issue, or suggest an enhancement, please engage with the project on GitHub. Your contributions help improve this CLI for the community.

📄 License

This project is licensed under the MIT License.