# 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:

```sh
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](https://bateri.dev/docs/commands.md) 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:

```sh
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.

```sh
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:

```sh
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

```sh
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.

```sh
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](https://bateri.dev/docs/servers.md) 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.
