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/tools run 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.

• Host definitions sync too — safely. Domains reference hosts by canonical name; definitions travel with the project and materialize into ~/.ssh/config on 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. IdentityFile never 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

1. Machine A: ctrl+g → r → paste git@github.com:you/stool-data.git. Done — it pushes now and keeps syncing in the background.
2. Machine B: same URL → stool detects existing data and offers to adopt it.
3. Per-project sharing: open the project → ctrl+g → set its own remote. Teammates import it with ctrl+o and choose whether to sync ssh hosts or domains only (a machine-local choice, h to 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

MIT