---
name: "upterm-session-list"
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-session-list"
---

# upterm-session-list(1)

List running sessions

## NAME

upterm-session-list - List running sessions

## SYNOPSIS

**upterm session list \[flags\]**

## DESCRIPTION

List the running sessions, one row each: name, status, session ID, command and relay. \* marks the session this terminal is in ($UPTERM\_ADMIN\_SOCKET).

The sessions come from the records in: /build/.upterm/results Sessions started under another XDG\_RUNTIME\_DIR are listed too. Listing deletes the records of sessions that ended more than 7 days ago, after which 'upterm session info' and 'upterm session wait' no longer know them.

\-o json prints a JSON array of what 'upterm session info NAME -o json' prints, one per running session, and \[\] when none is running.

Exit status: 0, or 1 when the records directory can't be read, or for a usage or configuration error. A session whose own record can't be read is left out of the list.

## OPTIONS

**-h**, **--help**\[=false\]\
 	help for list

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

**-o**, **--output**=""\
 	Output format: json (command line only)

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

```
  # List the running sessions:
  upterm session list
  # As JSON, for a script:
  upterm session list -o json
```

## SEE ALSO

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

## HISTORY

27-Oct-2026 Auto generated by spf13/cobra