Automate

The bateri command

In every terminal bateri opens, a program, a script or an agent can open panes beside you, type into them, read their screen and send you a notification.

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.