A4(1)

📦 version 2.0, in nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

okay bestie, welcome to a4(1) — the manual page for a4, a dynamic terminal manager. no cap, that's the whole vibe of the name section. 💅

🦋 SYNOPSIS 🦋

a4 [-a name] [-l] [-i file] [-s] [-v]

💖 DESCRIPTION 💖

a4 is a dynamic terminal window manager. One of eight tiling layouts is dynamically applied to all visible terminals. The terminal windows are grouped by tags, making it easy to visually switch between contexts of work. a4 automatically runs in a named persistent session from which you can detach and reconnect. Any number of named sessions can exist simultaneously. Color schemes are dynamically applied to each terminal window, based on the text in its titlebar, helping the user to visually identify terminals based on attributes such as hostname, userid, and any other text programmed to display in the titlebar. it's giving organized but make it cute ✨

Four of the eight layouts divide the screen into two areas, one for a zoomed window and the other for a stack of the remaining windows. These four layouts can be adjusted during use to expand or shrink the number of windows in the zoom area and the overall size of the zoom area. They are named for the location of the zoom area: zoom_left, zoom_right, zoom_top, and zoom_bottom. The other four layouts are fullscreen, grid, rows, and columns. highkey iconic layout behavior 🫶

Each terminal window can be tagged with one or more tags. The user then selects which tag or tags to view, and all windows with those tags are arranged in the dynamic layout. The list of all tags is displayed on the left of the status bar. Tag names are user defined, with the default being the numerals 1 through 9. obsessed with a tag system fr fr 🎀

Terminal windows can be minimized to a bar at the bottom of the screen. A minimized terminal keeps its tags but stays out of the user's way until it is unminimized again. Terminal windows can be set to read-only status in order to prevent accidental typing or closing. Terminal windows can be added to a focus group in order to type the same input into all simultaneously. Minimized and read-only terminal windows are never typed into, even if they are included in the focus group. safety first, bestie 💖

Terminal color schemes are dynamically applied by comparing the text of the terminal's title with an ordered set of user-defined color rules. literally color-coded main character energy 🌈

✨ OPTIONS ✨

  • -a name — Attach to named session, creating it if it doesn't exist.
  • -l — List all available sessions.
  • -i file — Use the specified INI file instead of the default file.
  • -s — Suppresses all startup actions defined in the INI files.
  • -v — Prints version information to stderr, then exits.

🎀 USAGE 🎀

This section lists the default keyboard and mouse mappings to actions in a4. Everything is user-defined and may be customized to the user's liking (see CUSTOMIZATION below). yes bestie, you can remap it all 💅

