A small, dependency-free Python toolkit for debugging local web development: make HTTP requests, check endpoint health, inspect network configuration, and find listening TCP ports from a terminal UI or CLI.
Status: early-stage software (
0.1.0). Review process and network actions before using them. No license has been selected; do not assume the code is licensed for reuse or redistribution.
- Python 3.10 or newer.
- The terminal interface uses
curses; it is intended for Unix-like terminals. Windows may require a separately provided curses implementation and is not covered by the current CI matrix. - Active-port inspection requires
lsof; process details useps. Availability and visibility depend on the operating system and user permissions. Network-interface and route views use native system utilities and can show limited information if those utilities are unavailable.
The program uses only the Python standard library at runtime.
Install the debug command with uv from a checkout:
uv tool install .The command is then available on your PATH. Running debug with no arguments launches the interactive terminal UI; debug tui launches it explicitly. Use debug --help to see the available CLI commands.
For an isolated project environment instead, you can install with uv venv followed by uv pip install --python .venv/bin/python . (on Windows, use .venv\\Scripts\\python.exe). The curses UI may not be available on Windows.
debug # open the terminal interface
debug tui # open the terminal interface explicitly
debug request GET http://localhost:3000/
debug request POST http://localhost:3000/api \
--json '{"hello":"world"}'
debug request GET https://example.com/ -H 'X-Debug: yes' --headers
printf 'payload' | debug request POST http://localhost:3000/submit --data-stdin
debug health http://localhost:3000/health --expect 200 --body
debug netinfo
debug netinfo --interfaces
debug netinfo --routesrequest also has the alias http. Supported methods are GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS. Options include --preset json|form|text|html, --bearer TOKEN, --timeout SECONDS, --body-only, and --raw; run debug request --help for details. A non-2xx HTTP status makes request return exit status 1; health returns 1 when the received status differs from --expect.
- Requests go to the URL you provide. Do not send credentials or sensitive payloads to untrusted endpoints. TLS certificate checks follow Python's standard library defaults.
- A bearer token supplied on the command line may be visible in shell history or process listings. Prefer a suitably protected environment/secret workflow; the CLI does not currently read bearer tokens from an environment variable.
- Responses can contain private data and are printed to your terminal. The TUI performs network requests synchronously, so an active request can temporarily block interaction.
- Network information can expose hostnames, IP addresses, routes, ports, and process command lines. Treat captured output as sensitive.
- The active-ports TUI offers process termination. Verify the selected process and PID before confirming; terminating the wrong process can interrupt work. Permission checks and operating-system behavior apply.
Run the standard-library test suite and byte-compile the package:
python -m unittest discover -s tests -v
python -m compileall -q .The tests directory is intentionally not part of the installed package. CI runs these checks on Python 3.10–3.14 on Ubuntu. To contribute, add focused tests for behavior changes and avoid committing credentials, captured private responses, or machine-specific output.
Choose and add an appropriate license if reuse is intended, confirm the package/distribution name is available and appropriate, review the security/privacy notes and supported-platform claims, and inspect the final source and test suite. The public distribution name is web-debug; the Python import/module name is webdev.