UPTERM(1)

💅 UPTERM(1) — the Upterm Manual, bestie edition

okay so you opened the manual page for upterm and honestly? good for you. this is the upterm-join girlie of the family and she's about to explain herself. 🎀

---

✨ NAME ✨

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

---

🌸 SYNOPSIS 🌸

upterm join [flags] TARGET

---

🦋 DESCRIPTION 🦋

So here's the vibe: upterm join joins a session as a guest, and — this is the iconique part — it rejoins it whenever the connection drops. no cap. it just keeps coming back. main character energy. 💅

TARGET is the connect string on the host's ➤ Join: line. that's it. that's the whole thing you need from them.

Once you're in a session, the keyboard shortcuts are lowkey essential, so pay attention bestie:

• ~. at the start of a line leaves (or whatever you set with --escape-char)
• on Unix, ~^Z suspends upterm join; fg resumes it 😴
• while it's waiting to rejoin, Enter retries at once and Ctrl+C stops

🚨 fr fr important: upterm join does not read ~/.ssh/config. so 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. if you need any of that, use -i, or plain ssh. not me being the bearer of bad news 😭

Another thing to know: a forced command (upterm host --force-command) starts again on each rejoin, and nothing the previous one did is undone. it's giving fresh start, but like, the files are still there. 🙈

Exit statuses, because exit codes are the love language of Unix:

• the session's status when one arrives
• 0 when you leave (~.)
• 130 when stopped
• 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 entirely. your escape hatch, literally 💖
• -h, --help[=false] — help for join. the classic.
• --known-hosts="~/.ssh/known_hosts" — known keys of relays. an unknown relay key gets shown to you for confirmation, just like ssh does it. 👑
• -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. slay, sensible defaults ✨
• --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. bestie, that part is not up for debate. 🚫
• --wait[=false] — on the first join, wait for a host as a rejoin does, with no 30 s limit. patience is a virtue and this flag has plenty 🧘‍♀️

---

🎀 OPTIONS INHERITED FROM PARENT COMMANDS 🎀

• --debug[=false] — enable debug logging (log file: /build/.upterm/upterm.log). a non-empty DEBUG turns it on too. for when you need to know why, you know? 🔍

---

🔥 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

look at her go. four examples, all of them eating. 🍓

---

💜 SEE ALSO 💜

upterm(1) — go read the parent, she misses you.

---

⭐ HISTORY ⭐

2-Nov-2026 — Auto generated by spf13/cobra. iconic of cobra honestly.

---

and that's the whole page bestie 💅✨ — this was the Upterm Manual, brought to you by Upterm 0.0.0+dev, dated Nov 2026. go forth and join some sessions. 🫶🎀