CLI reference
Every hive command, grouped by what it does, with its options and exit codes.
Every hive command, for Hivemind 2026.10.3. hive <command> --help lists every option your version has.
Paste this into your coding agent to turn these commands into a script that hands work to several agents and collects their replies.
Show the prompt
Using the hive commands on this page and `hive <command> --help`, write a shell script that hands one task to several coding agents in my Hivemind workspace, waits for every reply, and handles each exit code.
1. Check the setup: `hive --version` works, and `hive ctl agents --json` exits 0 inside my project. Exit 3 means neither the app nor `hive host` runs: ask me to open the project with `hivemind <folder>`. See which agents can start with `hive agents list --found`.
2. Ask me for the task, the list of items (files, packages, questions), and which agent to use.
3. For each item: `hive ctl spawn --agent <agent> --prompt "<task> for <item>" --name "<item>" --json` prints `{"tile": …}`; keep the tile ids. Then for each tile: `hive ctl read <tile> --timeout 10m --json`. Handle the exit codes in the table on this page: 4 read again; 5 the tile was closed; 7 the agent is idle or cannot say when it finishes; 8 it waits on an answer; 9 it is asleep (wake it with `hive ctl wake <tile>`) (show me its question from `hive ctl agents --json` and stop).
4. Print each item with its reply, then close the tiles with `hive ctl close <tile>` unless I ask to keep them.
5. Run it on two small items first and show me the output.
If a step needs anything only I can do, such as a login, ask me and wait.
REFERENCE https://hivemind.griiken.com/guide/cli.mdHow hive works
--jsonprints the result as one JSON object on one line on stdout. A failure is{"error":{"code":"…","message":"…","fix":"…"}}on stderr (fixwhen there is one), and exits non-zero:hive <command> --helpends with the exit codes. An unknown flag is a usage error (exit 2).- The issue commands edit files, and work without the app.
hive ctldrives the running app orhive host. - In an agent's terminal,
hive ctlacts as that agent in its workspace. Elsewhere it acts as you: in the workspace--reponames, else the open one your folder is in, else the only one open. WithHIVE_DRIVE_TOKENset, it acts as that program (API). - You name a workspace by its folder, its folder's name, its id (four characters or more) or its issue prefix. A name two workspaces share is refused, and both are listed.
Exit codes
Every hive command exits with one of these. This is the one list; other pages link here.
| Exit | code in --json | Meaning |
|---|---|---|
| 0 | ok | |
| 2 | BAD_REQUEST, UNKNOWN_METHOD | usage — the error lists valid values |
| 3 | UNAVAILABLE | neither the app nor hive host is running |
| 4 | TIMEOUT | a wait ran out (read, open-review, workflow) |
| 5 | NOT_FOUND, NO_BROWSER_TILE, NO_ELEMENT, ATTACHMENT_MISSING | no such tile, frame, issue, workspace, Browser tile, element on the page or file |
| 6 | FORBIDDEN | a bad or missing token, or a call the caller may not make |
| 7 | UNSUPPORTED, RATE_LIMITED, DEPTH_EXCEEDED, OCCLUDED, PART_OF_A_PACKAGE, SEVERAL_BROWSER_TILES, SEVERAL_ELEMENTS, ATTACHMENT_TYPE, ATTACHMENT_TOO_BIG, ATTACHMENT_NOT_A_NOTE, REVIEW_PICTURES | refused — the runtime cannot do this, or not now; read of an idle agent with nothing new; sleep or wake that did nothing for a reason other than it being so already; tile look of a tile something is drawn over; a plugin that is part of a package changes only with it |
| 8 | read only: the agent stopped to wait on an answer (a question, a permission) | |
| 9 | ASLEEP | the agent is asleep: send, keys, read and connect to it are refused (a report to it waits in its inbox); the fix is hive ctl wake <tile> |
| 1 | FAILED | other |
hive ctl read
hive ctl read <tile> waits for an agent to finish replying. Its exit code says how the wait ended:
| Exit | Means | Do |
|---|---|---|
| 0 | The agent replied. With awaiting, it still waits on that many background tasks it started. | Use the reply it printed. With awaiting, read again for what comes of them. |
| 4 | It is still working. | Run read again. |
| 5 | Its tile was closed. | Start it again if you still need it. |
| 7 | It was sent nothing new, and is idle. | Send it a task. |
| 8 | It stopped to ask you something. | Answer it, then read again. |
| 9 | It is asleep. | Wake it with hive ctl wake <tile>. |
Issues
To track work as Markdown files in .hivemind/. These work without the app. Guide: Track work as issues.
hive init --prefix MYP [--no-agentic] # create tracker (+ agentic stack by default)
hive init # refresh the agentic stack
hive add skill # refresh the skills only
hive guide agents # print the agent guide this hive ships (also work, browser, workflow)
hive new "Title" [--label l …] [--parent ID] [--state backlog] [--github N]
[--assignee claude --assignee-type agent] [--assignee-model m]
[--description d] [--ac "criterion one || criterion two"]
hive list [--state todo] [--assignee id] [--label l] [--parent none|ID]
hive show MYP-1
hive update MYP-1 [--state s] [--title t] [--assignee id|none]
[--add-label l] [--rm-label l] [--github N|none] [--note "…"]
hive close MYP-1 [--reason "…"] [--note "…"] # --reason → cancelled, else done
hive reopen MYP-1 [--state todo] [--note "…"]
hive task MYP-3 add "Subtask" [--assignee id] [--state todo] # sub-issues: MYP-3.1, …
hive task MYP-3 done 2 # tail number or full id
hive task MYP-3 list.hivemind has to be a real folder. A link there is not treated as a workspace, and hive init refuses it.
hive link MYP-4 --parent MYP-1 # re-parent, or --parent none
hive relate MYP-4 OPS-7 [--type blocks] [--remove]
# relates | blocks | blocked-by | duplicates |
# parent-of | child-of | moved-to | moved-from
hive move MYP-4 OPS [--copy] # move refuses issues with sub-issues
hive workspace list
hive workspace register
hive agent detect # detect agent CLIs
hive agent context [--state todo] # regenerate .agent.md
hive resolve "text" # expand @ID mentions to markdown linkshive ctl set-state MYP-1 in_progress [--note "…"]
hive ctl add-comment MYP-1 "root cause found in …"
hive ctl mark-acceptance MYP-1 0 [--undone] # 0-based index from hive show --json
hive ctl delete-issue MYP-1 # irreversible
hive ctl list-workspaces # prefix, title and folder of eachhive ctl: agents and tiles
To start, message, read and close agents and tiles in the running app. Guide: Coordinate agents.
hive ctl whoami # which app (hivemind or hivemind-dev), its data folder and
# sockets, and you: person, agent or program; workspace,
# tile and session
hive ctl agents [--watch] [--session <id>]
# the workspace's agents, their state, what each waits on
# and its last line;
# --session: the one in that session (exit 5: none)
hive ctl tiles # every tile: agents, terminals, tools, browsers
hive ctl frames # frames an agent may start in: id, name, machine
hive ctl frame add --folder /srv/web [--machine build] [--name web]
# a frame on that folder, on a saved machine or one of
# your devices by id or name; → {"frame","path","opened"}
hive ctl spawn [--agent claude] [--prompt "…"] [--name "title"]
[--frame <id or name>] [--mode plan] [--model sonnet]
[--no-report] [--supervise all|Bash,Edit] [--resume <session>]
# → {"tile":…}; workers auto-report by default;
# --mode yolo: the agent asks nothing
hive ctl sessions [agent] [--cwd dir] [--limit 100]
# past sessions in a folder, to --resume
hive ctl send <tileId> "text" [--interrupt] # after its turn; --interrupt: stop the turn first
hive ctl keys <tileId> Down,Enter # Esc, Tab, digits, …
hive ctl read <tileId> [--timeout 90s] [--poll] # default wait 100 s; --poll: no wait; idle with nothing new: exit 7
# exit 4 timeout, 5 closed, 7 idle, 8 waits on an answer, 9 asleep
hive ctl inbox [--wait 90s] [--tile id] # what other agents sent you, each once (--wait at most 10m)
hive ctl stream <tileId> [--lines 40] [--timeout 30s]
[--snapshot] [--json] # what it prints, live; --lines: the last N first
hive ctl focus <tileId>
hive ctl tile look <tileId> [--out f.png] [--json] # brought into view, waited for until it drew:
# {tile, state, drew, console, png} (png: the picture's path)
hive ctl close <tileId> # ends what runs in it; exit 5 if it is not open
hive ctl sleep [tile|frame] [--force] # its process ends, its screen and conversation kept; none: every agent
hive ctl wake [tile|frame] # back in its conversation; awake already is exit 0; exit 7 if nothing woke for another reason
hive ctl rename <tileId> ["name"] # no name: back to what its agent says it is doing
hive ctl send-file <file> [--tile t] # a copy for the person's phone, in this agent's chat, kept 7 days; at most 32 MiB
# exit 7 with no phone paired or a file too big; "ready" does not mean it arrived
hive ctl sent-files [--tile t] # what this agent sent and is still kept
hive ctl take-back-file <id> # the phone no longer shows or fetches it; exit 5 if it is not kept
hive ctl connect <src> <dst> # src's finished replies go to dst's inbox; dst is told by one line typed into it, which starts a turn
hive ctl disconnect <src> [<dst>]
hive ctl open-tool <owner/name/tool> [--frame f] [--url https://…]
# open a tile of a tool that is switched on
hive ctl view emit <name> ['{"json":1}' | -] [--view id]
# a named event to the view shownhive ctl agents --json prints {"seq": 3, "agents": [ … ]}: seq is the agent feed's position (--watch prints the events after it), and each agent is {"tile", "name", "agent"?, "workspace": {"id", "name"}, "state", "since", "machine", "waiting"?, "parent"?, "interrupt"?, "conversation"?, "session"?, "line"?}: name is the tile's name (spawn --name), agent the program it runs (spawn --agent), state is asleep for one put to sleep, and line is its last line as its row in the Layers panel says it: what it last said, or for an agent that keeps no conversation what its screen last showed, at most 160 characters. Without --json the line ends each agent's row as line: ….
hive ctl tiles --json prints {"tiles": [ … ]}, every tile of the workspace in order, each {"tile", "kind", "name", "frame", "state"?, "agent"?, "plugin"?, "tool"?}. kind is agent, terminal or tool, or the tile's own kind when it is none of those; an agent has its state and agent, a tool its plugin and tool ids. frame is null for a tile in no frame. session appears once the agent's hooks have said it; --session <id> also finds a tile by the session the app tracks to resume it.
hive ctl read gives an agent's reply to its turn, as clean text. hive ctl stream --snapshot gives the last lines its terminal printed, raw: escape codes stripped, but spinners, boxes and redraws left in. Read a reply with read; look at a screen with stream.
hive ctl workflow --shape fanout|pipeline|mapreduce
[--items "a || b"] [--prompt "Review {item}"]
[--stages "draft || critique || rewrite"] [--input "seed"]
[--reduce-prompt "Merge {results}"]
[--agent claude] [--model m] [--frame f] [--supervise all]
[--max-concurrent 6] [--timeout 10m] [--close] [--repo dir]
# per-worker timeout; blocks until all replies
hive ctl approve <reqId> allow|deny|always|never [--reason "…"]
hive ctl report "summary" [--tile id] # to the inbox of the tile that spawned you ($HIVEMIND_TILE)
hive ctl open-review --file plan.md|--plan "…" [--cwd dir] [--timeout 30m] [--tile id]
# default ceiling 24 h; --tile from a terminalhive ctl: plugins
To open plugins and run the commands they offer. Guide: Plugins.
hive ctl plugin list [--json] # every plugin running, each starting, ready or failed,
# with its commands; the views there are; and every
# widget, with the view it shows over alone (`view`)
hive ctl plugin open <record> [--frame f] [--json]
# get it running: a tool's tile opened, a widget added
# to the canvas, a view switched to; answers once it
# can be called
hive ctl plugin open <widget id> [--json] # that widget, as plugin list names it, shown over
# every view
hive ctl plugin commands [--json] # what the ready plugins let you run, with what each takes
hive ctl plugin call <plugin> <command> ['{"json":"argument"}' | -] [--tile id] [--json]
# runs it and prints what the plugin answered
hive ctl plugin close <instance | record> [--plugin p] [--json]
# close its tile, take the widget off the canvas,
# leave the view for the canvasThe Windows view answers these commands while it is the view shown:
hive ctl plugin call windows split-right # also split-down
hive ctl plugin call windows focus-left # also focus-right, focus-up, focus-down
hive ctl plugin call windows maximize # show the focused pane alone, or bring the others back
hive ctl plugin call windows close-pane
hive ctl plugin call windows unsplitPlugins
To write, check, install, list and remove agents, views, widgets, tools, themes, live wallpapers and packages, and change their settings. Guide: Packages, Make a live wallpaper.
hive plugins new tool|widget|view <name> [--dir folder] [--owner login]
# a starter that works, with PROMPT.md; prints the next steps
hive plugins new package <name> [--dir folder] [--owner login]
# a package that holds nothing yet, with PROMPT.md
hive plugins new wallpaper <name> [--dir folder] [--owner login]
# a live wallpaper that draws, in a package of its own that offers it once installed,
# with PROMPT.md and two skills for your coding agent
hive plugins new tool|widget|view|wallpaper <name> --in <package folder>
# a starter inside the package, named in its hivemind-package.json
hive plugins new theme <name> --in <package folder> [--dir folder]
# a theme.json of the look in use, in <package>/themes/<name>
hive plugins add <folder> --to <package folder>
# one already written, copied in when outside; another owner's id is refused
hive plugins check <folder> [--json] # its types, its manifest and its code drawn once; file:line for each problem
# of a package: hivemind-package.json and every member with its own check
# a live wallpaper, once built: drawn in headless Chromium (Playwright's) against a fake app
# it runs the plugin's code on this computer: check only what you would install
hive plugins install <folder>|<id> # a folder holding a plugin, or one from HiveHub by its id: installed as a package
# owner/name and @owner/name are always HiveHub's: a folder is ./x, ../x, /x or ~/x
# a tool arrives off: hive plugins enable @owner/name
# a package that opens with a view prints it and its command (--json: startView {id, name, open})
# one that offers a live wallpaper prints it and the command that uses it (--json: startWallpaper {id, name, use})
hive plugins install <folder>|<id> --dry-run # what an update would change, member by member; installs nothing
hive plugins rollback <package> # back to the version in use before its last update, switched as it was
hive plugins remove <plugin>|<package> # one you added on its own, or a whole package
# one plugin of a bigger package is refused (exit 7): remove the package
hive plugins reload # the running app loads every plugin again
hive plugins api --kind tool|widget|view # what its code is given, as the type declarations of this version
hive plugins search [words…] [--kind <kind>] [--limit N] # HiveHub's plugins: every word starts a word of it, best match first (20 by default, at most 100)
hive plugins list [--kind agent|view|widget|tool|wallpaper] # every plugin on this machine, on or off, and why any fails to load
hive plugins show claude # its settings: each one's value and what it takes
hive plugins enable @hivemind/web # or disable; a package by its id switches all it holds
# one plugin of a package can be switched off alone, on only while its package is on
hive plugins set @you/board columns all # checked against what the setting takes
hive plugins reset @you/board [columns] # back to its default
hive plugins workspaces <tool> <folder>… # the workspaces a tool's service drives (hive host)
hive plugins workspaces <tool> --none # it drives none: its service stops
hive agents list # every agent, its source, on/off, and why any failed
hive agents list --found # only agents whose CLI is on this machine
hive agents install amp # by its name on HiveHub; every file checked against its hash
hive agents install <dir> # a folder with agent.yaml; checked before it is copied
hive agents install owner/repo[/dir] [--ref tag] # from a GitHub repository
# downloaded ones print what they run first: re-run with --yes
hive agents validate <dir> # check a manifest the way an install would
hive agents remove <id> # removes the agent from this machine; it stays removedA plugin is named by its id. Where two kinds have the same id, name it as <kind>:<id>, as
hive plugins list prints it (view:board).
enable, disable, set, reset, choosing workspaces, and hive config set plugins.… are the person's to run. From an agent's tile or with a program's token they are refused (PERSON_ONLY, exit 6), saying what to ask the person to run.
API tokens
To let a program of yours drive a workspace. Guide: Make an API token.
hive grant create <name> -w <folder> [--role agents] [--expires 30d]
# a token for one program to drive these workspaces
hive grant list
hive grant revoke <id>Settings and upgrade
To read and change settings, themes, the installed version and what it changed in your data. Guide: Settings, Update and roll back.
hive config path
hive config get [dotted.path]
hive config set <path> '<json>'
hive theme list # the presets, and installed themes as @owner/package/theme
hive theme use nord # a preset
hive theme use @owner/kit/harbour # a theme: its files are copied beside settings.json
hive theme revert # back to the look before the theme
hive theme export f.json
hive theme import f.json
hive upgrade [--dev]
hive migrations [--json]
hive migrations restore <id> [--json]hive migrations lists what updates changed in this computer's data; restore puts it back as it was before a change. Guide: When an update changes your data.
Host
To keep workspaces and agents running on a server. Guide: Keep agents running while your laptop sleeps.
hive host run # serve until stopped (what a service runs); one host per machine
hive host status # whether it runs, as which device, where it is reached, its workspaces
hive host stop # stop serving; the terminals keep running in the background process
hive host pair # print six words, a link and a QR code for your app to enter
hive host add <dir> # serve a folder on this machine as one of its workspaces (through the app when it runs)
hive host install # run it as a service of yours (systemd): at boot, and again if it stops
hive host uninstall # stop running it as a service; its terminals keep runningSharing and people
To invite people into a workspace and set their roles. Guide: Share a workspace.
hive share <workspace> [--role view|edit|terminals] [--uses n] [--expires 7d]
# print an invite link (default: edit, one person, 7 days)
hive people requests # who is asking to join now, by number
hive people allow <n> [--role view|edit|terminals] # let them in, at their link's role or this one
hive people deny <n> # turn them away
hive people list # who is on the list, their roles, who is here now
hive people role <person> <role> # view, edit, terminals, or agents (only while they are here)
hive people remove <person> # take them off; their link stops working
hive people rule [ask|invite] # ask (default): you answer each request;
# invite: anyone with a valid link is let in at once
hive join <link> # join a workspace someone shared, waiting while they decide;
# yours to run in a terminal of your own, not from an agent's tile
hive network enrol-link [--data <dir>] [--uses n] [--expires 7d]
# on your network's server: a link that puts a device on itReview comments
To read and answer comments left on an agent's changes. Guide: Review an agent's changes.
hive review list [--file src/x.ts] [--status open|resolved|all] [--on page|diff]
hive review show <id> # one comment with its replies; a page note's elements and picture
hive review reply <id> "fixed in 3f2c1a"
hive review seen <id> # an open comment you are on; refused once it is closed
hive review resolve <id> [--summary "how it was addressed"] [--attach file]...
hive review dismiss <id> --reason "why it is not done"
hive review reopen <id> # only a resolved or dismissed one
hive ctl notes add --selector "<css>" --body "what you found" [--intent fix|change|question] [--tile <browser tile>] [--attach file]... [--json]
hive ctl notes add --area x,y,width,height --body "what you found" # page pixels, for what no selector names
hive ctl notes list [--status open|resolved|all] [--json] # the notes on pages
hive ctl notes show|seen|reopen <id>
hive ctl notes done <id> [--summary "what was done"] [--attach file]... # .webm .mp4 .png .jpg .gif, up to 200 MB each
hive ctl notes dismiss <id> --reason "why not"
hive ctl notes reply <id> "answer"
hive ctl notes watch [--timeout 300] # wait for the next note on a page; exit 4 on timeout
hive review watch [--timeout 300] [--file f] # wait for the next comment; exit 4 on timeout
hive ctl browser ask "Please sign in" [--tile t] [--timeout 90s] # the person does it in the tile; you wait and see nothing
hive ctl browser sign-ins # saved sign-ins, by name and site
hive ctl browser sign-in <name> [--tile t] [--timeout 90s] # the app types it once the person says yes; you never see the password
hive ctl browser wait <ask> # go on waiting: the question stays up for 5 minutes
hive ctl browser asks # the questions waiting on the person
hive ctl browser answer <ask> yes|always|no|done # the person's; refused to an agentTerminals that outlive the app
To run terminals in the background process, which keeps them alive while the app is closed. Add --machine <name> to reach a saved machine.
hive daemon start|status|stop # the background process; stop keeps sessions as snapshots, restored on start
hive ps [--machine build-box] # the sessions running
hive run [--attach] [--cwd dir] [--id name] -- npm run dev
# start one; with --attach, ctrl-b d detaches
hive attach <session> [--read-only] # view and type into one; a unique prefix of its id is enough
hive kill <session> # end it and its processMachines
To add other computers over ssh. Guide: Run agents on another computer.
hive machine add me@build-box [--label build] [--install-hive]
# also an ssh alias or ssh://me@build-box:2222;
# terminals over plain ssh; --install-hive puts this
# version's hive in ~/.hivemind/bin there (not on Windows)
hive machine list
hive machine check build # reachable, platform, hive path and version
hive machine install-hive build [--off] # put hive there now; --off: plain ssh for new terminals
hive machine rename build gpu-box
hive machine disable build # kept, not connected; enable turns it back on
hive machine remove build # forgotten; its sessions there keep runningNetwork and notifications
To choose how your devices reach each other, and to get a push when an agent needs you. Guide: Set up your own network server, reference: hive-net.
hive network show # which network, who signed it, its servers
hive network use local # or a network link, or a signed profile's file
hive network doctor # whether its relays answer this computer
hive push set https://ntfy.sh/<your-topic> [--events input.requested,turn.ended]
# a plain-text POST when an agent on this machine needs you
hive push status | test | offhive notifications
The app's toasts, popups and sounds: the notifications settings (Settings). Guide: Know who is waiting.
hive notifications show [--json]
hive notifications set <key> <value> # sound on, sounds.done on, volume 0.4 (or 40%), dnd.start 22:30
hive notifications play needs|done|error [--json]
# plays it in the app: {played, why?, pack?}
hive notifications recent [--json] # the last 10 moments: agents, sound, popupsset and play are the person's: an agent is refused them (PERSON_ONLY, exit 6). play and
recent need the app running; without it they exit 3 (UNAVAILABLE). set reloads the app.
Packages (preview)
To check a package before anything installs it. Installing packages is not built yet.
hive packages inspect <dir> # check a bundle and show what it would start, running nothingLast validated for Hivemind 2026.10.3.