Protocol Verbs

Windows

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

close-window Added in v0.8.0

Close a window.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
{"id":1,"verb":"close-window","params":{"session":"work","window":"build"}}

close-workspace Added in v0.8.3

Close every pane on a workspace, like tmux kill-window. Scratch panes stay unless the workspace named is their scratch workspace. A pane that calls it needs the admin grant.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
workspaceintWorkspace whose panes to close. Omit for the current one.
Result fieldTypeDescription
workspaceintThe workspace whose panes were closed.
closed[]stringIds of the windows that were closed, in window order.
{"id":1,"verb":"close-workspace","params":{"session":"work","workspace":2}}

focus-window Added in v0.8.0

Move the focus to a pane. Pass exactly one of window, relative or direction.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name to focus. Switches to that window's workspace.
relativestringFocus the next or previous window on the current workspace. One of next or prev.
directionstringFocus the neighbouring pane in this direction. Needs an attached client. One of left, right, up or down.
Result fieldTypeDescription
focused_window_idstringId of the window that now has the focus.
current_workspaceintWorkspace now showing.
windowobjectThe focused window's full row, in the same shape list-windows reports.
{"id":1,"verb":"focus-window","params":{"session":"work","window":"build"}}
{"id":1,"verb":"focus-window","params":{"session":"work","relative":"next"}}

get-window Added in v0.8.0

Describe one window, as the client protocol's GetWindow does: an attached client answers with its cursor and process fields, and with none attached the daemon answers with the window's list-windows entry. It is a read, which a pane holding read may call on its own 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.
windowstringWindow id or name. Omit to target the focused window.
Result fieldTypeDescription
window_idstringId of the window.
display_namestringIts name as shown: the custom name, or the shell's title.
agent_statestringIts agent state.
{"id":1,"verb":"get-window","params":{"session":"work"}}

list-windows Added in v0.8.0

List the windows in a session. The list carries shell, the base name of the shell a new pane in the session runs. Each window carries a host when its process runs on another machine, and omits it when the process is on this one. A window whose shell marks its commands with OSC 133 also carries at_prompt, command_seq, marks_commands (the shell has sent a command-start mark), prompt_marks_only when it ran a command without one, running_cmdline while a command runs, and last_cmdline, last_exit_code and last_duration_ms once one has finished. A pane given grants of its own carries them as grants; a pane on the default of [agents.permissions] omits it. A pane whose process runs on this machine carries pid, the process it started, and tty, its terminal device. A zoomed window carries zoomed, and a floating window carries floating. A window whose program named itself with OSC 1 carries icon_name, the name an unnamed workspace shows while the window is its active one.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
railboolfalseAlso list the rail pane, the pane a client draws in its rail's pane section. It carries rail, the command line it runs.
{"id":1,"verb":"list-windows","params":{"session":"work"}}

move-window Added in v0.8.0

Move a window to another workspace, or with to_session to another session, or with beside next to another pane. The program in the window keeps running, and the window keeps its id and its scrollback.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow to move. Omit to move the focused one.
workspaceintWorkspace number to move the window to. Required without to_session. With to_session, omit it to use the workspace the destination shows.
followboolfalseSwitch to that workspace after moving. With to_session, focus the window in the destination.
to_sessionstringSession to move the window to, by name or id. A popup, a scratch pane, a TML pane and a pane on another machine cannot move (pane_not_movable). The window's own session is refused (same_session).
besidestringPane to put the window next to, in the layout of that pane's workspace. Without window, the caller's own pane moves. Not with workspace, to_session or follow. Works with no client attached.
sidestringrightWith beside: the side of that pane the window takes. One of left, right, up or down.
ratiointWith beside: the window's share of the space, in percent, from 1 to 99. Omit for an even split.
Result fieldTypeDescription
window_idstringId of the window that moved. A move to another session keeps it.
sessionstringSession the window is in now.
from_sessionstringSession the window left. Only with to_session.
from_workspaceintWorkspace it was on.
workspaceintWorkspace it is on now.
current_workspaceintWorkspace the window's session shows after the call. It changes only when follow is true.
{"id":1,"verb":"move-window","params":{"session":"work","window":"build","workspace":2,"follow":true}}
{"id":1,"verb":"move-window","params":{"session":"work","window":"build","to_session":"review"}}
{"id":1,"verb":"move-window","params":{"session":"work","window":"review","beside":"build","side":"down","ratio":30}}

new-window Added in v0.8.0

