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

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

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

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