Introduction

bee-tui is a terminal cockpit for Ethereum Swarm Bee node operators. It surfaces the state Bee's API hides — bucket collisions, redistribution skip reasons, bin starvation, NAT reality — in fourteen live screens, with an always-on HTTP request tail so operators trust what they see.

bee-tui cold-start tour

This handbook is the per-screen reference. It explains what each screen shows, why it matters, and how to use the keymap. The high-level project plan lives in docs/PLAN.md; the README is the install + quickstart entry point.

Who this is for

You run a Bee node (mainnet or testnet) and want to know what's wrong without reading 50 endpoints worth of JSON. The pain points this tool exists to address:

  • "Why is my node unhealthy?" — answered by S1 with WHY tooltips encoding tribal knowledge from the bee-go source.
  • "Which batch is about to fail uploads?" — S2's worst-bucket fill bar + Enter-to-drill bucket histogram.
  • "Why am I unreachable?" — S7 distinguishes public-vs-private underlay and tracks AutoNAT reachability stability over a window.
  • "Why am I not earning rewards?" — S4's redistribution skip reasons reconstruct the truth LastPlayedRound doesn't tell you.
  • "Where is my upload stuck?" — S9's TagStatus ladder lights up the exact phase a stuck upload is in.
  • "Which of my nodes am I driving?" — Ctrl+N opens the v1.10 node picker over a list of every [[nodes]] entry; the top-bar metadata line always names the active profile + endpoint.
  • "Is anything running in the background?" — top-bar awareness chips (subs N, watch N, alerts ●, v1.10+) appear whenever a pubsub subscription, a :watch-ref daemon, or webhook alerting is active, and disappear when nothing is.

What this handbook is not

It's not a Bee operations manual. The deep model of how Swarm works — postage, neighborhoods, kademlia, redistribution — is best absorbed from the Bee book and the bee-go source. This handbook assumes you know that domain and just need to know how the cockpit surfaces it.

Versioning

bee-tui follows Semantic Versioning. The handbook on this site reflects whatever version is on main; the README's Status table tells you what's shipped and what's coming.