path: root/docs/slosh.1

.\" slosh(1) -- hand-written man(7), no toolchain renders it into being.
.\" Kept in docs/ beside the longer prose; `make install` puts it under
.\" share/man/man1. When behaviour changes, this file is part of the change.
.TH SLOSH 1 "August 2026" "slosh" "User Commands"
.SH NAME
slosh \- a terminal multiplexer
.SH SYNOPSIS
.B slosh
.RB [ \-s
.IR name ]
.RB [ \-\-layout
.IR file ]
.RB [ \-\-no\-reload ]
.RB [ \-\-
.IR command\ ... ]
.br
.B slosh ls
.br
.B slosh
.RB [ \-s
.IR name ]
.B cmd
.I line
.br
.B slosh \-\-check
.RI [ file ]
.br
.B slosh \-\-dump\-config
.br
.B slosh \-\-dump\-theme
.br
.B slosh \-\-headless
|
.B \-\-script
.RB [ \-\-cols
.IR n ]
.RB [ \-\-rows
.IR n ]
.RB [ \-\-idle\-ms
.IR n ]
.RB [ \-\-layout
.IR file ]
.RB [ \-\-
.IR command\ ... ]
.SH DESCRIPTION
.B slosh
multiplexes one terminal into panes and tabs, grouped into named
.I sessions
that keep running when the terminal goes away.
Run with no arguments it attaches to the session called
.BR main ,
creating it if nobody is home; detaching (or losing the connection)
leaves the session and everything in it running, and the same command
reattaches.
.PP
Several terminals may attach to one session at once.  The newest attachment,
then the client with the most recent keyboard or mouse activity, sets the
shared screen size.  Resizing that active client resizes the session; resizing
another client changes only its view.  A smaller view follows the cursor over
the shared screen, and a larger one is filled with blank cells.  Detaching
leaves the other clients attached.  Both halves are configurable:
.B multi_attach
restores the old displacing attach, and
.B size_follows
picks whose size rules; see
.BR slosh (5).
.PP
A trailing
.B \-\-
.I command\ ...
is run in the first pane instead of the configured shell.
Every other pane runs the shell the configuration names, or
.BR $SHELL .
.PP
Attaching from inside a pane of the same session is refused, because it would
draw the session recursively inside itself; the error message names the
escape hatches.
Attaching to a
.I different
session from inside a pane is nesting, and allowed.
.SH OPTIONS
.TP
.BI \-s\  name
The session to attach to, create, or (with
.BR cmd )
address.
Defaults to
.BR main .
.TP
.BI \-\-layout\  file
Apply a layout file to the session being created: tabs, splits,
directories and commands, as written by
.B dump\-layout
or by hand.
See the layouts chapter of the documentation.
.TP
.B \-\-no\-reload
Do not watch the configuration file for changes.
By default a running session re-reads it when it changes on disk, and a
file that no longer parses is reported and otherwise ignored.
.TP
.BI \-\-check\  [file]
Read a configuration (or, if the file looks like one, a layout)
the way a session would, and print everything it could not honour, one
problem per line as
.IR file:line:\ what .
Without an argument it checks the configuration a session would actually
load.
Exits 1 when there is anything to say, so it slots into an editor's
compile step or a pre-commit hook without glue.
.TP
.B \-\-dump\-config
Print every setting with its default, as a file you could have written.
.RS
.PP
.EX
slosh \-\-dump\-config > ~/.config/slosh/config.kdl
.EE
.PP
is a supported way to start a configuration.
The values are the defaults, not the ones currently in effect:
this is the file to begin from, and
.B \-\-check
is the one that reads yours back.
Colour is the exception: it prints the
.B theme_name
in force and the colours a configuration overrides by hand, not the
resolved palette, so a dumped configuration keeps following its theme.
.RE
.TP
.B \-\-dump\-theme
Print the palette in force as a theme file: every colour the
compositor draws, derivations resolved.
.RS
.PP
.EX
slosh \-\-dump\-theme > ~/.config/slosh/themes/mine.kdl
.EE
.PP
starts a theme from the session in front of you rather than from an
empty file; name it with
.B theme_name
to wear it.
.RE
.TP
.B \-\-headless
Run the whole compositor without a terminal: start the command, let it
settle, print the composed screen to standard output, and exit.
Useful for seeing what a program draws without attaching anything.
.TP
.B \-\-script
The headless driver: the same compositor reading control commands from
standard input, one per line, and answering on standard output: the
same vocabulary the control socket speaks, without a server or a socket.
This is what the test suite drives.
.TP
.BI \-\-cols\  n ,\ \-\-rows\  n
The screen size for the headless modes (default 80\(mu24).
When attaching from a terminal, its size enters the latest-active rule above.
.TP
.BI \-\-idle\-ms\  n
How long
.B \-\-headless
waits for output to go quiet before printing the screen (default 300).
.TP
.B \-\-version
Print the version and exit.
It is the same string the status line shows, so \(lqwhich build is
this\(rq has one answer whether you ask the binary or the session.
.TP
.B \-\-install\-terminfo
Write the
.B xterm-ghostty
terminfo entry the binary carries into
.I ~/.terminfo
(no root, no package).
Sessions do this on their own when the entry is missing everywhere; the
flag is the by-hand spelling, for provisioning and for saying so.
See ENVIRONMENT.
.TP
.BI \-\-server\  name
Run a session's server in the foreground.
Internal: attaching spawns this for you.
.SH COMMANDS
.TP
.B ls
List sessions, each
.B running
or
.B stale
(a socket whose server no longer answers).
.TP
.BI cmd\  line
Send one control command (a JSON object) to the session named by
.B \-s
and print the reply.
A detached session answers exactly as an attached one does.
The vocabulary (panes, tabs, layouts, workspaces, clipboard, snapshots,
and more) is listed in the scripting chapter of the documentation:
.RS
.PP
.EX
slosh \-s work cmd '{"cmd":"new\-tab","name":"api"}'
slosh \-s work cmd '{"cmd":"panes"}'
.EE
.RE
.SH KEYS
Everything is the
.B prefix
.RB ( ctrl+a
by default), then one key.
Pressing the prefix twice sends a literal
.B ctrl+a
to the program in the pane.
.B prefix\ ?
shows a cheatsheet built from the bindings actually in force, and
.B prefix\ p
opens the same list as a palette you can type into; both therefore
outrank the table below, which shows the defaults.
.TP
.B Enter
Split whichever way there is more room;
.B \e
and
.B \-
split into columns or rows when you mean one.
.TP
.BR h\ j\ k\ l ,\ arrows
Move focus;
.B o
focuses the next pane.
.TP
.BR H\ J\ K\ L ,\ shift+arrows
Move the boundary between panes, or the pane itself when it is floating.
.TP
.B 0
Give every visible pane an even share.
.TP
.B Space
Turn the layout a quarter turn.
.TP
.B z
Zoom this pane to fill the tab, and back.
.TP
.B m
Minimise it into the strip along the bottom.
.TP
.BR f ,\ F
Float this pane above the layout, and back; a
.I new
floating shell: the throwaway terminal.
.TP
.B =\ (+),\ \-
Grow / shrink a focused float about its centre
.RB ( \-
splits, when the pane is tiled).
.TP
.BR x ,\ X
Close this pane; close this tab and everything in it.
On the last tab
.B X
refuses and points at
.BR q .
.TP
.B r
Run a finished pane's command again.
.TP
.B P
Set this pane's purpose (a label layouts and scripts address).
.TP
.BR > \ < ,\ b
Push this pane to the next / previous tab; break it out into a tab of
its own.
.TP
.BR c ,\ Tab ,\ shift+Tab ,\ 1 \&...\& 9
New tab; next / previous tab; go to that tab.
.TP
.B s
Find a pane by name.
.TP
.BR w ,\ W
The projects picker (workspaces); write this tab out as this project's
layout.
.TP
.B p
The command palette.
.TP
.B PgUp\ PgDn\ Home\ End
Scrollback; the mouse wheel works too.
.TP
.B e
Edit the configuration, in a pane.
.TP
.B d
Detach, leaving the session running.
.TP
.B q
Quit the session.
.PP
Rebinding is one line of configuration:
.B keys { prefix "ctrl+b" }
and a
.B keys
block adds to the defaults rather than replacing them; binding a key to
.B none
takes it away.
.SH MOUSE
Clicking focuses.
Dragging with the left button selects, and releasing copies: the
selection is the copy, sent to your terminal as an OSC\ 52 clipboard
write.
A drag held past a pane's top or bottom edge scrolls the viewport under
it, so more than one screenful is selectable in one gesture; the further
past the edge, the faster.
A double-click selects the word under the pointer, where words stop at
configurable separators.
The middle button pastes the last selection.
The wheel scrolls a pane's scrollback, or becomes arrow keys for a
full-screen program without scrollback of its own.
.PP
A program that asks for the mouse gets it (clicks, wheel and all),
and holding
.B shift
selects over it, the escape hatch every terminal shares.
.PP
The chrome is draggable: a title moves a pane onto another to swap them
(or onto the tab strip to move it there), a border drags the boundary,
and the corners resize floats.
Every button on the frame says what it does when the pointer rests on
it.
.SH SHADERS
A pane can wear
.IR shaders :
colour passes over its cells, each a pure function from (cell,
position, strength) to that cell's colours.
Text is never touched, only colour, so selection and copy read what was
really there.
A
.B shaders { }
block in the configuration runs a chain over every pane
.RB ( where=\(dqchrome\(dq
runs a pass over the frame instead), a
.B states { }
block tints panes by what is true of them (dead, suspended,
scrolled, unfocused, ringing a bell), and the strength of any pass
can be an arithmetic expression over the cell's position, the cursor,
focus and the clock, which is how scanlines, margins, spotlights and
breathing frames are written in a config file without compiling
anything.
See
.BR slosh (5)
for the vocabulary; ready-made presets ship under
.IR PREFIX/share/slosh/ ,
and a program can prototype a chain on its own pane over an escape
sequence (OSC\ 5577) when the configuration allows it with
.BR in_band_shaders .
.SH CONFIGURATION
One KDL file:
.IR ~/.config/slosh/config.kdl ,
honouring
.B $XDG_CONFIG_HOME
and overridden wholesale by
.BR $SLOSH_CONFIG .
No file is required; every setting has a default, and
.B \-\-dump\-config
prints them all as a starting point.
A running session re-reads the file when it changes (see
.BR \-\-no\-reload ),
keeping the working configuration when the new file is broken, and
.B include
composes files (a theme, a shared base) with the includer
winning.
The format, every setting, and the layout files a session can be built
from are
.BR slosh (5).
.PP
An installed copy of the annotated default configuration, example
layouts, themes and shader presets lives under
.IR PREFIX/share/slosh/ .
.SH ENVIRONMENT
Set in every pane:
.TP
.B TERM
.B xterm-ghostty
\(en found in the machine's terminfo database, or, when it is missing
everywhere, installed into
.I ~/.terminfo
from the copy the binary carries (an entry curses cannot find makes
editors exit on the spot and backspace guess).
Only when even that write fails (no
.BR $HOME ,
read-only) do panes get
.BR xterm-256color ,
and everything still works.
.TP
.B SLOSH
.B 1
: you are inside a pane.
.TP
.B SLOSH_SESSION
The name of the session this pane belongs to: which one of possibly
several, the part a program cannot work out for itself.
Unset under
.BR \-\-script ,
which has no session.
.TP
.B SLOSH_BIN
The binary that made this pane, so a program can reach the session even
when
.B slosh
is not on its
.BR PATH .
.PP
Read:
.TP
.B SLOSH_CONFIG
The configuration file, overriding the default path.
.TP
.B XDG_CONFIG_HOME
Where the default configuration path starts.
.TP
.B XDG_RUNTIME_DIR
Where sockets and server logs live; without it,
.IR /tmp/slosh\-UID/ .
.TP
.B SHELL
What a pane runs when the configuration does not say.
.TP
.B EDITOR
What
.B prefix\ e
opens the configuration in, when the configuration does not say.
.SH FILES
.TP
.I ~/.config/slosh/config.kdl
The configuration.
.TP
.I $XDG_RUNTIME_DIR/slosh/name.sock
A session's control socket
.RI ( /tmp/slosh\-UID/name.sock
without
.BR XDG_RUNTIME_DIR ).
.TP
.I $XDG_RUNTIME_DIR/slosh/name.log
That session's server log.
.TP
.I PREFIX/share/slosh/
The annotated default configuration, an example layout, and the shipped
themes, chrome and shader presets.
.TP
.I PREFIX/share/doc/slosh/
The full documentation, of which this page is the summary: keys, panes,
configuration, shaders, layouts, workspaces, scripting, design.
.SH EXIT STATUS
0 on success, and for
.B \-\-check
a clean file; 1 when
.B \-\-check
found problems, or when attaching, starting or addressing a session
failed; 2 for an unknown argument.
.SH SEE ALSO
.BR slosh (5)
.PP
The prose documentation under
.IR PREFIX/share/doc/slosh/ ,
which this page summarises.