UPTERM(1)                        Upterm Manual                       UPTERM(1)



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.



OPTIONS
       --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.



OPTIONS INHERITED FROM PARENT COMMANDS
       --debug[=false]     enable debug level logging (log file:
       /build/.upterm/upterm.log).



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



SEE ALSO
       upterm(1)



HISTORY
       13-Oct-2026 Auto generated by spf13/cobra

Upterm 0.0.0+dev                   Oct 2026                          UPTERM(1)