Create a new window, optionally on a named workspace and in a named directory.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
namestringName for the new window. Omit to use the shell's title.
workspaceintWorkspace number to create the window on. Omit for the calling pane's workspace, else the one the session shows.
cwdstringDirectory to start the shell in. Omit to use the calling pane's directory, or outside a pane the focused pane's.
focusbooltrueFocus the new window. Pass false to leave the focus where it is.
command[]stringArgv to exec as the window's process instead of a shell. No shell parses it, so nothing needs quoting. The window closes when the program exits, unless keep_open is set.
hoststringRun the window's process on another machine, named as it is in the [hosts] config table. The window belongs to this session and is drawn and sized here; only the process is there. Omit, or pass "local", for this machine.
grants[]stringWhat the new pane may do through tuios: read, write, fan, respond, admin, or none. Omit for the default of [agents.permissions], or, from a pane without admin, the calling pane's own grants. A pane may give only what it holds, and admin does not include respond. A window on another machine holds what that machine gives it. One of read, write, fan, respond, files, task, admin or none.
close_on_exitboolfalseClose the window when its process exits, also with no client attached. Without it, a detached session keeps a window whose process exited until something closes it.
keep_openboolfalseKeep the window after its process exits. The window shows a line with the exit status under the last output, and stays until something closes it. Cannot be used with close_on_exit.
waitboolfalseAnswer when the process exits, with exit_code. Use keep_open too to read the output after the exit. Not for a window on another machine.
timeoutint0With wait: milliseconds to wait before failing with the timeout code. 0 waits with no limit.
kindstringterminalWhat draws the window: terminal, or view, web or app for a window a native renderer (tuios-gpui) draws itself. Such a window runs a placeholder that shows its uri in a terminal client. One of terminal, view, web or app.
uristringWhat a view, web or app window shows, such as tuios://review/<pane> or a page. Needed for those kinds.
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.
shell_integrationstringWhether the pane's bash or zsh starts with OSC 133 prompt marks on: auto or off. Omit it to use [shell] integration. Has no effect on a window that runs a command. Not saved: a restored pane uses the config. One of auto or off.
Result fieldTypeDescription
window_idstringId of the new window. Use it to address the window in later calls.
hoststringThe machine the window's process runs on. Omitted for a window on this machine.
namestringThe window's name, generated when none was given.
workspaceintWorkspace the window was created on.
pty_idstringId of the window's PTY.
focusedboolWhether the window took the focus.
unplacedboolTrue while the window's geometry is a placeholder. An attached client replaces it. On a detached session it stays true and the reported size is nominal.
keep_openboolTrue when the window stays after its process exits. Omitted otherwise. A daemon that does not know keep_open omits it too.
exit_codeintWith wait: the process's exit status, -1 when a signal ended it.
signalintWith wait: the signal that ended the process. Omitted when it exited on its own.
{"id":1,"verb":"new-window","params":{"session":"work","name":"build"}}
{"id":1,"verb":"new-window","params":{"session":"work","name":"tests","workspace":2,"cwd":"/src/api","focus":false}}
{"id":1,"verb":"new-window","params":{"session":"work","name":"htop","command":["/usr/bin/htop"]}}
{"id":1,"verb":"new-window","params":{"session":"work","name":"tests","focus":false,"command":["sh","-c","make test"],"keep_open":true,"wait":true}}

pip Added in v0.8.3

Pin a pane as the attached client's picture-in-picture view: a small live copy of the pane in a corner of the screen while another pane has the focus. Naming the pinned pane again unpins it. The view belongs to the client, not the session, and needs an attached client.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name to pin. Omit to pin the client's focused pane, or to unpin it when it is the pinned one.
offboolfalseUnpin whatever is pinned. Takes no window.
Result fieldTypeDescription
pinnedboolWhether a pane is pinned now.
window_idstringId of the pinned pane, empty when nothing is pinned.
{"id":1,"verb":"pip","params":{"session":"work","window":"build"}}
{"id":1,"verb":"pip","params":{"off":true}}

Open a popup: a floating pane that runs one command and closes when the command exits. Needs an attached client.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
command[]stringyesArgv to run in the popup. No shell parses it, so nothing needs quoting. The popup closes when the program exits.
widthstring80%Popup width, in cells ("60") or as a share of the pane region ("60%").
heightstring60%Popup height, in cells ("20") or as a share of the pane region ("50%").
dimintPercent to dim the screen behind this popup, 0 to 90. Omit to inherit appearance.popup_dim (default 0); explicit 0 disables it. Scratch panes are unchanged.
namestringName for the popup. Omit to use the program's title.
cwdstringDirectory to run the command in. Omit to inherit the daemon's.
cwd_fromstringA window whose folder the command runs in, read from its process when the call comes. It wins over cwd, which is the folder when the read gives none.
workspaceintWorkspace to open the popup on. Omit for the current one.
waitboolfalseKeep the call open until the command exits, and return its exit_code in a popup_result.
capture_stdoutboolfalseWith wait: send the command's standard output to a pipe the daemon reads instead of the popup, and return it as stdout. A picker such as fzf draws on the terminal and prints only the choice, so the choice comes back. Not on Windows.
timeoutint0With wait: milliseconds to wait before failing with the timeout code. The popup stays open. 0 waits as long as it is open.
scratch_namestringWith scratch: the scratch pane's name. A session has one scratch pane per name. Empty is the built-in scratch terminal.
scratchboolfalseOpen the session's scratch terminal, the popup the toggle_scratch key shows and hides. command is optional and defaults to the shell. A session has one scratch terminal.
Result fieldTypeDescription
exit_codeintWith wait: the command's exit status, -1 when a signal ended it, as closing the popup does.
stdoutstringWith capture_stdout: what the command printed to standard output, at most 1 MiB.
stdout_truncatedboolWith capture_stdout: true when the output was cut to 1 MiB.
window_idstringId of the popup. Use it to address the popup in later calls.
namestringThe popup's name, generated when none was given.
workspaceintWorkspace the popup was opened on.
pty_idstringId of the popup's PTY.
widthstringThe width the popup uses, with the default filled in.
heightstringThe height the popup uses, with the default filled in.
{"id":1,"verb":"popup","params":{"session":"work","command":["fzf"]}}
{"id":1,"verb":"popup","params":{"session":"work","command":["htop"],"width":"90%","height":"80%"}}
{"id":1,"verb":"popup","params":{"session":"work","command":["fzf"],"wait":true,"capture_stdout":true}}

