ssh_host_update
Update fields on an existing SSH host configuration to safely rotate passwords, change ports, or adjust settings without editing the plaintext TOML file.
Instructions
Update one or more fields of an existing host configuration - this is the safe way to rotate a password, change a port, or adjust other settings without ever needing to read or hand-edit the host configuration TOML file (which stores every host's credentials in plaintext - never read it directly; this tool, ssh_conn_add_host, ssh_host_remove, and ssh_host_list cover everything you should need).
Only the fields you pass are changed - any parameter left at its default
(omitted/None) keeps its current value. To clear a field entirely (e.g. drop a
password when switching a host to key-only auth), pass an empty string "" rather
than omitting it. user/host themselves can't be changed this way (that changes
the 'user@host' key identity) - remove and re-add instead if you need that.
Prefer this over ssh_host_remove + ssh_conn_add_host for adjusting an existing host: remove+re-add loses every field you don't explicitly resupply, since ssh_conn_add_host has no knowledge of the entry it just deleted.
host_name may be either the 'user@hostname' key or a configured alias - resolved
the same way as ssh_conn_connect.
Warn the user that any new password/passphrase value passed here will be visible to the LLM, the same caveat as ssh_conn_add_host.
Returns:
On success: {'status': 'success', 'message', 'key', 'updated_fields' (list of field names that were actually changed)}. On failure (the update would leave
neither a password nor a keyfile set, or a duplicate alias):
{'status': 'error', 'error': <message>} - not a raised exception.
Raises:
SshError: If host_name doesn't resolve to any configured host (tried as both
key and alias).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| port | No | New SSH port. Omit to leave unchanged | |
| alias | No | New alias. Omit to leave unchanged; pass an empty string to clear it | |
| keyfile | No | New SSH private key path. Omit to leave unchanged; pass an empty string to clear it (e.g. when switching to password-only auth) | |
| password | No | New password. Omit to leave unchanged; pass an empty string to clear it (e.g. when switching to key-only auth) | |
| host_name | Yes | The 'user@hostname' key or alias of the host to update | |
| description | No | New description. Omit to leave unchanged; pass an empty string to clear it | |
| sudo_password | No | New sudo password. Omit to leave unchanged; pass an empty string to clear it | |
| key_passphrase | No | New passphrase for the SSH key. Omit to leave unchanged; pass an empty string to clear it |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||