Metadata-Version: 2.4
Name: proxy-path-doctor
Version: 0.6.0
Summary: A read-only CLI for diagnosing mismatched proxy configuration sources.
Author: proxy-path-doctor contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/oneAI6/proxy-doctor
Project-URL: Issues, https://github.com/oneAI6/proxy-doctor/issues
Project-URL: Changelog, https://github.com/oneAI6/proxy-doctor/blob/main/CHANGELOG.md
Keywords: proxy,network,diagnostics,windows,linux
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: json5>=0.9
Dynamic: license-file

# 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, VS Code and Cursor user proxy settings, 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

Install the latest release from PyPI:

```powershell
python -m pip install proxy-path-doctor
```

For development, install the project from the repository:

```powershell
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:

```powershell
proxy-path-doctor
```

Include a DNS and HTTP connectivity check:

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

Check whether a local development URL is covered by `NO_PROXY`:

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

Generate a JSON report for an issue:

```powershell
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.

## Testing feedback wanted

Real-world proxy setups vary widely. Windows and Linux users who rely on
proxies for development tools, package managers, IDEs, or AI coding tools are
invited to try the CLI and share whether its findings are clear and useful.
See [the testing feedback issue](https://github.com/oneAI6/proxy-doctor/issues/1)
for a short checklist. A successful run with no conflict found is useful too.

## 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`
- VS Code and Cursor user proxy settings, including `http.proxy` and `http.noProxy`
- 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

```text
[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](CONTRIBUTING.md) and [docs/ROADMAP.md](docs/ROADMAP.md).
The [maintainer plan](docs/MAINTAINER_PLAN.md) describes a realistic path from
the MVP to a maintained public project.
Release notes are available in [CHANGELOG.md](CHANGELOG.md).

## License

MIT
