Configuration

Configuration

Config lives in ~/.config/gukab/:

File	Purpose
hosts.toml	Hosts and groups
automations.toml	Reusable macros and expect rules (see Automations)
known_hosts	Trusted SSH host-key fingerprints (see Security)
log/<host>/<timestamp>.log	Per-session transcripts

Copy-paste starting points: examples/hosts.toml and examples/automations.toml.

hosts.toml

Groups (optional)

Each group is a collapsible header in the list. icon is any glyph you paste — a Nerd Font symbol, an emoji, or "" for none.

[[groups]]
name = "Core"
icon = ""      # paste a glyph here, or leave empty

Hosts

[[hosts]]
name = "core-sw-01"        # label shown in the list
hostname = "10.0.0.1"      # IP or DNS name
port = 22                  # optional, defaults to 22
username = "admin"
credential_ref = "core"    # keychain entry holding the password (see below)
group = "Core"             # optional; omit for an ungrouped host
on_connect = ["en"]        # optional; macro keys to run right after connecting

Field	Required	Notes
name	yes	Display label
hostname	yes	IP or DNS
port	no	Default 22
username	yes	SSH user
credential_ref	yes	Keychain entry name for the password
group	no	Group membership
on_connect	no	Macro keys auto-run on connect
macros / expects	no	Per-host automation (see Automations)

Credentials

Passwords are never stored in hosts.toml — they live in the OS keychain. Add one in the TUI with Ctrl+K (reference + password), or from a shell:

security add-generic-password -s gukab -a <credential_ref> -w '<password>' -U   # macOS

credential_ref in a host ties it to the keychain entry of the same name.