UPTERM(1) Upterm Manual UPTERM(1)

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

upterm join [flags] TARGET

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.

--escape-char="~" Escape character for leaving (ESC-CHAR followed by . at the start of a line) or suspending (ESC-CHAR followed by ^Z, Unix only), or 'none' to disable.

-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, and a .pub selects that key in the SSH agent, as upterm host -i does. 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 targets. 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.

--debug[=false] enable debug level logging (log file: /build/.upterm/upterm.log).

  # Join a session, with the connect string the host shares:
  upterm join ssh://ID@uptermd.upterm.dev
  # The same; a target without a scheme is ssh:
  upterm join ID@uptermd.upterm.dev
  # Join over a WebSocket, through an HTTP proxy:
  upterm join wss://ID@uptermd.upterm.dev --proxy http://proxy.example.com:3128
  # Wait for a host that hasn't connected yet, with no 30 s limit:
  upterm join --wait ID@uptermd.upterm.dev

upterm(1)

13-Oct-2026 Auto generated by spf13/cobra

Oct 2026 Upterm 0.0.0+dev