SSH Keys

Three-tier resolution. Precedence: --ssh-key flag > host.ssh_key in hosts.toml > default derivation.

Tier	Source	Example
1	--ssh-key flag (one-off)	auberge backup create --host my-vps --ssh-key /path/to/key
2	host.ssh_key in ~/.config/auberge/hosts.toml	auberge host add my-vps --ssh-key ~/.ssh/custom
3	Derived: ~/.ssh/identities/{hostname}/{user}	auberge ssh keygen --host my-vps --user ansible

~/.config/auberge/hosts.toml

[[hosts]]
name = "my-vps"
address = "10.0.0.1"
user = "ansible"
port = 22
ssh_key = "~/.ssh/identities/custom_key"

Tip

When the derived path doesn’t exist, commands fail and point at auberge ssh keygen. The only interactive picker lives in auberge ssh add-key, which scans ~/.ssh/, ~/.ssh/identities/, and ~/.ssh/identities/<host>/ to choose its connection and authorize keys; the selection is never saved to hosts.toml.

SSH Include

Every write of hosts.toml regenerates ~/.ssh/config.d/auberge.conf from it — host add|edit|rename|remove|detect-tailscale-ip, and anything added later, because regeneration is bound to the roster write rather than to the command. One Host block per entry with HostName, Port, User, IdentityFile (tiers 2–3 above), IdentitiesOnly yes, HostKeyAlias (the host’s name), and StrictHostKeyChecking accept-new. The file is CLI-owned — hand edits are lost on the next host subcommand.

HostKeyAlias is also what every CLI connection is checked under, so ~/.ssh/known_hosts needs an entry keyed by the host’s name rather than its address. Reading hosts.toml copies the address-keyed entry onto the name — every command does this, not just the ones that write the roster, because the trigger has to be the binary rather than an edit you may never make. The original entry is left alone.

HostName, Port and User are the resolved route to the host, the same one the CLI’s own ssh, scp, rsync and ansible connections use. Interactive ssh <name> and auberge therefore cannot take different routes to one host — a hand-written stanza keyed on the old address no longer intercepts one and not the other.

Activate the aliases once:

# first line of ~/.ssh/config
Include ~/.ssh/config.d/auberge.conf

The CLI never writes ~/.ssh/config; it prints this line as a hint while missing. ssh keeps the first value it obtains per option, so the Include position decides precedence: on the first line, the generated blocks beat stale manual blocks for the same hosts.

Importing from ~/.ssh/config

auberge host add (no args) detects an existing ~/.ssh/config and offers to import host name, address, user, port, and IdentityFile from any host block.

Common errors

Error	Fix
SSH key not found	auberge ssh keygen --host <host> or fix the path with auberge host edit <host>
Configured SSH key not found (warning)	Falls back to the derived path; fix the stale ssh_key with auberge host edit <host>
No SSH private keys found	auberge ssh keygen --host <host> or copy keys into ~/.ssh/identities/
Permissions 0644 are too open	chmod 600 /path/to/key