Metadata-Version: 2.4
Name: netdiag-cli
Version: 0.1.0
Summary: One CLI for network troubleshooting: traceroute with BGP/ASN, DNS, latency, VPN checks, and SRE on-call presets.
Project-URL: Homepage, https://github.com/akintunero/netdiag
Project-URL: Documentation, https://github.com/akintunero/netdiag#readme
Project-URL: Repository, https://github.com/akintunero/netdiag
Project-URL: Issues, https://github.com/akintunero/netdiag/issues
Author-email: Olúmáyòwá Akinkuehinmi <akintunero101@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: bgp,cli,devtools,dns,network,ping,sre,traceroute,vpn
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# netdiag

**Production runbook CLI for network incidents** - traceroute with ASN/BGP, DNS drift, latency, VPN checks, and on-call presets in one binary.

[![CI](https://github.com/akintunero/netdiag/actions/workflows/ci.yml/badge.svg)](https://github.com/akintunero/netdiag/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/python-3.11%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

**Stdlib-only at runtime** · **`--json` on every command** · **Exit codes built for automation**

```bash
netdiag doctor
netdiag oncall <HOST> --json
```

---

## Install

| Method | Command |
|--------|---------|
| From source (dev) | `python3 -m pip install -e ".[dev]"` |
| PyPI | `python3 -m pip install netdiag-cli` |
| From Git | `python3 -m pip install "git+https://github.com/akintunero/netdiag.git"` |

Use `python3 -m pip` (not bare `pip`) on macOS if `pip` is missing. The PyPI package is **`netdiag-cli`**; the command is still **`netdiag`**.

**System tools:** `ping` (required), plus `traceroute`, `dig`, and routing/socket tools as needed. Run `netdiag doctor` to see what is on your PATH.

---

## Runbook workflow

| Step | Command | Exit code |
|------|---------|-----------|
| 1. Pre-flight | `netdiag doctor` | `0` ready · `2` missing required tools |
| 2. Incident check | `netdiag oncall <HOST> --json` | `0` pass · `1` fail · `2` error |
| 3. Ticket artifact | `netdiag report <HOST> -o incident.md` | same |

Exit code semantics are stable in v0.x - see [docs/CLI_CONTRACT.md](docs/CLI_CONTRACT.md).

```bash
netdiag oncall 1.1.1.1 --json
netdiag oncall YOUR-SERVICE.example.com --json | jq '.steps[] | select(.ok==false)'
```

> **Tip:** Run one command per line. Do not paste trailing `#` comments from docs into zsh/bash.

### VPN and corporate DNS

```bash
netdiag vpn --corp intranet.company.com
netdiag oncall app.internal --corp app.internal --vpn --json
```

### Optional config

Copy [docs/config.example.toml](docs/config.example.toml) to `~/.config/netdiag/config.toml`:

```toml
[defaults]
corp_host = "app.internal.corp"

[oncall]
preset = "oncall"
```

### Shell completions

```bash
eval "$(netdiag completion bash)"
eval "$(netdiag completion zsh)"
```

### About the CLI

```bash
netdiag --info    # version, platform, repo links, wordmark banner
```

Set `NETDIAG_NO_BANNER=1` to hide the banner.

---

## Why operators use it

| | |
|---|---|
| **One CLI** | Replaces ad-hoc `dig` + `ping` + `curl` + `traceroute` scripts |
| **`--json`** | PagerDuty, CI, Slack bots, `jq` filters |
| **Presets** | `web`, `api`, `vpn`, `oncall` - tuned check bundles |
| **Small runtime** | No required PyPI dependencies |

---

## Quick start (developers)

```bash
git clone https://github.com/akintunero/netdiag.git
cd netdiag
python3 -m pip install -e ".[dev]"
netdiag doctor
python3 -m pytest tests/ -q
```

Smoke test (live network, all subcommands):

```bash
bash scripts/cli_smoke.sh
```

Example probes:

```bash
netdiag oncall 1.1.1.1 --json
netdiag oncall 1.1.1.1 --preset api --json
netdiag trace 8.8.8.8 -m 12 --no-bgp-api
netdiag report 1.1.1.1 -o incident.md
```

---

## Command reference

| Command | Description |
|---------|-------------|
| **`doctor`** | Pre-flight: required tools for runbooks |
| **`oncall`** | Primary incident bundle (preset `oncall`) |
| `report` | Markdown report (`-o file.md`, `--vpn`) |
| `vpn` | VPN, split-tunnel, DNS drift |
| `check` | Health check; `--preset` for bundles |
| `trace` | Traceroute + ASN/BGP enrichment |
| `ping` / `latency` | RTT, jitter, percentiles |
| `dns` / `dns-trace` / `dns-compare` / `dns-all` | DNS tooling |
| `port` / `ports` | TCP probes and scans |
| `http` / `tls` / `redirects` / `headers` | Application layer |
| `speed` | CDN throughput (Cloudflare by default) |
| `compare` | Two-host DNS + ping diff |
| `presets` | List available presets |
| `completion` | bash / zsh completions |

Also: `route`, `ifaces`, `local-ports`, `connections`, `whois`, `subnet`, `ip`, `ptr`, `mtr`, and more - `netdiag --help`.

All commands support `--json`.

---

## Documentation

| Doc | Link |
|-----|------|
| Docs index | [docs/README.md](docs/README.md) |
| Cookbook (on-call recipes) | [docs/cookbook.md](docs/cookbook.md) |
| CLI contract (exit codes, flags) | [docs/CLI_CONTRACT.md](docs/CLI_CONTRACT.md) |
| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
| Security | [SECURITY.md](SECURITY.md) |
| Roadmap | [ROADMAP.md](ROADMAP.md) |
| Changelog | [CHANGELOG.md](CHANGELOG.md) |

---

## Author

**Olúmáyòwá Akinkuehinmi** - [@akintunero](https://github.com/akintunero) · [akintunero101@gmail.com](mailto:akintunero101@gmail.com)

## License

MIT - see [LICENSE](LICENSE).

## Responsible use

Use only on networks and hosts you are authorized to test.
