# RemoteDeck (CLI prototype)

This working prototype is a persistent multi-host TCP health/uptime
watchlist: point it at a text file of "name host:port" targets and it
repeatedly probes each one over TCP, keeps each target's up/down state in
memory, and only reports state CHANGES (unknown->up, up->down, down->up)
as they happen, plus an optional JSON-lines event log a real monitoring
pipeline could tail. It differs from the sibling NetLens tool on purpose:
NetLens is a one-shot port scan / latency probe you run once and read the
output of, while RemoteDeck is a long-running watchlist with saved state
across polls and a transition history -- the "is everything I'm
responsible for actually up" layer you'd run continuously underneath a
real remote-ops workspace. The full RemoteDeck product concept also
includes SSH/SFTP terminal sessions, RDP, tunnels, session tabs, and a
credential vault; none of that is in this prototype. A correct SSH/SFTP
client needs a crypto library beyond Go's standard library (this suite is
intentionally dependency-free), and terminal/session UI is a GUI concern,
not a CLI one -- so those pieces are roadmap items, not shortcuts taken
here. See ../plan.md for the full product plan.

## Build from source

Requires Go 1.24+, no external dependencies.

    go build -o remotedeck .

Cross-compile for another platform:

    GOOS=windows GOARCH=amd64 go build -o remotedeck.exe .
    GOOS=darwin  GOARCH=arm64 go build -o remotedeck .

## Usage

    remotedeck watch --targets <file> [--interval 5s] [--timeout 2s] [--once] [--log events.log] [--json]
    remotedeck help

Flags:

    --targets   path to the watchlist file (required)
    --interval  time between poll passes in continuous mode (default 5s)
    --timeout   per-target TCP connect timeout (default 2s)
    --once      do a single poll pass, print a full status table of every
                target's current state, and exit. Exit code is non-zero if
                ANY target is DOWN and zero if all targets are UP -- wire
                this into cron or a CI health check.
    --log       append every state-transition event as a JSON line to this
                file, so a real monitoring pipeline could tail it. Always
                JSON regardless of --json.
    --json      print console events as JSON instead of human-readable text
                (independent of --log)

Without --once, remotedeck loops forever: it polls all targets every
--interval and prints/logs an event only when a target's state changes
(the very first poll counts as every target transitioning out of
"unknown", so you get an initial status line for free). It keeps running
until interrupted (Ctrl-C / SIGTERM).

### Targets file format

Plain text, one target per line as "name host:port". Blank lines and
lines starting with # are ignored:

    # production hosts
    web1 10.0.0.5:443
    db1  10.0.0.9:5432

### Event JSON shape (console --json and --log lines)

    {"time":"2026-08-10T01:37:38Z","target":"svc","addr":"127.0.0.1:18081",
     "old_state":"up","new_state":"down","reason":"refused"}

    {"time":"2026-08-10T01:37:44Z","target":"svc","addr":"127.0.0.1:18081",
     "old_state":"down","new_state":"up","latency_ms":0.38}

## Prebuilt binaries

See ../downloads/ for prebuilt binaries (Windows/macOS/Linux) and
CHECKSUMS.txt for their SHA-256 hashes. These are unsigned indie builds --
Windows SmartScreen and macOS Gatekeeper will warn on first run, which is
expected until a code-signing certificate is in place.