Customize

Settings

bateri's settings are one file: where it lives, when a change takes effect, what happens to a value bateri can't read, and every key with its default.

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: osc52 and [remote] integration turn off, and restore_windows becomes "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–100000default 10000
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.5default 0.10
cursor_glow
Strength of the shadow around the cursor; 0 turns it off
decimal, 0.0–3.0default 1.0
cursor_unfocused
The cursor while the window is not focused: hollow empties it, solid leaves it alone
"hollow" | "solid"default "hollow"
cursor_blink_interval
Half the blink period, in seconds
decimal, 0.05–5.0default 0.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; 1 turns it off
decimal, 1.0–21.0default 3.0
dim_unfocused_splits
Dim the panes of a split tab that don't have the focus
true | falsedefault false
focus_frame
A 2 pt line in the accent round the focused pane of a split tab
true | falsedefault false
split_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 | falsedefault false
tab_icons
Show the program a tab runs as an icon on a tile before its title
true | falsedefault true
tab_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 0default 13
line_height
Line spacing multiplier
number, 0.5 – 2default 1.0
letter_spacing
Letter spacing multiplier
number, 0.5 – 2default 1.0
smoothing
Thicken the text the way macOS does (macOS only)
true or falsedefault false
features
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
true or falsedefault true
python_env
Whether the dock's bottom line starts with the active Python environment
true or falsedefault true
node_version
Whether the dock's bottom line shows the Node version in a Node project
true or falsedefault true

[commands]

What the bateri command may do on this Mac.

level
What the bateri command 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 | falsedefault true

[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 the bateri command 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 | falsedefault true
stats
The style of the remote load indicator at the right of the ssh status bar; alerts draws nothing until a value passes its threshold; off turns 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–60default 3
integration
A plain ssh sets up shell integration on the server
true | falsedefault true

[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"]