Configuration

Configuration

This page summarizes the configuration model. For the complete grammar, SSH command structure, postconnect semantics, and legacy details, see the in-repo docs/CONFIGURATION.md.

Files

There are two configuration roles:

• ~/.superterm/superterm.ini is the user file: preferences plus the user's own window classes and profiles. The in-application managers save here.
• $SUPERTERM_INI, or /etc/superterm/superterm.ini when unset, is the system file: it can provide shared window classes and profiles.

Both use the same syntax and may be the same file for a personal installation:

export SUPERTERM_INI="$HOME/.superterm/superterm.ini"

Classes and profiles from both files are merged by name; the user file wins. The application creates ~/.superterm with mode 700 and writes its files with mode 600, because they may contain credentials and commands.

User settings

[autologin]
shell=/bin/bash
login=1

[keymap]
prefix=ctrl-q

[ui]
language=en
palette=color

[session]
server=always
autosave=1
autorestore=1
dragcontent=1
zoomanim=0
default_profile=daily

[autologin]

• shell is the local shell for new panes (default $SHELL, else /bin/bash).
• login=1 starts a login shell; login=0 an interactive non-login shell.

[keymap]

prefix selects the tmux-style prefix key for chords (Ctrl-Q d detach, Ctrl-Q c open class, Ctrl-Q s session picker, Ctrl-Q 1..9 go to window, Ctrl-Q n/p next/previous window, Ctrl-Q arrows resize; press the prefix twice to send one literal prefix byte). Accepted values:

• ctrl-a .. ctrl-z, e.g. prefix=ctrl-q.
• A single letter a .. z (shorthand for the same Ctrl key).
• A number 1 .. 26 (raw control code; 17 = Ctrl-Q).

The default is Ctrl-Q. The old numeric default prefix=2 (Ctrl-B) is migrated to Ctrl-Q so it does not collide with a remote tmux; write prefix=ctrl-b to keep Ctrl-B on purpose. The setting is saved in ctrl-<letter> form.

[ui]

• language: en (default) or es; english, spanish, and espanol are also accepted. Also switchable at runtime via Options -> Language.
• palette: color (default, classic Turbo Pascal palette), bw (black and white), or mono (monochrome). Any other value falls back to color. Also switchable at runtime via Options -> Color palette. A desktop picture keeps its own colours in all three.
• desktop_color: the colour behind the windows, as one of the sixteen the text palette holds (0 = black, the default, through 15 = white). It also fills the cells a picture leaves empty. Options -> Desktop colour... is a visual picker for it.
• solid_background=1 (default) makes superterm paint its own black instead of naming the palette's, so a terminal whose theme calls something else "black", or one with a transparent background, does not show through the application. Set it to 0 to get that transparency back: the panes' default background and the chrome's black are then whatever the host terminal makes of them. Also toggled at runtime from Options -> Solid background.

[session]

• server=always (default since 3.0) starts a session server on every launch; the visible terminal attaches to it as a client and the whole workspace can be driven with the control CLI (CLI). server=detach restores the classic behaviour where the server only exists after detaching with the prefix + d.

• autosave=1 (default) saves the fallback session on exit.

• autorestore=1 (default) restores ~/.superterm/session.ini at startup when no profile takes priority; set 0 for a fresh profile startup.

• dragcontent=1 (default) draws a window's contents while it is being dragged. Set it to 0 for a wireframe drag: the window is hidden for the gesture and only its outline moves, so the desktop and the windows behind it stay visible through it, and each step sends just the strip the outline vacates plus the one it takes -- about 29 cells per step on a 53x29 window instead of redrawing the interior. Worth having on a slow or high-latency link, or with a pane full of content.

• zoomanim=0 (default) makes F5 switch instantly. Set it to 1 for a short expanding and contracting outline between the pane and the full desktop, about 350 ms. Purely cosmetic; the instant transition is the fast one.

• All four flags can also be toggled at runtime from the Options menu.

[ui] desktop background

• background names the picture drawn behind the windows, by file name without the extension; none leaves the plain pattern and costs nothing.
• background_mode is center (default), tile, stretch or fit. A picture may name the layout it was made for, and choosing it from the menu adopts that layout.
• Pictures are plain text files searched in $SUPERTERM_BACKGROUNDS, then ~/.superterm/backgrounds, then the directory installed beside the binary, then /usr/local/share/superterm/backgrounds and /usr/share/superterm/backgrounds, then backgrounds/ in a source checkout. First match wins, so your own file shadows an installed one of the same name, and a new file appears in the menu without rebuilding.

A picture is a palette plus three parallel lines per row:

name: City at night
name.es: Ciudad de noche
mode: tile
palette: 0E1430 1B2450 26325F FFD866
>    333   33333
:    111   22222
.    000   00000

> is the glyph row: a space leaves the cell empty so the desktop shows through, 1 2 3 are the upper half, lower half and full block, 4 5 6 the light, medium and dark shades, anything else is literal. : and . give the foreground and background palette index of each cell, as 0-9, a-z, then A-Z. Note the space after the marker: a row is read from the third character.

