UPTERM(1)

✨ UPTERM(1) — the upterm manual, but make it make sense ✨

okay bestie, you're looking at upterm, and honestly? this page is about listing your sessions. stay with me, it's gonna slay 💅

---

🌸 NAME 🌸

upterm-session-list — literally just lists your running sessions, that's the whole vibe 🎀

🦋 SYNOPSIS 🦋

upterm session list [flags]

💖 DESCRIPTION 💖

So the way this works: it lists all your running sessions, one row per session, and each row shows the name, the status, the session ID, the command and the relay. That's five lil pieces of info per row, no cap ✨

The session this terminal is currently in? That one gets a * next to it — and it knows which one that is because of $UPTERM_ADMIN_SOCKET. iykyk 💫

Where do these sessions even come from? The records in:

/build/.upterm/results

and yes, sessions that were started under a different XDG_RUNTIME_DIR show up here too, we're inclusive like that 🫶

⚠️ okay this part matters, listen: listing deletes the records of sessions that ended more than 7 days ago. and after that? upterm session info and upterm session wait literally no longer know those sessions exist. gone. ghosted. 💀 so don't come crying to me about your week-old session.

If you pass -o json, you get a JSON array where each element is exactly what upterm session info NAME -o json prints, one per running session. and if nothing's running? you get []. an empty array. a lil empty nest 🍓

Exit status: 0 normally. 1 when the records directory can't be read, or if there's a usage or configuration error. Also — a session whose own record can't be read just gets left out of the list entirely, like it wasn't invited to the party 🙈

👑 OPTIONS 👑

• -h, --help[=false] — help for list. classic. iconic.
• --hide-client-ip[=false] — hides the guests' IP addresses from upterm's output. When it's not set (whether by flag, environment, or config file), the IPs are only hidden in CI. And --hide-client-ip=false? that shows them in CI too, so like, be aware bestie 🌈
• -o, --output="" — output format. the value is json, and it's command line only (so don't try to sneak it into a config file) 🔥

🧚 OPTIONS INHERITED FROM PARENT COMMANDS 🧚

• --debug[=false] — turns on debug logging, and the log file is /build/.upterm/upterm.log. also, a non-empty DEBUG turns it on too, so you've got options ⭐

💜 EXAMPLE 💜

  # List the running sessions:
  upterm session list

  # As JSON, for a script:
  upterm session list -o json

🌺 SEE ALSO 🌺

upterm-session(1) — go read that one next, bestie 🦋

🎀 HISTORY 🎀

2-Nov-2026 — Auto generated by spf13/cobra. not me being auto-generated 😭

---

and that's the page!! mwah 💋

Upterm 0.0.0+dev — Nov 2026 🫶 periodt.