UPTERM(1)                        Upterm Manual                       UPTERM(1)



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



SYNOPSIS
       upterm session set NAME [flags]



DESCRIPTION
       Change a session's join timeout.


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


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


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


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


       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.



OPTIONS
       -h, --help[=false]  help for set


       --join-timeout=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.



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



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



SEE ALSO
       upterm-session(1)



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

Upterm 0.0.0+dev                   Oct 2026                          UPTERM(1)