The pictures that ship use 3 and the space, and nothing else. Half blocks, quadrants and the shades all split apart when the terminal font is stretched -- which is what a maximised window does to them -- so since 3.4.2 a cell is either painted whole, in one colour, or left alone. They are generated by tools/mkbackgrounds.py, which is in the source tree: run it to redraw them or to add your own.

• default_profile names the profile activated at startup.
• Legacy default_template, default_session, and default_window are still read to select the startup profile and window.

Window classes

A window class ([class.NAME]) is a reusable pane definition. Its type is derived from the fields and never stored: connect present -> command class; otherwise host present -> structured SSH class; otherwise -> local class.

[class.production]
name=production
enabled=1
host=prod.example.com
user=alice
port=22
key=~/.ssh/id_ed25519
postconnect=tmux new -A -s main
scrollback=20000

[class.monitor]
name=monitor
enabled=1
cmd=htop

Fields:

• name — canonical name (defaults to the section suffix).
• enabled — 1/0 (also true/yes/on); default 1.
• title — default window title for panes from this class; empty falls back to the class name. A pane title can be changed with Panes -> Rename title... and is kept when saved into a session or profile.
• shell — local shell; empty means the [autologin] shell.
• cmd — command run when the pane opens (locally, or as the SSH remote command when there is no postconnect).
• cwd — working directory; ~/ is expanded.
• host, user, port, key — structured SSH fields.
• password — base64-encoded SSH password; requires sshpass (storage encoding, not encryption). Prefer a key or an agent.
• connect — free connection command; takes precedence over host.
• postconnect — command sent after connecting (see below).
• scrollback — lines; default 10000, maximum 100000.

For a structured SSH class, superterm builds ssh -tt [-p port] [-i key] -o StrictHostKeyChecking=accept-new [user@]host [command]. The remote command precedence is: pane postconnect, class postconnect, pane cmd, class cmd. For command and local classes, postconnect is delivered on the connection's standard input as it starts.

Profiles

A profile ([profile.NAME]) is a named workspace of windows and pane layouts whose panes reference window classes. There are three section levels:

1. [profile.NAME] — name, enabled, focused_window (0-based), windows (comma-separated window names).
2. [profile.NAME.window.W] — enabled, layout, focused_pane (0-based), panes (comma-separated pane names).
3. [profile.NAME.window.W.pane.P] — enabled, class (window class reference; empty means an ad-hoc pane), and overrides cmd, cwd, connect, postconnect, scrollback (terminal is a legacy synonym of class).

[profile.daily]
name=daily
enabled=1
focused_window=0
windows=servers,logs

[profile.daily.window.servers]
enabled=1
layout=V:500;L;L
focused_pane=0
panes=prod,mon

[profile.daily.window.servers.pane.prod]
enabled=1
class=production

[profile.daily.window.servers.pane.mon]
enabled=1
class=monitor

[profile.daily.window.logs]
enabled=1
layout=L
focused_pane=0
panes=logs

[profile.daily.window.logs.pane.logs]
enabled=1
class=production
; pane fields override the class: a different tmux session
postconnect=tmux new -A -s logs

layout is a ;-separated preorder list where L is one pane and V:ratio / H:ratio are splits (V side by side, H stacked). The ratio ranges 0..1000 (500 = half, clamped to 150..850). Switch profile windows with Ctrl-Q 1..9, Ctrl-Q n/p, or F8/F9.

At runtime use the Profiles menu to activate a profile, Save current as profile... to capture the workspace, and Manage profiles... to edit.

Detached sessions

Ctrl-Q d (or Sessions -> Detach...) prompts for a session name (default: the active profile) and moves the panes into a per-user background server:

• Socket: ~/.superterm/sessions/<name>.sock (directory mode 700).
• Metadata sidecar: ~/.superterm/sessions/<name>.ini with the session name, profile, pane count, server PID, and creation time (mode 600).

Names are sanitized to A-Z a-z 0-9 . _ - and limited to 64 characters. Several named sessions can coexist. To return:

superterm --attach            # one session: direct; several: picker
superterm --attach NAME       # attach by name
superterm --list-sessions     # table of live sessions (purges orphans)

Inside the app, Ctrl-Q s (or Sessions -> Attach / manage sessions...) opens the same picker to attach to or permanently close sessions.

Fallback session

When no profile takes priority, ~/.superterm/session.ini stores the current split tree and each pane's cmd, cwd, and class identity. With autosave=1 it is written on exit (and on Ctrl-S); with autorestore=1 it is restored at startup.

Legacy compatibility

Old configurations keep working without manual edits:

• [t-*] terminal sections are read as window classes and migrated to [class.*] the first time the class manager saves the user file. The old type= key is ignored; the type is derived from the fields.
• [template.*] sections are read and flattened into profiles (a one-session template becomes a profile of the same name; a multi-session template becomes one profile per session, named template/session). An explicit [profile.*] of the same name wins.
• SQLite template storage ([storage] with backend=sqlite and directory=templates) is still read as a legacy, read-only template source and flattened the same way.
• [keymap] prefix=2 migrates to Ctrl-Q; prefix=ctrl-b keeps Ctrl-B.
• [session] default_template, default_session, and default_window still select the startup profile and window.
• The old single ~/.superterm/session.sock detached session is still recognized by the picker and --attach.