hp-viz

hp-viz is a production-ready terminal app for watching the HoneyPeer public attack visualizer in real time — live feed, incidents, peers, stats, history, and threat-intelligence blog posts, without opening a browser.

Default data source: viz.honeypeer.com

Install (recommended)

One command — auto-detects Linux/macOS and amd64/arm64:

curl -fsSL https://viz-cli.honeypeer.com | bash

Installs hp-viz to /usr/local/bin (uses sudo when needed) or ~/.local/bin.

Optional:

HP_VIZ_INSTALL_DIR=~/bin curl -fsSL https://viz-cli.honeypeer.com | bash

Manual download

Rolling binaries live at the latest release — each push to main replaces the build.

curl -fsSL -o hp-viz.tar.gz \
  "https://git.ssh.surf/snxraven/honeypeer-viz-cli/releases/download/latest/hp-viz-linux-amd64.tar.gz"
tar -xzf hp-viz.tar.gz
sudo install -m755 hp-viz-linux-amd64 /usr/local/bin/hp-viz

Archives: hp-viz-linux-amd64, hp-viz-linux-arm64, hp-viz-darwin-amd64, hp-viz-darwin-arm64. SHA256 files are on the release page.

Build from source

Requires Go 1.24+ and a truecolor terminal (COLORTERM=truecolor recommended).

git clone https://git.ssh.surf/snxraven/honeypeer-viz-cli.git
cd honeypeer-viz-cli
make build
./bin/hp-viz --version

Quick start

# Live public feed
hp-viz

# Offline demo (bundled fixture)
hp-viz --fixture tests/fixtures/sse-sample.txt

# Help / version
hp-viz --help
hp-viz --version

Configuration

Precedence: flags → environment → config file → defaults.

Optional file: ~/.config/hp-viz/config.yaml (see config.yaml.example).

Variable	Description
HP_VIZ_URL	Master base URL (default: https://viz.honeypeer.com)
HP_VIZ_BUFFER	In-memory feed size (default 1000, clamped 50–5000)
HP_VIZ_MOUSE	Set 1 or true to enable mouse on startup
HP_VIZ_BELL	Terminal bell on block-tier events
HP_VIZ_REDUCED_MOTION	Static mesh and no synthesized sounds
HP_VIZ_OPERATOR_TOKEN	Saved subscription operator token
HP_VIZ_SUBSCRIPTION_ID	Subscription ID (sub_…) for startup sign-in
HP_VIZ_SUBSCRIPTION_EMAIL	Billing email paired with subscription ID
HP_VIZ_NO_UPDATE	Skip automatic update checks
NO_COLOR / HP_VIZ_NO_COLOR	Disable colors

Flag	Description
--url	Master base URL
--buffer	Feed buffer size
--fixture	Replay SSE from a file (no network)
--record	Append live SSE events to JSONL
--no-color	Disable colors
--bell	Terminal bell on high-severity events
--subscription	Subscription ID for operator sign-in at startup
--email	Billing email for operator sign-in at startup
--no-update	Skip automatic update checks
--version	Print version and exit
--update	Check and apply rolling update, then exit
--help	Show help

Keyboard

Key	Action
j / k, ↑ / ↓	Move selection
Tab / Shift+Tab	Next / previous view
1–7	Jump to Feed · Incidents · Peers · Stats · History · Map · Blog
Enter	Open detail (or read blog post on Blog tab)
Esc	Close detail / back from blog post / cancel filter or search
m	Toggle mouse (off by default)
Click row	Open detail (when mouse on)
Click ✕ / outside	Close detail / search / operator modals
Wheel	Scroll lists and open modals
f	Toggle follow mode (auto-scroll to newest)
s	Search by attack or moderation ID (opens detail on match)
o	Operator sign-in — subscription ID + billing email unlocks real IPs
/	Filter — text or service:ssh geo:cn peer:id tier:block since:1h
v	Toggle peer mesh under the Feed tab
e	Toggle event sounds
- / =	Volume down / up (while sound is on)
PgUp / PgDn	Page list / load more blog or history
] / [	History sub-tab / time range · Map all↔1h
0	Map: reset pan/zoom
r	Reconnect stream
?	Help overlay
q	Quit

Updates

Release builds check for a newer rolling build on startup (every 6 hours by default). When a new commit is published to the latest release, hp-viz downloads the matching archive, verifies SHA256, and replaces itself in place.

hp-viz --version          # show embedded build commit
hp-viz --update           # check now and apply if newer
hp-viz --no-update        # skip automatic checks
HP_VIZ_NO_UPDATE=1 hp-viz # same via environment

Source builds (go build without release ldflags) are not auto-updated. Install via the curl installer to get a self-updating binary.

What you see

• Feed — live attacks, blocks, moderation events (masked IPs on the public feed; operator mode shows real IPs)
• Incidents — grouped activity with drill-down detail
• Peers — animated hub-and-spoke mesh (like the web viz), live roster, connect events
• Stats — aggregates and breakdowns
• History — paginated attack and reputation database history, with time-range filters
• Map — global attack map (web-parity): geo heat, live pulses, peers, pan/zoom
• Blog — published HoneyPeer threat briefings (markdown, tables, charts)

Timestamps use your local timezone.

Development

make check    # gofmt, vet, test, build
make test
make build
make fixture  # offline TUI demo

Releases (maintainers)

Every push to main runs format/vet/tests, then rebuilds and replaces the rolling latest release (binaries + install.sh). Requires the RELEASE_TOKEN Actions secret.

Point https://viz-cli.honeypeer.com at:

https://git.ssh.surf/snxraven/honeypeer-viz-cli/releases/download/latest/install.sh

License

MIT — see LICENSE.