---
title: The CLI
section: Automate
order: 20
description: Every hive command, its options, and its exit codes.
---

# The CLI

`hive` is the server and the command-line interface in one program. Inside a
hive terminal it is already on `PATH`.

Commands, flags and exit codes are stable. They break only in a new major
version, and the
[changelog](https://github.com/manueltarouca/hive/blob/main/CHANGELOG.md)
lists every change.

A command acts on the session and pane it runs in. `-s`, `-w` and `-b` choose
another session, tab or pane; [Sessions, tabs and panes](./sessions#choosing-what-a-command-acts-on)
says how they match. Every command takes these, and `-S` for another server.

## Sessions

| Command | Does |
| --- | --- |
| `hive ls` | List sessions |
| `hive new [LABEL] [--cwd DIR] [-- CMD…]` | Create a session |
| `hive session inspect` | Show a session's windows, layout and blocks |
| `hive kill SESSION` | Close a session and everything in it |

## Panes

The CLI calls a pane a block and a tab a window.

| Command | Does |
| --- | --- |
| `hive run [opts] [-- CMD…]` | Open a terminal in a new window |
| `hive split [opts] [-- CMD…]` | Open a terminal beside the current one |
| `hive move [--split SIDE] TARGET` | Move the block beside another |
| `hive block inspect` | Show a block, its methods, and its program |
| `hive label TEXT` | Label the block. `--session` or `--window` label those. |
| `hive zoom [--on\|--off]` | Zoom the block |
| `hive focus [left\|right\|up\|down]` | Focus the block, or its neighbor |
| `hive close [--window\|--session]` | Close the block, its window, or its session |

`run` and `split` take:

| Option | Does |
| --- | --- |
| `-- CMD…` | Runs a command instead of a shell. No shell parses it. |
| `--cwd DIR` | Sets the working directory. Without it, the CLI's own; a block created through the API without one starts in the server account's home. |
| `--label TEXT` | Labels the new block. |
| `--split right\|left\|above\|below` | Where the new block goes. |
| `--ratio PCT` | The new block's share of the split. |
| `--focus=false` | Leaves focus where it was. |
| `--keep-open` | Keeps the terminal after its command exits. |
| `--wait` | Waits for the command and exits with its status. |

## Input and output

| Command | Does |
| --- | --- |
| `hive send TEXT` | Types text. Reads stdin with `-` or no text. |
| `hive send-key KEY…` | Presses keys: `enter`, `ctrl+c`, `up`, `shift+tab`… |
| `hive capture [--trim] [--unwrap] [--format text\|vt]` | Prints the screen and scrollback |
| `hive capture --tail N` | Prints the screen's last N lines that show something |
| `hive wait [--for DUR] [TARGET]` | Waits for a program to exit, or a window or session to close |
| `hive events [--all] [--since N]` | Streams events |

## Agents

| Command | Does |
| --- | --- |
| `hive agents` | List agents, blocked first |
| `hive agent install claude` | Add hive's hooks to Claude Code |
| `hive agent uninstall claude` | Remove them |
| `hive agent hook HARNESS` | Run by an agent's hooks |

## Scripts

| Command | Does |
| --- | --- |
| `hive script run FILE [KEY=VALUE…]` | Run a TypeScript or JavaScript file on the server, once. Its log goes to stderr, its result to stdout as JSON. Ctrl-C stops it. |
| `hive script run -e CODE` / `-` | Run code from the command line, or from stdin |
| `hive script stop RUN_ID` | Stop a running script |
| `hive script ls` | Scripts in the scripts folder, running one-shots, and the latest that ended |
| `hive script grant NAME` / `revoke NAME` | Let a script in the folder run with what it asks for, or take that back |
| `hive script enable NAME` / `disable NAME` | Turn a script in the folder on or off |
| `hive script watch NAME` / `act NAME` | Let a script only watch (it may look, mark panes and notify; every change it tries is refused and listed), or act again |
| `hive script set NAME KEY=VALUE…` | Change a script's switches, the options it declares |
| `hive script show NAME` | One script: what it is, may do, its switches, and what it did lately |
| `hive script add [NAME…]` | List the starter scripts, or copy one into the scripts folder |
| `hive script reload [NAME]` | Load the folder again now |
| `hive script logs NAME [-f]` | A script's log |
| `hive script audit [NAME] [-f]` | What scripts did, and what people did to them; `-f` keeps following |
| `hive actions` | The actions scripts offer |
| `hive do ACTION [KEY=VALUE…]` | Run one, from the pane you're in |
| `hive keymap [--client mac]` | What keys do in an app, and where each binding came from |
| `hive script check FILE` | Bundle a script and report errors, without running it |
| `hive script types [--out FILE]` | Write `hive.d.ts`: this server's methods as TypeScript types, for your editor |

`script run` takes `--allow PERMS` (such as `control,spawn`; read only
without it), `--args JSON`, `--for DUR` (stop it after that long) and
`--all` (hear every session's events). See [Scripts](./scripts).

## API and server

| Command | Does |
| --- | --- |
| `hive api list [-q]` | Every server method |
| `hive api describe METHOD` | A method's arguments and result, as JSON Schema |
| `hive api call METHOD [JSON\|@FILE\|-]` | Call a method |
| `hive server run [--fresh]` | Run the server in the foreground |
| `hive server start` / `stop` / `status` | Manage a background server |
| `hive version` | Print the version. It doesn't start a server. |
| `hive config path\|default\|check\|show\|set\|reload` | The settings file; see [Settings](./settings#commands) |
| `hive help` | List the commands |

Every command takes `--json` for output a script can parse.

Some things have no command of their own and go through `hive api call`:
pinning a tab (`session.pin_window`), for example. See [the server
API](./api).

## Remote hosts

Any command runs against another machine's server with `-S`. The server
there must listen on your tailnet (`hive server start --tailscale`, or
`--extra-listen tailnet://:4483`), and let you in: by default only the
Tailscale user who owns that machine. [Remote hosts](./remote) has the
listeners and who they let in.

```sh
hive -S https://box.example.ts.net ls
hive hosts add box https://box.example.ts.net
hive -S box new build -- make
hive -S box whoami
```

| Command | Does |
| --- | --- |
| `hive hosts [ls]` | The servers you've named |
| `hive hosts add LABEL URL [--always\|--on-demand]` | Name one. The app shows the same list, and connects when you pick it (`--on-demand`, the default), or with `--always` at launch, staying connected (its agents' status and notifications stay live). Saved again without a flag, a host keeps its choice. |
| `hive hosts rm LABEL` | Forget it |
| `hive whoami` | Who the server thinks you are, and how you reached it |
| `hive client ls` | The apps connected to a server, and as whom |

`-S` takes:

| Value | Means |
| --- | --- |
| `/PATH`, `./PATH`, `~/PATH` | A Unix socket on this machine |
| `https://HOST`, `http://HOST:PORT` | A remote server |
| `LABEL` | A host saved with `hive hosts add` |
| `HOST` | A remote server, tried at `https://HOST`, then `https://HOST:4483`, then `http://HOST:4483` |

`HIVE_SERVER` is always a socket path: hive sets it in every terminal.

Hosts are kept in `hosts.json`, next to the settings file. A bare host is
saved as the URL it answered at. A command never starts a server on another
machine. A block created there without `--cwd` starts in that account's
home; `--cwd` is an absolute or `~` path on that machine. `config` edits this
machine's settings; for a remote server's, use `hive -S HOST api call
config.set`.

## Exit status

| Status | Meaning |
| --- | --- |
| 0 | It worked |
| 1 | It failed |
| 2 | The command line was wrong |
| 3 | A target was not found or matched more than one thing |
| 4 | The server could not be reached |
| 5 | The server refused you |
| 130 | It was interrupted |

`wait` and `run --wait` exit with the program's own status.