README
¶
stool
A terminal UI for managing your servers: projects → domains → ssh hosts → runnable tools — with an encrypted password vault and git-based sync between machines and teammates.
Built with Bubble Tea.
What it does
-
Projects & domains — group domains by project; each domain is DNS-resolved, TLS-checked (validity + days to expiry) and annotated with its WHOIS netname, so you always see where it points and what state it's in. Filter any list with
/. -
SSH hosts — reads and writes your real
~/.ssh/config(no shadow state): create, edit and delete host blocks, including hand-written ones, edited in place. stool's own entries live in a clearly marked managed section. Comments supported both for domains and hosts. -
SSH sessions — one keypress from a domain to a shell. Hosts that only accept password auth are handled by a built-in PTY auto-type: passwords are stored in an encrypted vault (scrypt + AES-GCM) behind a master password, keyed by target host — never in plain text.
-
Tools — bash scripts in
~/.config/stool/toolsrun against selected domains/hosts: a single live session for one target, tiled tmux panes for many. Scripts declare scope/target in header comments and receive{{domain}},{{domains}},{{host}},{{ip}}placeholders;{{Question?|key}}prompts interactively and{{sshpubkey}}opens a picker over your local/agent public keys. Ships with starter tools (docker, nginx, certbot, ssh-key install). A run log lets you repeat past runs. -
AI tools — generate or fix a tool by describing it: stool hands the terminal to an interactive Claude Code session scoped to the tools directory. You can also open a Claude session against a host to debug it in place.
-
Git sync — two independent levels, usable together:
- everything (
~/.config/stool: projects, tools, caches, encrypted vault) to your own remote; - a single project to its own remote — for sharing with a team. Import
a shared project from just its URL (
ctrl+o).
Sync uses your system git (ssh keys, credential helpers — no tokens stored by stool), runs in the background (push ~10 s after a change, pull heartbeat ~60 s, plus on start/quit), and merges three-way at the domain level, so deletions propagate and concurrent edits don't conflict.
- everything (
-
Host definitions sync too — safely. Domains reference hosts by canonical name; definitions travel with the project and materialize into
~/.ssh/configon other machines. Hand-written blocks are never touched: a name collision creates a derived block (web1-myproject) with a canonical marker, and everything (sessions, tools, grouping) resolves through it transparently.IdentityFilenever syncs. Per machine you can opt a project out: sync domains only. -
Backups — one-key tar.gz snapshots of the whole config, restorable in place.
Install
go install github.com/bakl/stool@latest
or from a clone:
git clone https://github.com/bakl/stool.git
cd stool && go install .
Requirements: Go 1.25+, git (for sync), ssh. Optional: tmux
(multi-pane tool runs), claude CLI (AI features).
Run stool. Data lives in ~/.config/stool by default; point it anywhere
with stool -dir /path or STOOL_DIR=/path.
Keys (essentials)
| Screen | Keys |
|---|---|
| Projects | enter open/create · i/ctrl+o import by URL · ctrl+g git sync · ctrl+b backups · d delete |
| Domains | type to add · enter card · space select · r run tool · R refresh all · / filter · g/s group/sort · tab ssh hosts · ctrl+g project sync |
| Domain card | open session, run tool, link/unlink ssh host, comments, password auth + vault |
| SSH hosts | enter edit · o session · a ask Claude · r run tool · n new · c comment · d delete |
| Tools | enter run · e edit · n new · a AI create · f AI fix · l run log |
Sync setup
- Machine A:
ctrl+g→r→ pastegit@github.com:you/stool-data.git. Done — it pushes now and keeps syncing in the background. - Machine B: same URL → stool detects existing data and offers to adopt it.
- Per-project sharing: open the project →
ctrl+g→ set its own remote. Teammates import it withctrl+oand choose whether to sync ssh hosts or domains only (a machine-local choice,hto change later).
Conflicts inside a project are resolved automatically at the domain/host
level (newer edit wins, deletions propagate). Sync errors are shown in the
project header and logged to ~/.config/stool/sync.log.
Development
Tests first — see CLAUDE.md for the TDD workflow and architecture notes. The full check:
go build ./... && go vet ./... && gofmt -l . && go test ./... && go install .
UI logic is tested by driving real key sequences through the Bubble Tea
Update loop; all tests isolate HOME, so they never touch your actual
config or ~/.ssh/config.
License
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
aigen
Package aigen builds interactive `claude` CLI invocations — for generating or revising stool tool scripts, and for ad-hoc "do something on these hosts" sessions.
|
Package aigen builds interactive `claude` CLI invocations — for generating or revising stool tool scripts, and for ad-hoc "do something on these hosts" sessions. |
|
backup
Package backup creates and restores tar.gz snapshots of stool's config directory (~/.config/stool) — data.json, the encrypted vault, tool scripts, caches — so the whole setup can be saved and moved between machines.
|
Package backup creates and restores tar.gz snapshots of stool's config directory (~/.config/stool) — data.json, the encrypted vault, tool scripts, caches — so the whole setup can be saved and moved between machines. |
|
cfgdir
Package cfgdir is the single source of truth for stool's working directory (config, projects, tools, vault, caches).
|
Package cfgdir is the single source of truth for stool's working directory (config, projects, tools, vault, caches). |
|
gitsync
Package gitsync keeps stool data in git repositories and syncs them with remotes, using the SYSTEM git binary — so the user's own ~/.gitconfig, ssh-agent and credential helpers all just work, and stool never stores tokens or auth config of its own.
|
Package gitsync keeps stool data in git repositories and syncs them with remotes, using the SYSTEM git binary — so the user's own ~/.gitconfig, ssh-agent and credential helpers all just work, and stool never stores tokens or auth config of its own. |
|
probe
Package probe resolves domains/IPs and checks TLS certificate validity.
|
Package probe resolves domains/IPs and checks TLS certificate validity. |
|
runlog
Package runlog records a history of tool runs (what tool, on which targets, when) so they can be reviewed and repeated.
|
Package runlog records a history of tool runs (what tool, on which targets, when) so they can be reviewed and repeated. |
|
runner
Package runner executes stool tools as live terminal sessions (handing the real terminal over via tea.ExecProcess), so interactive tools like htop, top or vim work exactly as they would in a normal shell.
|
Package runner executes stool tools as live terminal sessions (handing the real terminal over via tea.ExecProcess), so interactive tools like htop, top or vim work exactly as they would in a normal shell. |
|
secrets
Package secrets implements an encrypted-at-rest password vault (~/.config/stool/secrets.enc) for optionally remembering ssh passwords when a host can't use key-based auth.
|
Package secrets implements an encrypted-at-rest password vault (~/.config/stool/secrets.enc) for optionally remembering ssh passwords when a host can't use key-based auth. |
|
sshauto
Package sshauto runs `ssh` inside a pseudo-terminal and auto-types a saved password the first time the remote asks for one, then hands the session over to the real terminal for fully interactive use.
|
Package sshauto runs `ssh` inside a pseudo-terminal and auto-types a saved password the first time the remote asks for one, then hands the session over to the real terminal for fully interactive use. |
|
sshconfig
Package sshconfig provides a minimal reader/writer for ~/.ssh/config that understands a "stool managed" section delimited by marker comments, so stool-created Host entries can be edited/removed without touching hand-written entries elsewhere in the file.
|
Package sshconfig provides a minimal reader/writer for ~/.ssh/config that understands a "stool managed" section delimited by marker comments, so stool-created Host entries can be edited/removed without touching hand-written entries elsewhere in the file. |
|
sshlaunch
Package sshlaunch builds the command used to hand off the terminal to an interactive `ssh` session via tea.ExecProcess.
|
Package sshlaunch builds the command used to hand off the terminal to an interactive `ssh` session via tea.ExecProcess. |
|
tools
Package tools discovers and runs user-defined scripts from ~/.config/stool/tools/.
|
Package tools discovers and runs user-defined scripts from ~/.config/stool/tools/. |
|
ui
Package ui implements the stool Bubble Tea application: project list, domain list (grouped/sorted by ssh host), ssh host management, and tool execution.
|
Package ui implements the stool Bubble Tea application: project list, domain list (grouped/sorted by ssh host), ssh host management, and tool execution. |
|
whois
Package whois looks up basic registration info (netname / mnt-by) for an IP address via the classic WHOIS protocol (port 43), following the IANA referral to the responsible regional registry, and caches results forever in ~/.config/stool/whois_cache.json — this data essentially never changes for a given IP, and re-querying on every render/resolve would be wasteful and slow.
|
Package whois looks up basic registration info (netname / mnt-by) for an IP address via the classic WHOIS protocol (port 43), following the IANA referral to the responsible regional registry, and caches results forever in ~/.config/stool/whois_cache.json — this data essentially never changes for a given IP, and re-querying on every render/resolve would be wasteful and slow. |