How to Debug Wigolo Components Using the Doctor Command and Tune Inspect

Use wigolo doctor to perform cold health checks on every core component and wigolo tune to inspect or reset per-domain self-tuning data that drives fetch routing decisions.

Wigolo, an open-source fetching and search orchestration tool maintained by KnockOutEZ, ships with two built-in diagnostic utilities that help you understand why a component is misbehaving and how to fix it. Learning how to debug Wigolo components using the doctor command and tune inspect capabilities ensures you can quickly resolve environment issues and optimize fetch performance. This guide covers the implementation details found in src/cli/doctor.ts and src/cli/tune.ts, providing practical examples for both manual troubleshooting and CI automation.

The Doctor Command: Cold Health Checks

The wigolo doctor command performs isolated, stateless probes of your environment without making network calls that could hang or alter state. According to the CLI reference in docs/cli.md, this command validates the data directory, runtime binaries, models, and provider configurations.

What Doctor Inspects

When you run wigolo doctor, the system defined in src/cli/doctor.ts checks the following components:

• Data directory: Verifies existence, writability, and correct layout under WIGOLO_DATA_DIR.
• Browser engine: Confirms the bundled Chromium binary is present and executable.
• Python runtime: Checks for a healthy Python interpreter and valid virtual environment.
• On-device models: Validates versions of tokenizers, onnxruntime, and downloaded LLM weights.
• LLM providers: Inspects configured providers and required environment variables (e.g., WIGOLO_GITHUB_TOKEN, BRAVE_API_KEY).
• Search backends: Tests SearxNG process health and engine breaker statuses.
• Cache subsystem: Validates SQLite-vec integrity and the background embedding queue.

If every probe passes, the command prints Overall: OK. If a component fails, it outputs a concise error line specifying the exact environment variable or command needed to resolve the issue.

Automatic Repairs with --fix

The --fix flag triggers repair primitives that automatically resolve known failure classes. As implemented in src/cli/doctor.ts, this flag downloads missing Chromium binaries from the Playwright CDN, recreates stale Python virtual environments, re-downloads missing model files, and resets stuck engine breakers via the internal /admin/reset-breakers API.

# Check health

wigolo doctor

# Auto-repair detected issues

wigolo doctor --fix

# Verify repairs succeeded

wigolo doctor

Machine-Readable Output for CI

For automation pipelines, the --json flag emits a structured diagnostic object containing the same information as the textual report. This allows CI systems to parse component health programmatically.

wigolo doctor --json > diagnostics.json

Inspecting Tuning with the Tune Command

While fetching URLs, Wigolo automatically self-tunes per-domain routing parameters, learning which fetch tier (direct, stealth, or proxy), challenge clearance (Cloudflare, Akamai), and backoff settings work best for each domain. The wigolo tune command exposes this data for inspection and reset operations.

Listing and Showing Domain Data

The tuning interface, defined in src/cli/tune.ts, supports several sub-commands:

# List all domains with learned tuning

wigolo tune list

# Show detailed record for a specific domain

wigolo tune show example.com

The output includes the selected tier, clearance type, backoff duration in milliseconds, and the timestamp of the last successful fetch. For example:

$ wigolo tune show wikipedia.org
{
  "domain": "wikipedia.org",
  "tier": "stealth",
  "clearance": "cloudflare",
  "backoff": 500,
  "lastSuccess": "2024-07-19T12:45:00Z"
}

Resetting Stale Tuning Data

When a domain consistently times out or returns captchas, its learned parameters may be sub-optimal. You can force Wigolo to relearn by resetting the tuning data:

# Reset tuning for a single domain

wigolo tune reset wikipedia.org

# Clear all per-domain tuning

wigolo tune reset --all

This is particularly useful after changing global proxy settings or when testing new fetch configurations.

Practical Debugging Workflow

Combine both commands to diagnose and resolve fetch issues systematically:

1. Establish baseline health: Run wigolo doctor to ensure the Chromium binary, models, and data directory are valid.
2. Repair if necessary: Execute wigolo doctor --fix to download missing dependencies or reset stuck breakers.
3. Inspect routing decisions: Run wigolo tune list to identify domains with aggressive backoff or incorrect tier assignments.
4. Reset problematic domains: Use wigolo tune reset <domain> for any site experiencing throttling.
5. Capture state: For CI verification, run wigolo doctor --json to archive the final health status.

Summary

• wigolo doctor performs cold health checks on the data directory, browser engine, models, and providers without making network requests.
• wigolo doctor --fix automatically repairs common failures like missing Chromium binaries or stale Python environments.
• wigolo tune exposes per-domain self-tuning data including fetch tiers, challenge clearances, and backoff settings stored in the cache.
• wigolo tune reset clears learned parameters, forcing the system to relearn optimal routing for specific domains or all domains.
• Both commands support --json output for integration with CI pipelines and automated monitoring.

Frequently Asked Questions

What is the difference between wigolo doctor and wigolo tune?

wigolo doctor checks global environment health—verifying that binaries, models, and configuration files exist and are functional. wigolo tune inspects runtime learning data specific to individual domains, showing how Wigolo adapts its fetching strategy based on past interactions with each site.

Can wigolo doctor --fix resolve network connectivity issues?

No. The --fix flag only repairs local state such as missing Chromium binaries, corrupted model files, or stale Python virtual environments. It does not repair network connectivity, DNS resolution, or external API outages, as these checks are intentionally "cold" and avoid network calls.

Where does Wigolo store the tuning data shown by wigolo tune?

The tuning data is persisted as JSON files under the WIGOLO_DATA_DIR cache directory, managed by the modules in src/cache/. Each domain has its own record containing the learned tier, clearance type, and backoff parameters.

How do I use these commands in a CI pipeline?

Run wigolo doctor --json as a validation step to ensure the environment is correctly configured before executing fetches. Parse the JSON output to check for the overall: "ok" status. If you need to test fetch behavior across different domains, use wigolo tune reset --all before your test suite to ensure consistent, fresh learning behavior.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}