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.

← Docs index · Next: Installation