UPTERM(1)

💖 UPTERM(1) — the Upterm Manual 💖

🎀 NAME 🎀

upterm-attach — attach this terminal to a running session. periodt. ✨

🦋 SYNOPSIS 🦋

upterm attach [NAME|ID] [flags]

🌸 DESCRIPTION 🌸

Okay bestie, upterm attach attaches this terminal to a running session, and you point at it with its name or session ID. NAME|ID is the session's name (the one upterm host printed, or --name gave it) or its session ID; upterm session list shows both. No name or ID? Then the only running session gets attached to; if there are several, you gotta give one. 💅

The session keeps running when this terminal detaches, and any number of terminals can attach to it over time. Everything but the keys below is sent to the session as typed, and a SIGTERM or SIGHUP detaches.

The keys only count at the start of a line (--escape-char changes the ~, or turns them off):

• ~. — detach: the session keeps running; upterm attach NAME reattaches and upterm session stop NAME ends it.
• ~? — show the session's status and keys, in this terminal only; the program may need its own redraw afterwards.
• ~a — review a guest's request, in the primary local terminal, and answer with the confirmation it shows as CODE: y CODE Enter allows it on its connection; a CODE Enter allows that guest every request of its kind (commands, files or forwards) until the session ends; n CODE Enter denies it; Esc decides later, and the request still expires.
• ~^Z — suspend this terminal (Unix); fg resumes it.
• ~~ — send a ~; ~~a sends literal ~a.

Through an outer ssh connection, ssh's own ~ escapes come first: type ~~., ~~?, ~~a and ~~^Z, or connect with ssh -e none and type them plain. 🐚

With --escape-char none or without a capable primary local terminal, interactive approval is unavailable; requests without a grant are denied. That's the rule, bestie. 🚫

On Unix you can also suspend with ~^Z, run upterm session info NAME, and return with fg. A session that keeps producing output while this terminal is suspended may disconnect it (254 below); upterm attach NAME brings it back. iykyk.

Exit status: 0 after a detach; the session's status once it ends (0 when no guest joined within its join timeout; 1 when it was stopped or ended by a signal); 254 if this terminal was disconnected; 255 if it could not attach, including a usage or configuration error. Save this for the group chat.

✨ 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 attach.
• --hide-client-ip[=false] — hide guests' IP addresses from upterm's output. When it isn't set (by flag, environment or config file), they are hidden in CI only; --hide-client-ip=false shows them there too.

🌈 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 🍓

# Attach to the session named build-shell:
upterm attach build-shell

# Attach to a session by its session ID:
upterm attach d3k5fia7m4us73ehblug

# Attach with no escape character, so every keystroke reaches the session:
upterm attach build-shell --escape-char none

These examples ate, no cap. 🍓

🧚 SEE ALSO 🧚

upterm(1) — go say hi to the parent page, slay. 🫶

💀 HISTORY 💀

2-Nov-2026 — auto generated by spf13/cobra. Not me writing lore, that's the receipt. 💀

---

Made with 💖 by Upterm 0.0.0+dev, dated Nov 2026. Byeee bestie, go attach something iconic. 👑