Protocol Verbs

Sessions

Sessions: part of the Protocol Verbs of TUIOS.

This page is one part of docs/protocol-verbs.md of the tuios repository. The Protocol Verbs page lists every part.

detach-client Added in v0.9.0

Detach attached clients from their sessions, as tmux detach-client does. The session keeps running, and each detached client exits with a message. With client, that client. With session, every client of the session. With neither, the client used last in the caller's pane's session, else in the only session with a client. all_other keeps that one client and detaches the rest of its session.

ParamTypeRequiredDefaultDescription
clientstringId of the client to detach, from list-clients.
sessionstringSession whose clients to detach.
all_otherboolfalseKeep the named client, or the client used last, and detach every other client of its session.
Result fieldTypeDescription
detachedarrayIds of the clients that were detached.
{"id":1,"verb":"detach-client","params":{"client":"c3"}}
{"id":1,"verb":"detach-client","params":{"session":"work"}}
{"id":1,"verb":"detach-client","params":{"session":"work","all_other":true}}

display-env Added in v0.9.3

Report the display a new pane of the session gets now: WAYLAND_DISPLAY naming the session's Wayland link, and DISPLAY and XAUTHORITY of the newest local client. It is empty unless [daemon] display is follow, the daemon has no display of its own, and a local client with a display is attached.

ParamTypeRequiredDefaultDescription
sessionstringSession whose display to report.
Result fieldTypeDescription
sessionstringSession name.
followboolTrue when [daemon] display is follow and the daemon has no display of its own.
ownboolTrue when the daemon has a WAYLAND_DISPLAY or DISPLAY of its own. Its panes keep it, and the follow is off.
linkstringThe session's Wayland link. It exists only while an attached client has a Wayland socket.
targetstringThe client socket the link points at. Absent when there is no link.
envobjectThe variables a new pane gets: WAYLAND_DISPLAY, DISPLAY and XAUTHORITY, each only when set.
{"id":1,"verb":"display-env","params":{"session":"work"}}

kill-session Added in v0.8.0

Terminate a session and every window in it.

ParamTypeRequiredDefaultDescription
sessionstringSession to terminate.
{"id":1,"verb":"kill-session","params":{"session":"work"}}

list-clients Added in v0.9.0

List every connection to the daemon and the session it is attached to.

No params.

Result fieldTypeDescription
clients[]objectOne row per connection: client_id, kernel peer pid, and current session name (empty while detached).
{"id":1,"verb":"list-clients"}

list-sessions Added in v0.8.0

List all sessions the daemon holds.

No params.

{"id":1,"verb":"list-sessions"}

new-session Added in v0.8.0

Create a session in the daemon, with its first window. The session runs detached until a client attaches to it.

ParamTypeRequiredDefaultDescription
namestringName for the new session. Omit to have one generated. A name the daemon already holds is refused.
widthint80Nominal width in columns. An attached client replaces it with its own viewport.
heightint24Nominal height in rows. An attached client replaces it with its own viewport.
windowbooltrueCreate the first window. Pass false for an empty session you place every window in yourself.
window_namestringName for the first window. Omit to use the shell's title.
cwdstringDirectory the session's windows start in: the first window, and any later one with no directory to inherit. Omit to use the daemon's.
command[]stringArgv to exec as the first window's process instead of a shell. No shell parses it, so nothing needs quoting.
spacestringSpace to file the session under, as set-session-space does: trimmed, then held to the session name rules and 64 bytes. Omit for none.
envobjectEnvironment variables for the window's process, name to value, on top of the daemon's. TUIOS_ names, TMUX and TMUX_PANE are refused, and a call from another machine may not pass env. Not for a window on another machine. Not saved: a restored pane starts without it.
Result fieldTypeDescription
sessionstringName of the new session. Use it as the session parameter of every later call.
spacestringSpace the session is filed under. Absent when space was not given.
session_idstringId of the new session.
widthintNominal width the session was created at.
heightintNominal height the session was created at.
windowsintHow many windows the session holds: 1, or 0 when window was false.
window_idstringId of the first window. Absent when window was false.
window_namestringName of the first window. Absent when window was false.
pty_idstringId of the first window's PTY. Absent when window was false.
{"id":1,"verb":"new-session"}
{"id":1,"verb":"new-session","params":{"name":"work","window_name":"build","cwd":"/src/api"}}
{"id":1,"verb":"new-session","params":{"name":"empty","window":false}}
{"id":1,"verb":"new-session","params":{"name":"ledger","space":"accounts"}}

