Metadata-Version: 2.4
Name: isitup-cli
Version: 0.3.0
Summary: A small CLI that periodically checks whether servers respond to ping, HTTP, and TCP ports
Author: stefan.insam
Author-email: stefan.insam <stefan.insam@netgo.de>
License-Expression: GPL-3.0-only
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Utilities
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: requests>=2.34.2
Requires-Dist: rich>=15.0.0
Requires-Python: >=3.14
Project-URL: Repository, https://github.com/ramsesoriginal/isitup
Project-URL: Issues, https://github.com/ramsesoriginal/isitup/issues
Description-Content-Type: text/markdown

<div align="center">
  <img src="https://raw.githubusercontent.com/ramsesoriginal/isitup/main/logo/main_hero.svg" alt="isitup" width="720">

  <p><strong>Is it up? Ping, HTTP, and TCP checks in one small, fast CLI.</strong></p>

  [![PyPI](https://img.shields.io/pypi/v/isitup-cli?color=blue)](https://pypi.org/project/isitup-cli/)
  [![CI](https://github.com/ramsesoriginal/isitup/actions/workflows/ci.yml/badge.svg)](https://github.com/ramsesoriginal/isitup/actions/workflows/ci.yml)
  [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
  [![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-3776AB?logo=python&logoColor=white)](pyproject.toml)
  [![uv](https://img.shields.io/badge/uv-managed-DE5FE9?logo=uv&logoColor=white)](https://github.com/astral-sh/uv)
  [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
  [![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
  [![GitHub stars](https://img.shields.io/github/stars/ramsesoriginal/isitup?style=social)](https://github.com/ramsesoriginal/isitup)
</div>

---

**isitup** is a small CLI that periodically checks whether servers respond to ping and,
depending on how the target is written, HTTP, a TCP port, or SSH:

| Target | Checks |
| --- | --- |
| `example.com` | ping only |
| `example.com:1337` | ping + TCP connect to port 1337 |
| `http://example.com` / `https://example.com` | ping + HTTP (catching a 500, a DNS failure, an expired TLS certificate, a redirect loop, etc.) |
| `https://example.com:1337` | ping + HTTP, against that port |
| `ssh://example.com` / `ssh://example.com:1337` | ping + SSH (connects and verifies the server's SSH identification banner; defaults to port 22) |

Ping is checked independently from the HTTP/TCP/SSH probe: many hosts (behind
load balancers, CDNs, or firewalls) drop ICMP but serve their actual service
just fine, so a blocked ping alone doesn't mark a target down: the "Status"
column is based on the probe, with ping shown alongside as extra diagnostic
info. A target only shows as `OFFLINE` when both ping and the probe fail; a
ping-only target's status is based on ping alone, since there's nothing else
to check.

If the same host appears more than once (e.g. `example.com` and
`https://example.com/health`), it's only pinged once per round. The ping
result is shared across all targets pointing at that host.

While checks are running you get a live spinner and a progress bar per
target counting down its timeout; results are then shown in a table that
updates in place (via [`rich`](https://github.com/Textualize/rich)) rather
than reprinting on every round.

Each target also keeps a rolling window of its last 20 response times for
the session (HTTP response time, TCP connect time, or SSH connect+banner
time, whichever applies), shown as Min/Max latency columns and a tiny
sparkline ("Trend"), along with
the last time it was seen online and the last time it was seen offline.
This history is in-memory only and resets each time you start the tool.

## Installation

The package is published on PyPI as `isitup-cli`, but it installs a plain
`isitup` command:

```bash
uv tool install isitup-cli
# or: pipx install isitup-cli
# or: pip install isitup-cli
```

To try unreleased changes straight from `main` instead (no PyPI release
needed):

```bash
uv tool install git+https://github.com/ramsesoriginal/isitup
```

Either way, remove it later with `uv tool uninstall isitup`.

## Usage

```bash
isitup example.com https://example.org db.internal:5432
```

`--url`/`-u` work the same way and can be freely mixed with positional
targets: `isitup example.com -u https://example.org` is the same as
`isitup example.com https://example.org`:

```bash
isitup --url example.com --url https://example.org --url db.internal:5432
```

Or with a config file:

```bash
cp config.example.yaml config.yaml
# edit config.yaml
isitup --config config.yaml
```

Config files and CLI-supplied targets (positional or `--url`) can be
combined; the tool watches the union of both. The config file is watched for
changes and reloaded automatically: add, remove, or edit targets without
restarting the tool (CLI-supplied targets can't change at runtime, only
what's in the file).

### Options

| Flag | Description |
| --- | --- |
| `-c`, `--config PATH` | YAML file listing targets; reloaded automatically on change |
| `TARGET` (positional) | a target to monitor: same as `-u`/`--url`, just without the flag (repeatable) |
| `-u`, `--url TARGET` | a target to monitor (repeatable): hostname, `hostname:port`, or a URL |
| `-i`, `--interval SECONDS` | seconds between check rounds (default: 30) |
| `--ping-timeout SECONDS` | ping reply timeout (default: 2) |
| `--http-timeout SECONDS` | timeout for the HTTP request or TCP connect (default: 5) |
| `--no-ping` | skip ICMP entirely, HTTP/TCP-only checks |
| `--columns LIST` | comma-separated list of table columns to show, in order (interactive UI only; `--plain`/`--json` always include every field). see below |
| `--basic-auth USER:PASS` | HTTP Basic Auth for CLI-supplied HTTP targets that don't set their own `basic_auth:` in the config file. see below |
| `--basic-auth-env USER_VAR:PASS_VAR` | same as `--basic-auth`, but reads the username/password from the named environment variables |
| `--tag TAG` | tag applied to CLI-supplied targets (repeatable). see below |
| `--filter-tag TAG` | only monitor targets carrying at least one of the given tags (repeatable). see below |
| `--expected-status SPEC` | comma-separated status codes/ranges (e.g. `200,204,301-302`) that count as OK, for CLI-supplied HTTP targets that don't set their own `expected_status:` in the config file. see below |
| `--warn-status SPEC` | same as `--expected-status`, but for codes that count as WARN instead of OK. see below |
| `--once` | run a single round and exit; exit code is `1` if any target is down, `0` otherwise. Useful as a cron/CI health gate |
| `--plain` | print one plain-text line per target per round instead of the live UI (for logging/piping) |
| `--json` | print one JSON object per target per round instead of the live UI (for machine consumption) |

`--plain` and `--json` are mutually exclusive with each other, and both skip
the interactive spinner/progress UI entirely.

### Config file reference

Two top-level keys:

| Key | Description |
| --- | --- |
| `targets` | list of target entries (required. see below) |
| `columns` | list of table column keys to show, in order (optional; interactive UI only). See "Customizing table columns" below |

Each entry under `targets:` supports:

| Key | Type | Default | Applies to | Description |
| --- | --- | --- | --- | --- |
| `url` | string | *(required)* | all | the target itself: a bare hostname, `hostname:port`, or a URL (`http://`, `https://`, `ssh://`) What gets checked besides ping depends on how it's written (see the table at the top of this README) |
| `name` | string | the `url` value | all | display name shown in place of the raw target string |
| `host` | string | hostname from `url` | all | ping a different host than the one being checked, e.g. when `url` goes through a load balancer or CDN |
| `ping` | bool | `true` | all except ping-only targets | set `false` to skip ICMP for this target (a ping-only target can't disable it, there'd be nothing left to check) |
| `id` | string | auto-generated | all | an explicit, stable identity for history/state; see "Target id" below |
| `tags` | list of strings | `[]` | all | tags for grouping and `--filter-tag`; see "Tagging and grouping" below |
| `basic_auth` | mapping | *(none)* | `http://`/`https://` only | `username`/`password`, or `username_env`/`password_env` to read from an environment variable; see "HTTP Basic Auth" below |
| `expected_status` | list of ints and/or `"NNN-NNN"` ranges | *(none)* | `http://`/`https://` only | status codes that count as OK; see "Custom HTTP status classification" below |
| `warn_status` | list of ints and/or `"NNN-NNN"` ranges | *(none)* | `http://`/`https://` only | status codes that count as WARN; see "Custom HTTP status classification" below |
| `retries` | int, `>= 0` | `0` | HTTP/TCP/SSH (not ping-only) | extra attempts within the same round if the probe comes back DOWN; see "Retries and flap-debouncing" below |
| `failure_threshold` | int, `>= 1` | `1` | HTTP/TCP/SSH (not ping-only) | consecutive DOWN rounds required before the displayed status flips to down; see "Retries and flap-debouncing" below |
| `recovery_threshold` | int, `>= 1` | `1` | HTTP/TCP/SSH (not ping-only) | consecutive non-DOWN rounds required before the status flips back; see "Retries and flap-debouncing" below |

See [config.example.yaml](config.example.yaml) for a fully-annotated example using
every one of these.

### Note on ping

Some servers/networks (common on cloud providers, behind load balancers or
CDNs) block ICMP echo requests entirely even though the service itself is
perfectly reachable. The "Status" column already accounts for this and
won't flag such a target as down (unless it's ping-only, in which case ping
*is* the only signal there is). If you'd rather not run ping checks against
a target at all (e.g. to skip the ~2s ping timeout), either set `ping: false`
for it in the config file, or pass `--no-ping` to disable ICMP checks
globally. Note that a ping-only target (bare hostname, no port) can't have
`ping: false`, there would be nothing left to check.

### SSH availability check

`ssh://example.com` (or `ssh://example.com:1234` for a non-standard port,
default 22) connects over TCP and reads the server's SSH identification
banner (the string like `SSH-2.0-OpenSSH_9.6` that a compliant server sends
before any client input, per RFC 4253) rather than just checking whether
the port is open. If the port is open but the banner doesn't start with
`SSH-`, the target is reported down with `error_kind: protocol`. This
catches something else listening on the port. No SSH handshake, key
exchange, or authentication is attempted, so no credentials are needed or
used.

### Customizing table columns

Every available column, in the order they appear by default:

| Column | Header shown | Default? | Notes |
| --- | --- | --- | --- |
| `target` | Target | Yes | display name (or the raw target string) |
| `status` | Status | Yes | overall UP/WARN/OFFLINE status (debounced. see "Retries and flap-debouncing") |
| `ping` | Ping | Yes | ping status and RTT |
| `service` | Service | Yes | the HTTP/TCP/SSH probe's own status, with code/port/error |
| `latency` | Latency | Yes | this round's latency (falls back to ping RTT when the probe has none) |
| `min` | Min | Yes | rolling-window minimum of the Latency column |
| `max` | Max | Yes | rolling-window maximum of the Latency column |
| `trend` | Trend | Yes | sparkline of the rolling window |
| `last_online` | Last Online | Yes | when this target was last confirmed online |
| `last_offline` | Last Offline | Yes | when this target was last confirmed offline |
| `detail` | Detail | Yes | free-text detail message for the current round |
| `checked` | Checked | Yes | when this round's check ran |
| `id` | Id | No | resolved id; see "Target id" below |
| `tags` | Tags | No | comma-joined tags, or `-`; see "Tagging and grouping" below |
| `content_length` | Size | No | HTTP `Content-Length` header; see "HTTP header/metadata tracking" below |
| `last_modified` | Last Modified | No | HTTP `Last-Modified` header |
| `etag` | ETag | No | HTTP `ETag` header |
| `content_type` | Content-Type | No | HTTP `Content-Type` header |
| `server` | Server | No | HTTP `Server` header |
| `header_change` | Headers Changed | No | when any tracked HTTP header last changed |
| `dns` | Resolved IPs | No | resolved A/AAAA addresses; see "Hostname resolution tracking (DNS)" below |
| `dns_change` | DNS Changed | No | when the resolved IP set last changed |

To show a different subset (or reorder them), pass `--columns` with a
comma-separated list:

```bash
isitup --columns target,status,detail --url https://example.com
```

Or set it once in the config file:

```yaml
columns: [target, status, service, latency, detail]
```

`--columns` takes precedence over a config file's `columns:` list, which
takes precedence over the default. This only affects the interactive UI:
`--plain` and `--json` always include every field, since they're meant for
machine consumption.

### HTTP Basic Auth

Set `basic_auth` on a config file target to send an `Authorization` header
with its HTTP requests. Each of `username`/`password` can be given either
literally or via a `*_env` reference to an environment variable (but not
both):

```yaml
targets:
  - name: Protected API
    url: https://api.internal.example.com
    basic_auth:
      username: admin
      password_env: API_PASSWORD   # read from $API_PASSWORD at startup
```

`basic_auth` only applies to `http://`/`https://` targets. It's rejected
on a bare hostname or `hostname:port` target.

For targets passed directly on the command line (positional or `--url`),
use `--basic-auth USER:PASS` or `--basic-auth-env USER_VAR:PASS_VAR`
instead. Either flag applies to every CLI-supplied HTTP target in that
invocation, but never to config-file targets. Those always use their own
`basic_auth:` (or none), so the two never mix unexpectedly:

```bash
isitup --basic-auth-env API_USER:API_PASSWORD --url https://api.internal.example.com
```

### HTTP header/metadata tracking

For HTTP(S) targets, a handful of response headers are captured every
round: `Content-Length` (response size), `Last-Modified`, `ETag`,
`Content-Type`, and `Server` without ever touching the response body
itself. `--plain`/`--json` always include them (nested under `http` in
JSON, as `content_length=`/`last_modified=`/etc. fields in `--plain`),
alongside a `last_header_change`/`header_change` timestamp: the last time
any of those five values actually differed from the previous round (not
set on the very first check, since there's nothing yet to compare against).
This is handy for noticing "something on this page changed" without
diffing the body yourself.

In the interactive table these show up as the `content_length`,
`last_modified`, `etag`, `content_type`, `server`, and `header_change`
columns: available via `--columns`/config `columns:`, but not part of the
default set (see above), so the table's default look is unaffected.

HTTP checks never download the response body, only the status line and
headers are read off the connection before it's closed. That makes checking
a large file, a big API payload, or a slow streaming endpoint just as cheap
as checking a tiny page.

### Hostname resolution tracking (DNS)

Every target's ping-host (`host` override if set, otherwise its hostname.
see "Note on ping" above) is resolved via DNS once per round, regardless of
target kind (ping-only, TCP, HTTP, or SSH) and independent of whether ping
itself is enabled (`--no-ping`/`ping: false`). Resolution is deduped the
same way ping is, so targets sharing a host are only resolved once.
`--plain`/`--json` always include the result as a top-level `resolved_ips`
field (a list of every A/AAAA address returned, or `null`/`-` if resolution
failed), alongside a `last_dns_change` (JSON) / `dns_change` (`--plain`)
timestamp: the last time the resolved IP set actually changed from the
previous round (not set on the very first check, since there's nothing yet
to compare against). This is handy for noticing a target silently moved to
a new IP (e.g. after a DNS failover or a misconfigured record).

In the interactive table these show up as the opt-in `dns` (resolved IPs)
and `dns_change` columns, available via `--columns`/config `columns:`,
but not part of the default set (see above).

### Tagging and grouping

Any target (ping-only, TCP, or HTTP) can carry `tags` in the config file:

```yaml
targets:
  - name: Prod Website
    url: https://example.com
    tags: [prod, web]
  - name: Staging Website
    url: https://staging.example.com
    tags: [staging, web]
```

Tags show up as their own `Tags` table column. Add it with `--columns
target,tags,status,...` (or a config `columns:` list), since it isn't in
the default set, and always as a `tags` field in `--plain`/`--json`
output.

To only monitor a subset, pass `--filter-tag` (repeatable, a target
matches if it has *any* of the given tags):

```bash
isitup --config config.yaml --filter-tag prod
```

With no `--filter-tag` given, every target is monitored, same as today.
For targets passed directly on the command line, `--tag TAG` (repeatable)
tags every CLI-supplied target in that invocation, like `--basic-auth`,
it never touches config-file targets, which set their own `tags:` instead.

### Target id

Every target has an `id` it's tracked/keyed by internally (history,
last online/offline, header-change tracking). By default this is
auto-generated deterministically from the target's URL, its `host`
override, and its `basic_auth` username (never the password), so
renaming a target or changing its `tags` doesn't reset its history, and
rotating a password doesn't either.

Give a config file target an explicit `id:` when you need to guarantee
its identity, or to disambiguate two targets that would otherwise
auto-generate the same id. Most commonly, the same URL monitored twice
with different credentials:

```yaml
targets:
  - name: Protected API (as Alice)
    url: https://api.internal.example.com
    id: api-as-alice
    basic_auth:
      username: alice
      password_env: ALICE_PASSWORD
  - name: Protected API (as Bob)
    url: https://api.internal.example.com
    basic_auth:
      username: bob
      password_env: BOB_PASSWORD
```

`load_targets` rejects the whole config at startup if any two targets
resolve to the same id (explicit or auto-generated), naming which
targets collide. The resolved `id` is always included as a field in
`--plain`/`--json` output, and available as an opt-in `id` table column
via `--columns`/config `columns:` (not shown by default).

### Failure classification

When the HTTP, TCP, or SSH probe fails, the specific reason is captured as
`error_kind` (visible in `--json` output, and shown as a short tag like
`DOWN (DNS)` in the Service column otherwise):

| `error_kind` | Meaning |
| --- | --- |
| `dns` | the hostname failed to resolve |
| `tls` | a TLS/certificate error (HTTP only, e.g. expired or self-signed cert) |
| `redirect` | too many redirects (HTTP only, possible redirect loop) |
| `timeout` | didn't complete within `--http-timeout` |
| `connection` | connection refused or otherwise unreachable |
| `protocol` | connected, but the server's response wasn't a valid SSH banner (SSH only) |
| `client_error` / `server_error` | got a 4xx / 5xx HTTP response |
| `request_error` | anything else `requests` raised |

Note that `error_kind` above always reflects the raw HTTP status code, even
when a custom `expected_status`/`warn_status` classification (below) decides
a different overall status for the same response: a 404 you've configured
as OK still shows `error_kind: client_error` for diagnostics.

### Custom HTTP status classification

By default, any HTTP response is classified as OK below 400, WARN for
4xx, and DOWN for 5xx. This is what "Failure classification" above
describes. For an HTTP target where a specific 4xx/5xx (or a redirect)
should be treated differently,  e.g. a `401`/`403` on an endpoint you
expect to require auth, or a `404` that should count as fully down instead
of a mere warning, set `expected_status` and/or `warn_status` on it in
the config file:

```yaml
targets:
  - name: Authenticated API (401 without valid creds should be DOWN)
    url: https://protected.internal.example.com/health
    expected_status: [200]
```

Each is a list of bare status codes and/or inclusive `"NNN-NNN"` range
strings, e.g. `expected_status: [200, 204, "300-399"]`. Setting *either*
field on a target **fully replaces** the default classification for it,
it does not blend with or extend the 4xx=warn/5xx=down rule. A code
matching `expected_status` is OK, a code matching `warn_status` is WARN,
and anything matching neither is DOWN. In particular, this means **3xx
redirects are not automatically OK** once you opt in. If your target
redirects and that's fine, include the range explicitly (e.g.
`expected_status: [200, "300-399"]`).

For targets passed directly on the command line, use `--expected-status`
and/or `--warn-status` with a comma-separated value instead (same syntax,
e.g. `--expected-status 200,204,301-302`). Like `--basic-auth`/`--tag`,
these apply only to CLI-supplied HTTP targets that don't already set their
own `expected_status:`/`warn_status:` in the config file, never to
config-file targets:

```bash
isitup --expected-status 200 --url https://protected.internal.example.com/health
```

This is also what makes `--once`'s exit code meaningful for endpoints
where "reachable" isn't good enough: without this, a `401`/`403`/`404` on
a target you actually care about being properly authorized/found only ever
shows as WARN, so `--once` still exits `0`.

### Retries and flap-debouncing

Two related but independent knobs make isitup less trigger-happy about
transient blips, for HTTP/TCP/SSH targets (ping-only targets have nothing
to configure here, there's no separate probe to retry or debounce):

- `retries`: extra attempts of the HTTP/TCP/SSH probe *within the same
  round* if it comes back DOWN, stopping as soon as a non-DOWN result is
  seen. `retries: 2` means up to 3 total attempts. Only the last attempt's
  result is kept; if more than one attempt was made, a short note like
  `(down after 3 attempts)` or `(recovered after 2 attempts)` is appended
  to the detail message.
- `failure_threshold` / `recovery_threshold`: how many *consecutive
  rounds* a target must report DOWN before its displayed status flips to
  reflect that, and how many consecutive non-DOWN rounds it must report
  before flipping back. A single blip that doesn't reach the threshold
  doesn't move the needle at all: The target keeps showing whatever it
  showed before, and a recovery in the middle of an accumulating failure
  streak (or vice versa) resets that streak back to zero rather than
  partially counting toward the threshold.

The **defaults reproduce today's exact behavior**: `retries: 0` (a single
attempt, no retry) and `failure_threshold: 1` / `recovery_threshold: 1`
(the status flips immediately on the very first differing result, exactly
like before this feature existed).

```yaml
targets:
  - name: Flaky But Usually Fine Internal Service
    url: https://flaky.internal.example.com/health
    retries: 2
    failure_threshold: 3
    recovery_threshold: 2
    # Up to 3 attempts per round if the probe comes back DOWN. Even then,
    # the displayed status only flips to down after 3 consecutive rounds
    # report DOWN, and only flips back to up after 2 consecutive rounds
    # report OK/WARN.
```

For targets passed directly on the command line, use `--retries`,
`--failure-threshold`, and `--recovery-threshold` instead. Like
`--basic-auth`/`--tag`/`--expected-status`, these apply only to
CLI-supplied HTTP/TCP/SSH targets that don't already set their own
`retries:`/`failure_threshold:`/`recovery_threshold:` in the config file,
never to config-file targets:

```bash
isitup --retries 2 --failure-threshold 3 --url https://flaky.internal.example.com/health
```

Internally, this is why the online/offline decision now lives entirely in
`TargetHistory`, computed once per round from the raw per-round result:
the debounced status (what's shown as the Status column, the top-level
`status` field in `--json`/`--plain`, and what `--once`'s exit code
reflects) and the `last_online`/`last_offline` timestamps are derived from
the exact same value, so they can never disagree with each other. The
Service column / `http=`/`tcp=`/`ssh=` fields, latency, HTTP headers, DNS
fields, and ping fields are unaffected, they always reflect the raw,
current-round result.

## Development

```bash
uv sync
uv run isitup --once --url https://example.com

uv run pytest       # tests
uv run ruff check .    # lint
uv run ruff format .   # format
uv run mypy src tests  # type check
```

Every push and pull request runs this same lint/type-check/test suite via
[GitHub Actions](.github/workflows/ci.yml), across Linux and Windows.

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## License

[GPL-3.0](LICENSE): see [LICENSE](LICENSE) for the full text.
