proxy-path-doctor 0.5.0

A read-only CLI for diagnosing mismatched proxy configuration sources.

proxy-path-doctor

proxy-path-doctor is a small, privacy-conscious, read-only CLI for diagnosing conflicting proxy configuration sources. It collects the settings that commonly cause confusing network failures, highlights mismatches, and produces a report that is safe to share in an issue.

The project is currently an early MVP. It supports Windows system proxy inspection, GNOME desktop proxy inspection on Linux, and portable checks for proxy environment variables, DNS, and optional HTTP connectivity.

Why this exists

Network failures are often reported as "the proxy looks correct" while several independent settings are involved. proxy-path-doctor gathers those signals in one place and redacts credentials before printing them.

The tool does not modify proxy settings, manage proxy servers, or choose a proxy provider. Its focus is explaining which configuration path a program may be using across Windows, Linux, environment variables, and connectivity checks.

Install

The planned PyPI package name for the first public release is proxy-path-doctor. Until then, install the current development version from the repository:

git clone https://github.com/oneAI6/proxy-doctor.git
cd proxy-doctor
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Usage

Inspect local settings without sending a network request:

proxy-path-doctor

Include a DNS and HTTP connectivity check:

proxy-path-doctor --check-url https://example.com

Check whether a local development URL is covered by NO_PROXY:

proxy-path-doctor --check-url http://localhost:3000

Generate a JSON report for an issue:

proxy-path-doctor --format json --output proxy-report.json

Any username or password embedded in a proxy URL is replaced with ***. Review a generated report before posting it publicly because hostnames and proxy addresses may still describe your environment.

Current checks

• Operating system and Python version
• Common proxy environment variables
• Windows user proxy settings
• Windows WinHTTP proxy settings
• Linux GNOME desktop proxy settings through gsettings
• Optional DNS resolution
• Optional HTTP HEAD request with a timeout
• NO_PROXY matching for checked URLs, including domains, ports, and IP addresses
• Actionable findings for conflicting settings and connectivity failures

Example finding

[findings]
- WARNING: Proxy environment variables are set while the Windows user proxy is
  disabled. Suggestion: Check whether your terminal, IDE, or launcher exports
  HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY intentionally.

Contributing

Bug reports and focused pull requests are welcome. See CONTRIBUTING.md and docs/ROADMAP.md. The maintainer plan describes a realistic path from the MVP to a maintained public project. Release notes are available in CHANGELOG.md.

License

MIT