rename-session Added in v0.8.2

Rename a session. The new name is what ls lists, what attach and every verb take, and what new panes get as TUIOS_SESSION. The old name still reaches the session for panes that already run. The session's display label is cleared.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
namestringThe new name. It must be unique, must not be empty, and must not hold a slash, a backslash or a control character.
Result fieldTypeDescription
typestringAlways session_renamed.
sessionstringThe session's new name.
old_namestringThe name it had before. It still reaches the session for panes that already run.
{"id":1,"verb":"rename-session","params":{"session":"work","name":"payments"}}

session-info Added in v0.8.0

Report details about one session.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
{"id":1,"verb":"session-info","params":{"session":"work"}}

set-session-accent Added in v0.8.0

Set a session's accent colour. Every attached client shares it, and it survives a reattach.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
accentstringAn ANSI colour name ("cyan", "bright blue") or a #rrggbb value, recorded verbatim. Omit or pass an empty string to clear it and let the client pick the session's colour.
{"id":1,"verb":"set-session-accent","params":{"session":"work","accent":"cyan"}}

set-session-name Added in v0.8.0

Set a session's display label. The session keeps its name for addressing, persistence and TUIOS_SESSION. To change the name, use rename-session.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
namestringDisplay label for the session. Omit or pass an empty string to clear it and fall back to the session name.
{"id":1,"verb":"set-session-name","params":{"session":"work","name":"Payments API"}}

set-session-space Added in v0.10.0

File a session under a space, a named group of related sessions that tuios ls and the sidebar list together, or mark it global. A space exists while at least one session is in it. It survives a daemon restart with the session. A global session is in no space, and filing one is refused unless global is false.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
spacestringThe space's name. Surrounding whitespace is trimmed, and the rest follows the session name rules (no slash, backslash or control character) and is at most 64 bytes. Omit or pass an empty string to take the session out of any space.
globalboolTrue marks the session global: it holds panes from more than one machine, is listed in its own group, and a new window in it asks which machine to run on. It takes the session out of its space, and is refused with a space. False takes the mark off before the space is set. Omit to leave the mark as it is.
Result fieldTypeDescription
typestringAlways session_space_set.
sessionstringThe session's name.
spacestringThe space the session is in now, empty for none.
globalboolWhether the session is global now.
{"id":1,"verb":"set-session-space","params":{"session":"work","space":"payments"}}
{"id":1,"verb":"set-session-space","params":{"session":"work","space":""}}
{"id":1,"verb":"set-session-space","params":{"session":"work","global":true}}

ssh-agent-path Added in v0.9.0

Report the session's ssh agent link: the path that new panes get as SSH_AUTH_SOCK while [daemon] ssh_agent is follow, and the client socket it points at now.

ParamTypeRequiredDefaultDescription
sessionstringSession whose link to report.
Result fieldTypeDescription
sessionstringSession name.
pathstringThe link. It exists only while an attached client has an agent socket.
followboolTrue when [daemon] ssh_agent is follow.
targetstringThe client socket the link points at. Absent when there is no link.
{"id":1,"verb":"ssh-agent-path","params":{"session":"work"}}

switch-session Added in v0.9.0

Switch an attached client to another session in place, as go-to does. The client is the one named by client, else the one showing session, else the one showing the caller's own session from a pane, else the only one attached.

ParamTypeRequiredDefaultDescription
namestringSession to switch to.
hoststringMachine from the client's [hosts] table that holds the session. Omit, or local, for this daemon.
createboolfalseCreate the session when it does not exist.
cwdstringWith create, the directory the new session's windows start in.
sessionstringSession the client to switch shows.
clientstringId of the client to switch, from list-clients.
Result fieldTypeDescription
sessionstringSession the client now shows.
hoststringMachine the session is on. Absent for this daemon.
client_idstringId of the client that switched.
createdboolTrue when create made the session on this daemon.
alreadyboolTrue when the client already showed the session. Nothing changed.
{"id":1,"verb":"switch-session","params":{"name":"api"}}
{"id":1,"verb":"switch-session","params":{"name":"api","create":true,"cwd":"/src/api"}}
{"id":1,"verb":"switch-session","params":{"name":"api","host":"build","session":"work"}}

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page