Reference

upterm-join(1)

Join a session as a guest, and rejoin it after a drop

NAME

upterm-join - Join a session as a guest, and rejoin it after a drop

SYNOPSIS

upterm join [flags] TARGET

DESCRIPTION

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.

OPTIONS

--escape-char="~"
The character that starts upterm's keys at the start of a line, or 'none' to turn them off.

-h, --help[=false]
help for join

--known-hosts="~/.ssh/known_hosts"
Known keys of relays. An unknown relay key is shown for confirmation, as ssh does.

-i, --private-key=[~/.ssh/id_{ed25519,ed25519_sk,ecdsa,ecdsa_sk,dsa,rsa}]
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.

--proxy=""
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[=false]
Accept an unknown relay key and record it without asking (similar to SSH's StrictHostKeyChecking=accept-new). A changed key is still refused.

--wait[=false]
On the first join, wait for a host as a rejoin does, with no 30 s limit.

OPTIONS INHERITED FROM PARENT COMMANDS

--debug[=false]
Enable debug logging (log file: /build/.upterm/upterm.log). A non-empty DEBUG turns it on too.

EXAMPLE

  # 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]

SEE ALSO

upterm(1)

HISTORY

27-Oct-2026 Auto generated by spf13/cobra