⌨️ Keyboard commands ⌨️

  • Ctrl-\ — Detach from the session.
  • Ctrl-g c — Create a new terminal window.
  • Ctrl-g x x — Force close the focused terminal.
  • Ctrl-g Enter — Zoom the focused terminal window to the top of the window stack, to be window #1, or swap with the next window if it is already #1.
  • Ctrl-g . — Minimize/unminimize the focused terminal window.
  • Ctrl-g q q — Force close all terminals and exit a4.
  • Ctrl-g Ctrl-l — Redraw the entire application.
  • Ctrl-g s — Enable or disable the status bar.
  • Ctrl-g S — Switch the position of the status bar between top and bottom.
  • Ctrl-g v [1..n] or Ctrl-g [F1..Fn] — View all terminal windows of only the tag at position n.
  • Ctrl-g t [1..n] — Set the focused terminal window to only the tag at position n.
  • Ctrl-g V [1..n] — Toggle viewing of terminal windows of the tag at position n.
  • Ctrl-g T [1..n] — Toggle on/off the tag at position n on the focused terminal window.
  • Ctrl-g v 0 — View all terminal windows of all tags.
  • Ctrl-g v Tab — Switch to viewing the terminal windows of the previously selected set of tags.
  • Ctrl-g t 0 — Set all tags on the focused terminal window.
  • Ctrl-g [1..n] — Focus terminal window number n.
  • Ctrl-g m [1..n] — Move the focused terminal window to position n in the window order.
  • Ctrl-g j — Focus next terminal window.
  • Ctrl-g k — Focus previous terminal window.
  • Ctrl-g Ctrl-j — Focus next visible terminal window, skipping minimized windows.
  • Ctrl-g Ctrl-k — Focus previous visible terminal window, skipping minimized windows.
  • Ctrl-g Tab — Focus the last selected terminal window.
  • Ctrl-g H — Focus terminal window to the left.
  • Ctrl-g J — Focus terminal window below.
  • Ctrl-g K — Focus terminal window above.
  • Ctrl-g L — Focus terminal window to the right.
  • Ctrl-g 0 — Toggle all visible terminal windows to be grouped for simultaneous typing. Minimized and read-only windows are not typed into, even if they are included in the focused group.
  • Ctrl-g ) — Toggle the focused terminal window to be part of a group of one or more focused windows for simultaneous typing. Minimized and read-only windows are not typed into, even if they are included in the focused group.
  • Ctrl-g * — Toggle read-only status of the focused terminal window so that no keypresses are sent to it.
  • Ctrl-g e — Open copy mode in the focused terminal window. The terminal buffer is passed as file $1 to a command for browsing and selection. A second file, $2, is also passed and any text written to it is saved to both the a4 paste buffer and the system clipboard. File $2 may also just be ignored. See copymode below.
  • Ctrl-g p — Paste the contents of the a4 paste buffer into the focused terminal window.
  • Ctrl-a f — Set layout to full screen.
  • Ctrl-a g — Set layout to grid.
  • Ctrl-a h — Set layout to zoom left.
  • Ctrl-a j — Set layout to zoom bottom.
  • Ctrl-a k — Set layout to zoom top.
  • Ctrl-a l — Set layout to zoom right.
  • Ctrl-a c — Set layout to columns.
  • Ctrl-a r — Set layout to rows.
  • Ctrl-a Space — Cycle forward through the layouts.
  • Ctrl-a Ctrl-Space — Cycle backward through the layouts.
  • Ctrl-a Tab — Switch to the previous layout.
  • Ctrl-a i — Increment the number of terminal windows in the zoom area.
  • Ctrl-a d — Decrement the number of terminal windows in the zoom area, if using a zoom layout.
  • Ctrl-a I — Increase the size of the zoom area by 5%, if using a zoom layout.
  • Ctrl-a D — Decrease the size of the zoom area by 5%, if using a zoom layout.
  • Shift-PageUp/PageDown — Scroll backward/forward half a screen in the focused terminal window.
  • Ctrl-g PageUp/PageDown — Scroll backward/forward a full screen in the focused terminal window.

🖱️ Mouse in terminal window 🖱️

Note that when a terminal application uses the alternate screen (such as vim, btop, or less), mouse events are passed through directly to the application instead of being handled by a4. Hold Ctrl while pressing or dragging Button1 to override this and perform text selection in a4 instead. 💖
  • Button1 click — Focus the selected terminal window.
  • Ctrl-Button1 click — Zoom the selected terminal window to the top of the window stack, to be window #1, or swap with the next window if it is already #1.
  • Button3 click — Toggle the selected terminal window to be part of a group of one or more focused windows for simultaneous typing. Minimized and read-only windows are not typed into, even if they are included in the focused group.
  • Ctrl-Button3 click — Toggle all visible terminal windows to be grouped for simultaneous typing. Minimized and read-only windows are not typed into, even if they are included in the focused group.
  • ScrollWheel up/down — Scroll backward/forward three lines in the terminal window that the mouse is hovering over.
  • Shift-ScrollWheel up/down — Scroll backward/forward half a screen in the terminal window that the mouse is hovering over.
  • Ctrl-ScrollWheel up/down — Scroll backward/forward a full screen in the terminal window that the mouse is hovering over.
  • Button1 drag — Select text in a terminal window. The selected text is automatically copied to the system clipboard when the button is released.

🖱️ Mouse in title bar 🖱️

  • Button1 click — Minimize/unminimize the selected terminal window.
  • Button3 click — Toggle read-only status of the selected terminal window so that no keypresses are sent to it.

