upterm join
Join a session as a guest, and rejoin it after a drop
Synopsis
Join a session as a guest, and rejoin it whenever the connection drops. TARGET is the connect string on the host’s ➤ Join: line.
In a session, ~. at the start of a line leaves (or –escape-char), and on Unix ~^Z suspends upterm join; fg resumes it. While it waits to rejoin, Enter retries at once and Ctrl-C stops.
upterm join doesn’t read ~/.ssh/config: per-host IdentityFile, User and ProxyJump don’t apply, the target can’t be a host alias, and FIDO keys work only through the agent. Use -i, or plain ssh, for those.
A forced command (upterm host –force-command) starts again on each rejoin; nothing the previous one did is undone.
Exits with the session’s status when one arrives, 0 when you leave (~.), 130 when stopped, and 255 when it can’t join, including a usage or configuration error.
upterm join [flags] TARGET
Examples
# Join a session, with the connect string the host shares:
upterm join ssh://[email protected]
# The same; a target without a scheme is ssh:
upterm join [email protected]
# Join over a WebSocket, through an HTTP proxy:
upterm join wss://[email protected] --proxy http://proxy.example.com:3128
# Wait for a host that hasn't connected yet, with no 30 s limit:
upterm join --wait [email protected]
Options
--escape-char string The character that starts upterm's keys at the start of a line, or 'none' to turn them off. (default "~")
-h, --help help for join
--known-hosts string Known keys of relays. An unknown relay key is shown for confirmation, as ssh does. (default "~/.ssh/known_hosts")
-i, --private-key strings Identity files. Supplying this makes the list the whole set, like OpenSSH's IdentitiesOnly: each file must load, a public key (.pub) file selects that key in the SSH agent, and other agent keys are not offered. By default, the agent's keys are offered first, then the listed files that exist and the agent doesn't hold, and a generated key when there are neither. (default [~/.ssh/id_{ed25519,ed25519_sk,ecdsa,ecdsa_sk,dsa,rsa}])
--proxy string HTTP proxy to reach the relay through (e.g. http://proxy.example.com:3128). Works with ssh, ws and wss relays. Without it, ws and wss use HTTPS_PROXY/HTTP_PROXY, and ssh goes direct.
--skip-host-key-check Accept an unknown relay key and record it without asking (similar to SSH's StrictHostKeyChecking=accept-new). A changed key is still refused.
--wait On the first join, wait for a host as a rejoin does, with no 30 s limit.
Options inherited from parent commands
--debug Enable debug logging (log file: /home/user/.local/state/upterm/upterm.log). A non-empty DEBUG turns it on too.
SEE ALSO
- upterm - Instant Terminal Sharing