---
name: "upterm-attach"
section: "1"
platform: "linux"
package: "upterm"
version: "0.40.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/upterm-attach"
---

# upterm-attach(1)

Attach this terminal to a running session

## NAME

upterm-attach - Attach this terminal to a running session

## SYNOPSIS

**upterm attach \[NAME\|ID\] \[flags\]**

## DESCRIPTION

Attach this terminal to a running session, given 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. Without one, the only running session is attached to; with several, 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.

Keys, 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\
   \~^Z   suspend this terminal (Unix); fg resumes it\
   \~~    send a ~

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

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.

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.

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

## SEE ALSO

**[upterm(1)](/upterm/1.md)**

## HISTORY

27-Oct-2026 Auto generated by spf13/cobra