🖱️ Mouse on tags in status bar 🖱️

  • Button1 click — View terminal windows of only the selected tag.
  • Ctrl-Button1 click — Toggle viewing of selected tag terminal windows.
  • Button3 click — Set the focused terminal window to only the selected tag.
  • Ctrl-Button3 click — Toggle on/off the selected tag on the focused terminal window.

🖱️ Mouse on layout symbol in status bar 🖱️

  • Button1 click — Cycle forward through the layouts.
  • Button3 click — Cycle backward through the layouts.
  • Ctrl-Button1 click — Increment the number of terminal windows in the zoom area, if using a zoom layout.
  • Ctrl-Button3 click — Decrement the number of terminal windows in the zoom area, if using a zoom layout.
  • M-Ctrl-Button1 click — Increase the size of the zoom area by 5%, if using a zoom layout.
  • M-Ctrl-Button3 click — Decrease the size of the zoom area by 5%, if using a zoom layout.

🖱️ Mouse on status bar text 🖱️

  • Button1 click — Cycle to next status bar command, or refresh the status bar command if there is only one.

🖱️ Mouse on layout frame line 🖱️

  • Button1 click — Set layout to fullscreen.

🎀 CUSTOMIZATION 🎀

Okay bestie, the whole personality of a4 is controlled by settings in the a4.ini file. Review the comments in the default system a4.ini file for instructions on how to customize these settings. See FILES below for the location of configuration files. A typical user configuration file is located at $HOME/.config/a4/a4.ini. The first line is often include = /usr/local/share/a4/a4.ini and then the following lines are the user's preferred override settings.

Several configuration settings may be cleared out and reset by setting them equal to blank, including "startup =" and "statusbar_cmd =". Having a section head [ColorScheme] followed by a line with just a single = character clears out all previously defined ColorSchemes. Likewise, a section head [ColorRules] followed by a line with just a single = character clears out all previously defined ColorRules. Any Key/Mouse Combination assigned in any of the Action sections may be cancelled by assigning it to blank, e.g. C-g c =. Later Key/Mouse Combination assignments override earlier ones.

🌈 ColorSchemes 🌈

Having different terminal color schemes dynamically applied helps to identify and keep track of all the different terminals with which you're working. The first step is to have different color schemes defined for use by the ColorRules later. Terminals typically have a default foreground (fg) color, background (bg) color, and 16 standard colors that are used by terminal applications. They can also define color numbers up to 255, but they are used less often. In a4, you can define ColorSchemes that are then applied to terminal windows dynamically by comparing the terminal's title text to defined ColorRules (see below). The first defined ColorScheme is used by default for all windows.

🦋 ColorRules 🦋

ColorRules look at the text in a terminal's title bar in order to dynamically set the terminal window's ColorScheme. This helps to identify and keep track of all the different terminals with which you're working. Color rules pair text with ColorSchemes. The text in a terminal window's title bar is compared with the text of each ColorRule, in the order specified, until one matches, and then that ColorScheme is applied to the terminal window. If none of the rules match, then the first ColorScheme defined in a4.ini is used.

The text of the title bar can be set using an echo command, for example echo -ne "\e]0;foobar\a" sets the title text to foobar. If using the bash shell, it is convenient to set the PROMPT_COMMAND environment variable to keep this text up-to-date with the current username, hostname, and present working directory. This is typically done with something like this in the user's .bashrc file:

PROMPT_COMMAND='echo -ne "\e]0;$USER@$HOSTNAME:${PWD/$HOME/\~}\a"'

With this kind of setup, it is then easy to specify ColorRules to have your terminals dynamically change colors based on these variables.

🌸 Terminology 🌸

Minimized and read-only terminal windows are never typed into, even if they are selected or focused.

  • selected — refers to just the one terminal window that has the cursor.
  • focus group — refers to the set of all visible terminal windows that have the group attribute enabled.
  • focused — refers to the selected terminal window, and if that window is part of the focus group then focused refers to all windows in the focus group.
  • mouse-selected — refers to just the one terminal window that is clicked on in the MouseTermwinActions or MouseTitlebarActions area.
  • mouse-focused — refers to the mouse-selected terminal window, and if that window is part of the focus group then mouse-focused refers to all windows in the focus group.

