.nh
.TH "UPTERM" "1" "Oct 2026" "Upterm 0.0.0+dev" "Upterm Manual"

.SH NAME
upterm-session-set - Change a session's join timeout


.SH SYNOPSIS
\fBupterm session set NAME [flags]\fP


.SH DESCRIPTION
Change a session's join timeout.

.PP
--join-timeout D ends the session D from now unless a guest joins first. It
replaces any join timeout already set, including one given to
\&'upterm host --join-timeout', so each call restarts the window: running it
again with the same duration extends the deadline. 0 disables it. Before the
session is ready, the timeout counts from readiness.

.PP
A guest who joins, however briefly and whether by terminal or SFTP, claims the
session: the automatic join timeout is disabled for the rest of its life, and
a later set says so and changes nothing. After that, nothing ends the session
but its command exiting or 'upterm session stop'.

.PP
\&'upterm session wait NAME' blocks until the session ends; interrupting it
leaves the session running. 'upterm session stop NAME' ends it.

.PP
Durations are shown compact and normalised: 90m shows as 1h30m.

.PP
Exits 0 when the session took the change, was already claimed, is ending, or
has already ended, 4 when no session has the name, and 1 for any other
failure -- including a change that could not be confirmed, which may still
have taken effect: running set again restarts the window, and 'upterm session
info NAME' shows what the session holds.


.SH OPTIONS
\fB-h\fP, \fB--help\fP[=false]
	help for set

.PP
\fB--join-timeout\fP=0s
	End the session this long from now unless a guest joins first (e.g. 10m). Replaces any join timeout already set; 0 disables it.


.SH OPTIONS INHERITED FROM PARENT COMMANDS
\fB--debug\fP[=false]
	enable debug level logging (log file: /build/.upterm/upterm.log).


.SH EXAMPLE
.EX
  # Debug a failed build: open the session first, give people 10 minutes to
  # join only if the build fails, and keep the build's exit status. Safe under
  # set -e and in zsh, where $status is read-only:
  upterm host --detach --accept --name build -- bash
  build_exit_code=0
  make || build_exit_code=$?
  if [ "$build_exit_code" -ne 0 ]; then
    # Ten minutes for someone to join; once they have, it runs until they exit.
    if upterm session set build --join-timeout 10m; then
      upterm session wait build || true
    fi
  fi
  upterm session stop build || true   # ends it either way; never masks the build's result
  exit "$build_exit_code"

  # Give 20 more minutes from now, replacing the current window:
  upterm session set build --join-timeout 20m

  # Turn the join timeout off:
  upterm session set build --join-timeout 0
.EE


.SH SEE ALSO
\fBupterm-session(1)\fP


.SH HISTORY
6-Oct-2026 Auto generated by spf13/cobra