duckduckgo-search-cli 0.1.0

Structured DuckDuckGo search in pure Rust, built for LLM pipelines.

English

What is it?

• Rust CLI that queries html.duckduckgo.com/html/ over plain HTTP.
• No paid API, no Chrome requirement in the hot path, no disk cache.
• Emits JSON, text, Markdown, or NDJSON streams suitable for piping into LLMs.
• Cross-platform: Linux (glibc, musl/Alpine, Flatpak, Snap, NixOS), macOS (Intel + Apple Silicon), Windows (cmd.exe + PowerShell).
• Feature-gated Chrome headless fallback (--features chrome) for JS-heavy pages.
• Parallel multi-query pipeline with per-host rate limiting and cancellation.

Why?

• Drop-in primitive for retrieval-augmented generation: stable JSON schema, stable exit codes.
• Respects .gitignore-style ownership — zero hidden state, configuration lives in XDG dirs.
• Rustls-only TLS: no OpenSSL runtime, no SChannel surprises, static musl builds succeed out of the box.
• Explicit timeouts (--timeout, --global-timeout) and bounded concurrency (--parallel, --per-host-limit) make the tool safe inside automation.

Quick Start

cargo install duckduckgo-search-cli
duckduckgo-search-cli init-config
duckduckgo-search-cli "rust async runtime" --num 5 --format json
duckduckgo-search-cli "rust async runtime" --fetch-content --max-content-length 5000 -o /tmp/out.json

Commands

Flags

Environment Variables

Output Formats

• json (default for pipes): canonical schema with results[], metadados, related_searches, stable field order.
• text: human-readable block NN. Title\n URL\n snippet.
• markdown: - [Title](URL)\n > snippet.
• Stream (--stream): NDJSON where each line is one result; metadata emitted as the final line.

Integration Patterns

# Pipe directly into an LLM preprocessing step.
duckduckgo-search-cli "site:example.com changelog 2025" --num 3 --format json | jaq '.resultados[].url'

# Feed extracted bodies into a summarizer.
duckduckgo-search-cli "tokio runtime internals" --fetch-content --max-content-length 4000 -f json \
  | jaq -r '.resultados[] | "# \(.titulo)\n\(.conteudo)\n"' > corpus.md

# Streaming mode with xargs.
duckduckgo-search-cli "wasm runtimes" --stream | choose 0 | xargs -I{} my-downloader {}

# Offline smoke test via wiremock-backed suite.
cargo test --test integracao_wiremock

Exit Codes

Troubleshooting

1. HTTP 202 / block anomaly: back off, raise --retries, rotate UA via init-config and tweak user-agents.toml.
2. Rate limited (HTTP 429): increase --per-host-limit reduction, enable --match-platform-ua, or add --proxy.
3. Zero results (exit 5): check --lang/--country, try --endpoint lite, and verify --time-filter.
4. Chrome not found: install Chromium via your package manager, or pass --chrome-path /path/to/chrome; feature must be compiled (cargo install duckduckgo-search-cli --features chrome).
5. UTF-8 issues on Windows: the binary auto-switches cmd.exe to code page 65001; if you see mojibake, set chcp 65001 before the run.

See the CHANGELOG for release history.

License: MIT OR Apache-2.0.

Português

O que é?

• CLI em Rust que consulta html.duckduckgo.com/html/ via HTTP puro.
• Sem API paga, sem Chrome no caminho quente, sem cache em disco.
• Emite JSON, texto, Markdown ou streams NDJSON prontos para alimentar LLMs.
• Multiplataforma: Linux (glibc, musl/Alpine, Flatpak, Snap, NixOS), macOS (Intel + Apple Silicon), Windows (cmd.exe + PowerShell).
• Fallback Chrome headless sob flag --features chrome para páginas com JavaScript pesado.
• Pipeline multi-query paralelo com rate-limit por host e cancelamento.

Por quê?

• Primitivo plugável para RAG: schema JSON estável, códigos de saída estáveis.
• Sem estado oculto — configuração mora no diretório XDG.
• TLS só via rustls: sem OpenSSL em runtime, sem surpresa no SChannel, builds musl estáticas funcionam de primeira.
• Timeouts explícitos (--timeout, --global-timeout) e concorrência limitada (--parallel, --per-host-limit) deixam o binário seguro em automação.

Início Rápido

cargo install duckduckgo-search-cli
duckduckgo-search-cli init-config
duckduckgo-search-cli "tokio async runtime" --num 5 --format json
duckduckgo-search-cli "tokio async runtime" --fetch-content --max-content-length 5000 -o /tmp/out.json

Comandos

Flags

Variáveis de Ambiente

Formatos de Saída

• json (default em pipes): schema canônico com resultados[], metadados, buscas_relacionadas.
• text: bloco legível NN. Título\n URL\n snippet.
• markdown: - [Título](URL)\n > snippet.
• Stream (--stream): NDJSON, cada linha é um resultado; metadados na linha final.

Padrões de Integração

# Pipe direto para pré-processamento em LLM.
duckduckgo-search-cli "site:example.com release 2025" --num 3 -f json | jaq '.resultados[].url'

# Enviar bodies extraídos para summarizer.
duckduckgo-search-cli "rust async tokio" --fetch-content --max-content-length 4000 -f json \
  | jaq -r '.resultados[] | "# \(.titulo)\n\(.conteudo)\n"' > corpus.md

# Modo streaming com xargs.
duckduckgo-search-cli "wasm runtimes" --stream | choose 0 | xargs -I{} downloader {}

# Testes offline com wiremock.
cargo test --test integracao_wiremock

Códigos de Saída

Troubleshooting

1. HTTP 202 / bloqueio: aumente --retries, rotacione UA via init-config editando user-agents.toml.
2. Rate limit (HTTP 429): reduza --per-host-limit, ative --match-platform-ua ou use --proxy.
3. Zero resultados (exit 5): confira --lang e --country, tente --endpoint lite, revise --time-filter.
4. Chrome não encontrado: instale Chromium pelo gerenciador de pacotes ou passe --chrome-path /caminho/chrome; a feature precisa ser compilada (cargo install duckduckgo-search-cli --features chrome).
5. Problemas UTF-8 no Windows: o binário muda cmd.exe para code page 65001 automaticamente; se ver mojibake, execute chcp 65001 antes.

Veja o CHANGELOG para o histórico completo.

Licença: MIT OR Apache-2.0.