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 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
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.
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 |
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.
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 has the
listeners and who they let in.
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.