In a terminal bateri opened, on this Mac or on a server over ssh, the bateri command is on the PATH. A program, a script or an agent uses it to open panes beside you, type into a pane, read its screen and ask you to look.
bateri on the Mac is never asked to run anything: what a program sends it only places, lists, labels, moves or closes panes, tabs, groups and windows, and shows a notification.
Open a terminal in bateri and try it:
bateri split --below -- npm run dev # prints p9: a pane below this one
bateri capture p9 # what is on its screen
bateri notify "dev server is up"
bateri commands lists every command and its options.
Ids
Everything is named by an id, a letter and a number: p9 a pane, t3 a tab, g1 a group, w1 a window. The commands that open something print the pane, and bateri ls lists every window, group and tab by the same names. An id never changes when the thing moves, and a number is not given twice.
A pane you open yourself (⌘D, ⌘T) has a number too, so bateri send p3 'q' reaches it.
A label is information, not a name. --label server shows on the pane, but no command takes a label in place of an id.
Where a command acts
The kind is always written: close tab t3, never close t3. An id of another kind, as in close group t3, is a mistake that says what to write. With no id, the command acts on the one it runs in:
bateri close tab # the tab this runs in
bateri zoom # the pane this runs in
Opening panes
split opens a pane beside this one, tab a tab next to it and window a window of its own. After -- comes the program to run; without one the pane runs bateri’s shell. The program is started directly, not by your shell, so an alias or a function is not found there; for a pipe or &&, run a shell: bateri split -- sh -c 'make && make test'. A program that is not there opens no pane: the command says it cannot be started and exits 1.
bateri split --right -- make test
bateri tab -- make watch
bateri window -- make watch
The keyboard stays where it was: a pane opened for a dev server doesn’t take your typing. --focus gives it the keyboard. --keep-open keeps the pane when its program ends, and --wait makes the command wait for the program and exit with its status, so a script can run a step in a pane of its own:
bateri split --wait -- make test && bateri notify "tests passed"
A shell named alone, as in bateri split -- zsh (also fish, and bash 4.4+), is a shell, with its dock and bateri in it. Anything else is a program: no dock, and the pane goes with it.
Talking to a pane
bateri send p9 'q' # type into a pane
bateri send-key p9 enter
bateri capture p9 # what is on its screen
bateri wait p9 # until its program ends; exits with its status
Floating panes
A floating pane is a card over the tab’s other panes, with its own place and size. split --float opens one, move pane --float lifts a pane out of its place and --dock puts it back. Places and sizes are percents of the tab.
--minimized opens it as a capsule from the start: the card is never seen, and the pane stays open when its program ends. It is the way to run a dev server that should not cover the tab.
bateri split --float --at 60,10 --size 35,40 -- htop
bateri split --float --minimized --label 'dev server' -- npm run dev
bateri minimize p9 # a capsule; again, and it opens where it was
The keyboard has one rule
A command that would change where you type, such as focus, move, zoom, swap, resize or split --focus, is done only from the pane the cursor is in, or while bateri is behind, or in a window other than the one you are typing in. Otherwise it is refused and says so. bateri notify is how to ask you to look.
What a machine may do
Each machine has a level, off, own, screen or full, and nobody is asked. own, the default, lets a program manage the panes of its own machine. On this Mac it is level in the [commands] section of your settings, or Programs on this computer may in Settings ▸ Shell. With "off" the command isn’t there at all. On a server says what each level allows.
In scripts
The commands that open something take --json and print the pane with the tab, group and window it stands in; bateri ls --json lists everything. A command ends with one of these statuses:
| Status | Meaning |
|---|---|
0 |
Done |
1 |
Failed |
64 |
A mistake in the command |
69 |
It needs bateri, and none is connected |
77 |
Refused |
wait and --wait end with the program’s own status.
Cron jobs call the command by its full path, ~/.local/share/bateri/shell/bin/bateri: one line that starts the bateri command of kablo, so it is the same program on every machine.