bateri’s settings live in one file:
~/.config/bateri/settings.toml
If the file doesn’t exist, everything runs with its default and no warning appears. bateri ▸ Settings… (⌘,) opens the settings window, and its Open settings.toml button opens the file in your editor, creating it first with every key at its default, each with a note on what it does. The file may be a symbolic link into a dotfiles repository; the link’s target is read.
When a change takes effect
The moment you save, in the settings file and in the file of the theme in use alike; the shell and the program in it keep running. The one exception is integration in [shell]: the shell has already started, so it takes effect in the next session. It doesn’t matter how your editor saves.
The settings window writes only the line of the setting you change, and so do the menus that write to the file: a theme from View ▸ Theme, View ▸ Tabs ▸ Top or Side, and a host’s mark from the Shell menu. Comments, order and keys bateri doesn’t know are left as they are. A key you delete goes back to its default.
If something goes wrong
bateri always opens, and says what it could not read in the window’s title bar:
bateri – settings.toml: line 2: `terminal.scrollback` must be an integer, found a string; using 10000
With several tabs the title bar holds the tabs, so the error becomes a ⚠ button left of +: hold the pointer on it to read it, click it to open the settings window. When there are several errors the first one shows with the number of the rest, and all of them are printed to standard error with the prefix bateri:.
- A value bateri doesn’t accept falls back to its default at launch. When you save, the key stays as it was, so a half-finished edit never breaks the screen. Three keys fall to the safe side instead:
osc52and[remote] integrationturn off, andrestore_windowsbecomes"layout". - A file that isn’t valid TOML changes nothing when you save. At launch every setting takes its default, with the same three exceptions.
- A key or section bateri doesn’t know is ignored without a word, so a file written for a newer bateri still opens.
- A theme that can’t be found leaves the theme on screen when you save; at launch the built-in theme of the appearance comes. A font that can’t be found falls to JetBrains Mono. Both say so.
Themes
A theme is a TOML file in ~/.config/bateri/themes/, named after the theme, and View ▸ Theme chooses one. bateri comes with its own themes and with well-known palettes such as Catppuccin and Dracula. A file needs only the colors it changes; the rest come from a built-in theme:
# ~/.config/bateri/themes/dracula.toml: Dracula on black
background = "#000000"
The roles a theme colors are in the theme format.
Keys
Every key by its section, with the values it takes and its default. SETTINGS.md in bateri's repository says what each value does in every case.
[terminal]
History, the cursor, asking before closing, and what comes back when bateri opens again.
scrollback- Number of lines kept in history
- integer,
0–100000default10000 scrollbar- When the scroll bar at the right edge shows
"system"|"auto"|"always"|"never"default"system"cursor- The cursor's default shape
"block"|"underline"|"beam"default"block"cursor_blink- Whether the cursor blinks
"auto"|"on"|"off"default"off"cursor_radius- Roundness of the cursor's corners, as a fraction of the cell's height
- decimal,
0.0–0.5default0.10 cursor_glow- Strength of the shadow around the cursor;
0turns it off - decimal,
0.0–3.0default1.0 cursor_unfocused- The cursor while the window is not focused:
hollowempties it,solidleaves it alone "hollow"|"solid"default"hollow"cursor_blink_interval- Half the blink period, in seconds
- decimal,
0.05–5.0default0.5 confirm_close- When to ask while closing a tab, a window or the app
"never"|"running"|"always"default"running"restore_windows- What comes back when bateri opens again
"all"|"layout"|"off"default"all"keep_running- When the running programs outlive bateri
"update"|"crash"|"quit"default"crash"
[appearance]
The theme, the tabs, and how panes are drawn.
theme- The color theme to use
"system"or a theme namedefault"system"light_theme- The light appearance's theme while
theme = "system" - theme namedefault
"bateri-light" dark_theme- The dark appearance's theme while
theme = "system" - theme namedefault
"bateri" content_edge- What the text does where it meets the tab bar, or the frame of a split pane
"fade"|"line"|"cut"default"fade"minimum_contrast- The least contrast ratio a program's text keeps against its background;
1turns it off - decimal,
1.0–21.0default3.0 dim_unfocused_splits- Dim the panes of a split tab that don't have the focus
true|falsedefaultfalsefocus_frame- A 2 pt line in the accent round the focused pane of a split tab
true|falsedefaultfalsesplit_style- How a tab sets its panes apart: cards on a ground, one pane's too, or panes divided by a line
"cards"|"lines"default"cards"tab_details- What a row of the side column says beyond its name: folder and branch (or server) and what a program asks
"off"|"smart"|"always"default"smart"minimized_panes- Where the capsules of minimized floating panes stand: in a row of their own under the splits, which slide up to make room, or over the tab's top right corner under the first pane's bar
"strip"|"top_right"default"strip"resize_in_steps- Resize a window a whole cell at a time while its edge is dragged
true|falsedefaultfalsetab_icons- Show the program a tab runs as an icon on a tile before its title
true|falsedefaulttruetab_icon_colors- Whether the icon uses the theme's colors only, or keeps the program's own color where it has one
"theme"|"brand"default"theme"tab_running- How a tab says a command runs, in the line round its icon: a fading tail going round, the same over a faint standing line, or the whole line fading in and out
"tail"|"tail_ring"|"breathe"default"tail"tab_position- Where a window's tabs sit: a bar along the top, or a column at the left edge
"top"|"side"default"top"
[font]
The font, its size and spacing, and its OpenType features.
family- Font family
- textdefault none (JetBrains Mono)
size- Size in points
- number, greater than
0default13 line_height- Line spacing multiplier
- number,
0.5–2default1.0 letter_spacing- Letter spacing multiplier
- number,
0.5–2default1.0 smoothing- Thicken the text the way macOS does (macOS only)
trueorfalsedefaultfalsefeatures- OpenType feature choices
- tables of
tag = true|false, one per familydefault none
[clipboard]
Whether programs may write to your clipboard.
osc52- Whether a program in the terminal, or the page of a program's view, can write to the clipboard
"copy"or"off"default"copy"
[motion]
How the cursor travels, how history scrolls, and how letters arrive and leave in the dock.
cursor_motion- How the cursor travels between cells
"snap","ease"or"spring"default"spring"reduce_motion- Whether animations are toned down
"system","on"or"off"default"system"smooth_scroll- Whether scrolling through history is smooth or line by line
"on"or"off"default"on"scroll_bounce- Whether lists and text in a program's view bounce at their ends
"on"or"off"default"off"keypress- How a letter typed in the dock arrives
"off","fade","rise","pop","extrude","heat","echo","drop","ink"or"squeeze"default"fade"erase- How a letter deleted in the dock goes
"off","iris","undertow","echo","bleed","unravel","recede","sublime"or"shatter"default"recede"dock_arrival- How the dock of a new window or tab arrives
"off","type","dust"or"ripple"default"ripple"
[shell]
Shell integration, and what the dock shows.
integration- Whether to set up integration in the shell, and how much
"auto","blocks"or"off"default"auto"ports- Whether the dock shows the ports the tab's programs listen on
trueorfalsedefaulttruepython_env- Whether the dock's bottom line starts with the active Python environment
trueorfalsedefaulttruenode_version- Whether the dock's bottom line shows the Node version in a Node project
trueorfalsedefaulttrue
[commands]
What the bateri command may do on this Mac.
level- What the
batericommand may do on this Mac, whoever runs it (an agent or you: the command cannot tell) "off"|"own"|"screen"|"full"default"own"
[agents]
bateri's integration with Claude Code.
claude_integration- Show what Claude Code said last right under its tab's title; a hook tells it, and only the Claude Code you start in a bateri terminal gets the hook
true|falsedefaulttrue
[remote]
Servers: marks for hosts, downloads, the load indicator and shell integration over ssh.
hosts- Marks for hosts: the dock's colors while ssh or mosh is on that host, a database client is connected to it, or kubectl works in that Kubernetes context;
commands("off"|"own"|"screen"|"full") is the level of thebatericommand on that server ([commands]), and an entry may carry it without a mark - array of
{ host, mark, integration, commands }default[] download_dir- The target of "Download to Downloads"
- folderdefault
"~/Downloads" download_conflict- If the same name exists at the target: ask, keep both (the new one gets a number) or overwrite
"ask"|"keep_both"|"replace"default"ask"download_notify- A transfer that ends while bateri is in the background sends a notification
true|falsedefaulttruestats- The style of the remote load indicator at the right of the ssh status bar;
alertsdraws nothing until a value passes its threshold;offturns the indicator and the sampling off "sparkline"|"numbers"|"alerts"|"off"default"alerts"stats_interval- Time between two samples of the load indicator
- integer, seconds,
2–60default3 integration- A plain
sshsets up shell integration on the server true|falsedefaulttrue
[apps]
The programs bateri keeps up to date.
sources- Where the programs bateri keeps up to date publish their releases; written, even as
[], the file's list is the list - array of stringsdefault
["bateri/textpen"] open_with- The program that opens a file or a folder you Command-click in a terminal;
""for none - stringdefault
"textpen"
[keys]
The shortcut of a menu command, by the command's name. A name left out keeps the command's own shortcut, "" leaves it without one, and a list of two gives it two. Settings ▸ Keyboard writes this table for you.
[keys]
copy_last_output = "shift+cmd+o"
show_all_tabs = ""
show_next_tab = ["shift+cmd+]", "ctrl+tab"]