Getting started
From zero to your agent searching the web in about five minutes. You need Node.js 20 or newer.
1. Initialize
npx wigolo init
init is unattended by default — no prompts, safe in scripts and CI. It performs a complete setup: downloads the browser engine and the on-device ranking and embedding models, verifies each component, and prints a per-component report so failures surface loudly instead of hiding until first use. A degraded component doesn't abort setup — it's named in the report, init still exits 0 (agents wired, config persisted), and the component lazy-retries on first use. A non-zero exit is reserved for hard failures like a failed requested agent registration.
To wire your coding agent at the same time, name it:
npx wigolo init --agents=claude-code
--agents takes a comma-separated list (see the full matrix). Omit it to set up the engine only and point any MCP client at wigolo yourself.
Useful variants:
npx wigolo init --no-warmup— skip all downloads; components lazy-load on first use.npx wigolo init --interactive— plain-text prompt flow (agent picker, onboarding questions).npx wigolo init --wizard— the rich guided setup TUI.npx wigolo init --json— machine-readable summary on stdout.
2. First search — through your agent
If you wired an agent, just ask it something that needs the web. The agent now has ten wigolo tools (search, fetch, crawl, cache, extract, find_similar, research, agent, diff, watch) and instructions on when to reach for each.
3. First search — from the terminal
Every tool also runs as a one-shot CLI command:
npx wigolo search "css container queries" --limit=2
Search: "css container queries" (2 results, 1357ms, engines: bing, duckduckgo)
[1] CSS container queries - CSS | MDN - MDN Web Docs - developer.mozilla.org (score: 1.00)
CSS container queries Container queries enable you to apply styles to an
element based on certain attributes of its container ...
[2] Using container size and style queries - CSS | MDN - developer.mozilla.org (score: 0.85)
Using container size and style queries Container queries enable you to
apply styles to elements nested within a specific container ...
Fetch a page as clean markdown:
npx wigolo fetch https://example.com --max-content-chars=400
Fetch: https://example.com/
This domain is for use in documentation examples without needing permission.
Avoid use in operations.
[Learn more](https://iana.org/domains/example)
[cached: false, 149 chars]
Add --json to any tool command for a machine-readable result on stdout.
4. Check the install
npx wigolo doctor
doctor reports the data directory, browser engine, on-device models, configured LLM providers, the search backend, and per-engine status — including which optional engines want an API key and exactly which env var enables them. wigolo doctor --fix repairs known failures.
For an end-to-end capability smoke test (real network, real extraction):
npx wigolo verify
Exit code 0 means every capability passed or was skipped; 1 means something failed.
Where to next
- Configuration — search backends, LLM providers (optional), cache TTLs, proxies.
- Tools — what each of the 10 tools does and returns.
- Installation — Docker, agent matrix, and other channels.
- REST API — run wigolo as a daemon for remote agents.