💅 Actions that can be mapped to keyboard and mouse events 💅

  • copymode — Open copy mode for the focused terminal window. The scrollback buffer and current screen contents are written to a temporary input file and passed as $1 to the editor command. A second temporary output file is passed as $2. Any text written to the $2 output file is saved to the a4 paste buffer and placed on the system clipboard. The $2 output file may also be ignored. The editor command is taken from the copymode_editor INI setting, then the EDITOR environment variable, then defaults to vi.
  • create — Create a new terminal window and is assigned the currently selected tags. The new window is placed in the #1 position in the order of all visible windows.
  • destroy — Force close the selected or mouse-selected terminal (not all focused or mouse-focused terminals).
  • focus[1-9|#|next|NEXT|prev|PREV|left|right|up|down|swap|group|groupall|0] — Move focus to the numbered terminal window specified by the numeral parameter 1-9. When # is used in the mapping instead of a numeral, the mapping is automatically expanded to nine separate mappings with the # character on both sides of the assignment replaced by the numerals 1-9. Parameters next and prev move focus to the next/prev numbered window in the ordered stack of all visible windows. Parameters NEXT and PREV do the same but skip over all minimized windows. Parameters left, right, up, and down move focus based on direction rather than number order. In the MouseTermwinActions or MouseTitlebarActions sections, mapping focus without any parameter focuses the mouse-selected window. Parameter swap focuses whichever was the previously focused window. Parameter group toggles the selected or mouse-selected window to be part of the focus group for simultaneous typing, while the groupall or 0 parameter toggles all visible windows to be part of the focus group.
  • keysequence char... — Send a sequence of characters to the focused terminal window. There is a set of backslash character escape sequences that may be used with this: \a for alert, \b for backspace, \e for escape, \f for form feed, \n for newline, \r for carriage return, \t for horizontal tab, \v for vertical tab, and \\ for backslash.
  • layout <layout name>|[+]1|-1|swap — Set layout to one of the eight named layouts: zoom_left, zoom_right, zoom_top, zoom_bottom, fullscreen, grid, rows, and columns. Parameter 1 or +1, cycles forward through the layouts, and -1, cycles backward. Parameter swap sets the layout to whatever was previously set.
  • minimize — Minimize/unminimize the selected or mouse-selected terminal window.
  • movewin [1-9 | #] — Move the focused terminal window to position n in the window order. If the window is minimized, it is unminimized and placed at the specified position. A value of 0 or 1 moves the window to position 1. Any value greater than or equal to the number of non-minimized windows moves it to the last non-minimized position. Minimized windows are not counted when determining the last position. When # is used in the mapping instead of a numeral, the mapping is automatically expanded to nine separate mappings with the # character on both sides of the assignment replaced by the numerals 1-9.
  • paste — Paste the contents of the a4 paste buffer into the focused terminal window.
  • quit — Force close all terminals and exit a4.
  • readonly — Toggle read-only status of the selected or mouse-selected terminal window so that no keypresses are sent to it.
  • redraw — Redraw the entire application.
  • scrollback [<n lines>|<.n percent>] — Scroll the focused or mouse-focused terminal window(s). Positive numbers scroll backward and negative numbers scroll forward. Integer numbers specify the exact number of lines to scroll. Numbers with a decimal point are interpreted as a percentage of a full screen of lines to scroll, e.g. .5 scrolls back half a screen's worth of lines.
  • statusbar next|vis|on|off|pos|top|bottom — Parameter next reruns the statusbar command, or cycles to run the next statusbar command if there are more than one. Parameter vis toggles the status bar on and off, or on and off set the visibility directly. Parameter pos toggles the statusbar position between top and bottom, or top and bottom set the position directly.
  • tag [<tag name>|_all] — Set the selected or mouse-selected terminal window to have only the specified tag name tag enabled. Special parameter _all sets the window to have all tags enabled on it. If mapped in the MouseTagNamesActions section, tag may be used without a parameter to set the selected window to have only the clicked tag enabled.
  • tagtoggle [<tag name>] — Toggle the tag name tag on and off on the selected or mouse-selected terminal window. If mapped in the MouseTagNamesActions section, tagtoggle may be used without a parameter to toggle the clicked tag on the selected window.
  • view [<tag name>|_all|_swap] — View all terminal windows with the tag name tag enabled. Special parameter _all views all windows of all tags. Special parameter _swap views the windows of whichever set of tags were previously selected. If mapped in the MouseTagNamesActions section, view may be used without a parameter to view all windows of the clicked tag.
  • viewtoggle [<tag name>] — Toggle viewing terminal windows of the tag name specified. If mapped in the MouseTagNamesActions section, viewtoggle may be used without a parameter to toggle viewing windows of the clicked tag.
  • zoom [n] — Zoom the selected or mouse-selected terminal window to the top of the window stack, to be window #1, or swap with the next window if it is already #1. If a parameter n is passed then that window number is zoomed instead of the selected window.
  • zoomnum [[+|-]n] — If the parameter passed includes a + or - sign symbol prefix then the action is to increase or decrease the number of terminal windows in the zoom area by n. If there is no sign symbol then the number of windows in the zoom area is set to n. If no parameter is passed then the number of windows in the zoom area is reset to the definition in the a4.ini configuration file. The minimum value of zoomnum is 1.
  • zoomsize [[+|-].n] — okay so bestie, this is your zoom-area size slider. If the parameter you pass has a + or - sign prefix, the action is to increase or decrease the size of the zoom area by n percent of the screen. No sign symbol? Then the zoom area size is just set to n percent of the screen. Pass no parameter at all? It resets the zoom area size to the definition in the a4.ini configuration file. Minimum value is .1, maximum is .9 — lowkey keep it in that range, fr fr. 💅

🌿 ENVIRONMENT 🌿

  • A4 — every process running inside a4 gets this variable set to the version. iconic little breadcrumb, honestly.
  • A4_SESSION — set to the session name when you're running inside a session. It prevents a nested a4 started from a startup command from recursively re-attaching to the same session. no cap, it's the anti-oops guard.
  • TERM — generally just use whatever the underlying terminal defaults to for this variable. If there's any question, use xterm-256color. 🫶
  • COLORTERM — if you're not seeing 24-bit truecolor, set this variable to 24bit or truecolor in the underlying terminal and restart a4. that's the whole vibe check. 🌈
  • EDITOR — copy mode uses this as the default editor when copymode_editor is not set in the INI file. If neither is set, it defaults to vi. periodt.

🗂️ FILES 🗂️

  • a4.ini — the configuration file a4 reads during initial startup. The location of the user's default file is $XDG_CONFIG_HOME/a4/a4.ini, which is usually $HOME/.config/a4/a4.ini, and the system default file is /usr/local/share/a4/a4.ini. 💖
  • *.ini — there are additional, partial configuration files in the /usr/local/share/a4/ directory, and they may be included in a user's own a4.ini file. For example, theme_default.ini includes all the a4 color theme settings; cs_solarized.ini defines the Solarized terminal color schemes, which may be used in color rules; vt220.ini defines the vt220 ANSI escape codes for terminal overrides. lil modular config moment ✨
  • $XDG_STATE_HOME/a4/name@hostname — session socket file for the named session, where name is the session name and hostname is the short hostname of the machine running the session. $XDG_STATE_HOME defaults to $HOME/.local/state. One socket file exists per active session; use a4 -l to list all active sessions on the current host. 🎀

📝 NOTES 📝

Real talk: there's a configuration error in the xterm-256color file installed by some Linux distros that causes the mouse to behave incorrectly by printing characters to the terminal. If you experience this problem, run the following command to put a local, patched copy of the file in place for your login account:

infocmp xterm-256color | sed -E 's/(kmous=\\E\[)</\1M/' | tic -o ~/.terminfo -

More documentation of a4 can be found at https://a4term.com/ — go get your read on, bestie. 🦋

👀 SEE ALSO 👀

  • a4-keycodes(1)

💖 and that's the whole page! footer says a4-v2.0 and A4(1), so you know it's official. go slay your terminal, bestie ✨

📦 where this page comes from