Hive command-line reference

Every hive command and option: new, list, attach, kill, agents, workspace, worktree, report-agent, doctor, update and daemon, with examples.

hive is both the interface and a command line. Every command talks to the daemon, starting it if needed, so sessions you create from a script show up in the interface and the other way round. hive --help and hive <command> --help print the same information.

SESSION is a session id, as shown by hive list and in the sidebar. WORKSPACE is a workspace name or id.

`hive`

Open the interface. Reattaches to the newest live session, or shows the start screen. Starts the daemon if it isn't running (unless [daemon] auto_start = false).

`hive new [AGENT] [-- ARGS...]`

Launch an agent in a new session and attach to it. AGENT is any name from hive agents, shell, or one from [agents.*]; without it, [general] default_agent.

Option	Meaning
`-l, --label <LABEL>`	Session label (defaults to the agent name)
`-C, --cwd <DIR>`	Working directory (defaults to the current directory)
`-W, --workspace <WORKSPACE>`	Workspace name or id (defaults to the one containing the directory)
`-w, --worktree`	Run in a new git worktree on branch hive/<agent>-<id>
`-b, --branch <BRANCH>`	Branch for the worktree (implies --worktree; created if missing)
`-d, --detached`	Create the session without attaching

hive new claude -l api -C ~/src/api
hive new codex -w                 # own worktree
hive new codex -b fix/login       # own worktree on branch fix/login
hive new shell -d -l db           # a background shell
hive new claude -- --model opus   # arguments after -- go to the agent

`hive list`

List sessions with id, label, agent, state, workspace, branch and directory.

`hive attach <SESSION>`

Open the interface on session SESSION (its id).

`hive kill <SESSION>`

Terminate a session and remove it. Hive sends SIGHUP and SIGTERM to its process group, then SIGKILL after [daemon] kill_timeout_secs.

`hive status`

One-line summary of the daemon and its sessions.

`hive agents [-a]`

List the agents Hive can launch and recognise, and which are installed. -a also lists known agents that are not installed.

`hive workspace list`

List workspaces (spaces).

`hive workspace add <PATH> [-n NAME]`

Add a workspace for a directory (its repository root inside git).

`hive workspace rename <WORKSPACE> <NAME>`

Rename a workspace.

`hive workspace rm <WORKSPACE>`

Forget a workspace that has no sessions. Nothing on disk changes.

`hive worktree list [-W WORKSPACE]`

List a repository's worktrees: branch, clean or modified, path, and the sessions running in each.

`hive worktree rm <PATH> [--force] [-y]`

Remove a worktree. Refused while a session runs in it, and refused with uncommitted changes unless --force (which asks to confirm unless -y). The branch is always kept.

`hive report-agent --agent <NAME> --state <STATE> [--message TEXT] [--seq N] [SESSION]`

Report an agent's status for a session: idle, working, blocked or unknown. Meant for agents and scripts; SESSION defaults to $HIVE_SESSION_ID.

Reports numbered (--seq) at or below the last one are ignored, so late reports can't overwrite newer ones. The default is the current time in milliseconds.

"$HIVE_BIN_PATH" report-agent --agent mybot --state blocked --message 'approve edit?'

`hive release-agent --agent <NAME> [SESSION]`

Clear an agent's status report; screen detection takes over again.

`hive doctor`

Check the installation: config file and whether it is valid, socket path, daemon, logs, detected colours and glyphs, and which agents are on PATH. Changes nothing, never starts the daemon, and exits non-zero on a problem.

`hive update [--tag vX.Y.Z]`

Install the latest release (or --tag) next to the running hive, verifying its SHA-256 checksum. Linux and macOS. A running daemon keeps the old version until hive daemon stop.

`hive daemon start`

Start the daemon if it isn't running.

`hive daemon stop`

Stop the daemon. This terminates every session.

`hive daemon status`

Show whether the daemon is running, with its version, pid and socket.

Exit codes and scripting

Commands exit with 0 on success and non-zero with a message on stderr otherwise. hive new -d prints created session 4 (codex) in /path, so a script can start several agents in the background and open them later with hive or hive attach 4.