resize Added in v0.8.0

Resize a window's PTY.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
widthintyesNew width in columns. Must be positive.
heightintyesNew height in rows. Must be positive.
{"id":1,"verb":"resize","params":{"session":"work","width":120,"height":40}}

screenshot Added in v0.8.0

Render a window to an image file.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow id or name. Omit to target the focused window.
formatstringpngOutput format. One of png, svg, ansi, html or txt.
framestringwindowDressing around the capture. One of window, plain or none.
themestringRender in this theme instead of the session's. Truecolor cells are unchanged by it.
scrollbackboolfalsePut the pane's history above the screen in the picture.
linesintBound the history rows to the last N. Needs scrollback.
cursorboolfalseDraw the cursor cell.
outstringWrite here instead of generating a name under screenshot.directory. A linked machine cannot set it.
Result fieldTypeDescription
pathstringThe file that was written.
hoststringThe machine the path is on: daemon or client.
formatstringThe format that was rendered.
colsintGrid width in cells.
rowsintGrid height in cells, history included.
bytesintSize of the written file.
warnings[]stringAnything the render had to guess or fall back on. Empty when there is nothing to say.
{"id":1,"verb":"screenshot","params":{"session":"work","window":"build","format":"svg"}}

set-window Added in v0.8.0

Change a window's name or minimized state. Pass only the fields to change.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow to change. Omit for the focused one.
namestringNew name. Pass an empty string to clear it and fall back to the shell's title.
minimizedboolMinimize the window, or restore it.
Result fieldTypeDescription
window_idstringId of the window that changed.
display_namestringThe name shown now. After a clear this is the shell's title.
minimizedboolWhether it is minimized now.
{"id":1,"verb":"set-window","params":{"session":"work","window":"build","name":"api tests","minimized":false}}

split-window Added in v0.8.0

Split a pane and put a new one beside it. Works with no client attached, and turns tiling on when it is off. The new pane opens on the workspace of the pane it cuts, and starts in the caller's directory when cwd is left out.

ParamTypeRequiredDefaultDescription
sessionstringSession name. Omit from a pane for the pane's own session, and from outside every pane for the most recently active one.
windowstringWindow to split. Omit to split the caller's own pane, or outside a pane the focused one.
directionstringAxis to cut on. The new pane goes right or below. Pass this or side. One of horizontal or vertical.
sidestringSide of the pane the new pane takes. Pass this or direction. One of left, right, up or down.
ratiointThe new pane's share of the space, in percent, from 1 to 99. Omit for an even split.
namestringName for the new window.
command[]stringArgv to run in the new pane instead of a shell, as for new-window.
cwdstringDirectory to start in, as for new-window.
focusbooltrueFocus the new pane. Pass false to leave the focus where it is.
keep_openboolfalseKeep the pane after its process exits, as for new-window.
close_on_exitboolfalseClose the pane when its process exits, as for new-window.
envobjectEnvironment variables for the pane's process, as for new-window.
hoststringRun the pane's process on another machine, as for new-window.
shell_integrationstringWhether the pane's shell starts with OSC 133 prompt marks on, as for new-window. One of auto or off.
grants[]stringWhat the new pane may do through tuios: read, write, fan, respond, admin, or none. Omit for the default of [agents.permissions], or, from a pane without admin, the calling pane's own grants. A pane may give only what it holds, and admin does not include respond. A window on another machine holds what that machine gives it. One of read, write, fan, respond, files, task, admin or none.
Result fieldTypeDescription
window_idstringId of the pane the split created.
directionstringThe axis that was cut.
sidestringThe side the new pane took.
namestringThe new pane's name.
workspaceintWorkspace the new pane is on.
unplacedboolTrue while a client has still to place the pane.
{"id":1,"verb":"split-window","params":{"session":"work","window":"build","direction":"vertical","name":"logs"}}
{"id":2,"verb":"split-window","params":{"session":"work","window":"build","side":"down","ratio":30,"focus":false,"command":["tail","-f","app.log"]}}

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