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	no	Keychain entry name for the password — or the passphrase of identity_file. Omit for a key-only host with an unencrypted key
identity_file	no	Path to a private key for SSH-key auth (see below)
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.

SSH key authentication

Set identity_file (in the host form's SSH key file field, or directly in hosts.toml) to authenticate with a private key instead of a password:

[[hosts]]
name = "edge-rtr-01"
hostname = "10.0.3.1"
username = "netops"
identity_file = "~/.ssh/id_ed25519"   # `~` / `$HOME` expanded
group = "Core"
# credential_ref omitted — the key has no passphrase

• Only the path is stored. The key material is never copied into hosts.toml or the keychain; the file stays on disk where you keep it.
• Passphrase-protected keys: store the passphrase in the keychain with Ctrl+K and name it in credential_ref. The same field thus holds a password for password hosts or a passphrase for key hosts.
• Auth order: public key (if identity_file is set) → password → keyboard-interactive → none, each tried only if the previous failed.
• Formats: OpenSSH, legacy PEM (PKCS#1 BEGIN RSA PRIVATE KEY), PKCS#8, and PuTTY .ppk. A key file readable by group/other triggers a non-blocking warning (chmod 600 recommended).