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.

OptionMeaning
-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, --worktreeRun in a new git worktree on branch hive/<agent>-<id>
-b, --branch <BRANCH>Branch for the worktree (implies --worktree; created if missing)
-d, --detachedCreate 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 notes [DIR]

Open the notes app on the vault for the current directory (a folder with .obsidian/ in this repository), or DIR: a note tree, rendered notes, links, backlinks, search, new and daily notes. Press ? inside for keys.

Find notes about something, best first, as path:line with the matching line. For agents and scripts.

hive context search how are dirty worktrees handled

hive context get <NOTE> [--json]

Print a note (by link name, path, or the start of its name), then what it links to and what links to it.

hive context list [-n N] [--json]

List notes, most recently changed first, with their tags.

hive context add <NOTE> [TEXT...] [--by NAME]

Append a dated entry to a note (created if missing), signed with the session. The text is the remaining arguments or standard input. Never rewrites a note.

hive context add Hive/Decisions "Tokens expire after 1h"

hive context path

Print the vault's path.

Every context command takes --vault DIR; otherwise it uses $HIVE_VAULT (set in Hive sessions), else the vault found from the current directory.

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 [-y]

Stop the daemon. This terminates every session, so it lists them and asks first (-y skips the question). They come back as ended sessions: Ctrl+Space R in hive restores them all, and agents resume their last conversation.

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.

Something wrong or missing? Open an issue.