# CLI reference

> Every hive command, grouped by what it does, with its options and exit codes.

Source: https://hivemind.griiken.com/guide/cli/

Every `hive` command, for Hivemind <Version />. `hive <command> --help` lists every option your version has.

<AgentPrompt description="Paste this into your coding agent to turn these commands into a script that hands work to several agents and collects their replies." page="cli">{`
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.
`}</AgentPrompt>

## How `hive` works [#how-hive-works]

- `--json` prints the result as one JSON object on one line on stdout. A failure is `{"error":{"code":"…","message":"…","fix":"…"}}` on stderr (`fix` when there is one), and exits non-zero: `hive <command> --help` ends with the exit codes. An unknown flag is a usage error (exit 2).
- The issue commands edit files, and work without the app. `hive ctl` drives the running app or `hive host`.
- In an agent's terminal, `hive ctl` acts as that agent in its workspace. Elsewhere it acts as you: in the workspace `--repo` names, else the open one your folder is in, else the only one open. With `HIVE_DRIVE_TOKEN` set, it acts as that program ([API](https://hivemind.griiken.com/guide/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 [#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]

`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 [#issues]

To track work as Markdown files in `.hivemind/`. These work without the app. Guide: [Track work as issues](https://hivemind.griiken.com/guide/issues/).

```text
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.

```text
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 links
```

```text
hive 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 each
```

## `hive ctl`: agents and tiles [#hive-ctl-agents-and-tiles]

To start, message, read and close agents and tiles in the running app. Guide: [Coordinate agents](https://hivemind.griiken.com/guide/agent-workflows/).

```text
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 shown
```

`hive 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`.

```text
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 terminal
```

## `hive ctl`: plugins [#hive-ctl-plugins]

To open plugins and run the commands they offer. Guide: [Plugins](https://hivemind.griiken.com/guide/plugins/).

```text
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 canvas
```

The **Windows** view answers these commands while it is the view shown:

```bash
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 unsplit
```

## Plugins [#plugins]

To write, check, install, list and remove agents, views, widgets, tools, themes, live wallpapers and packages, and change their settings. Guide: [Packages](https://hivemind.griiken.com/guide/packages/), [Make a live wallpaper](https://hivemind.griiken.com/guide/live-wallpapers/).

```text
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 removed
```

A 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 [#api-tokens]

To let a program of yours drive a workspace. Guide: [Make an API token](https://hivemind.griiken.com/guide/api-tokens/).

```text
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 [#settings-and-upgrade]

To read and change settings, themes, the installed version and what it changed in your data. Guide: [Settings](https://hivemind.griiken.com/guide/settings/), [Update and roll back](https://hivemind.griiken.com/guide/update-and-roll-back/).

```text
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](https://hivemind.griiken.com/guide/data-updates/).

## Host [#host]

To keep workspaces and agents running on a server. Guide: [Keep agents running while your laptop sleeps](https://hivemind.griiken.com/guide/host/).

```text
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 running
```

## Sharing and people [#sharing-and-people]

To invite people into a workspace and set their roles. Guide: [Share a workspace](https://hivemind.griiken.com/guide/multiplayer/).

```text
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 it
```

## Review comments [#review-comments]

To read and answer comments left on an agent's changes. Guide: [Review an agent's changes](https://hivemind.griiken.com/guide/review/).

```text
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 agent
```

## Terminals that outlive the app [#terminals-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.

```text
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 process
```

## Machines [#machines]

To add other computers over ssh. Guide: [Run agents on another computer](https://hivemind.griiken.com/guide/machines/).

```text
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 running
```

## Network and notifications [#network-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](https://hivemind.griiken.com/guide/self-hosting/), reference: [hive-net](https://hivemind.griiken.com/guide/hive-net/).

```text
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 | off
```

### `hive notifications` [#hive-notifications]

The app's toasts, popups and sounds: the `notifications` settings ([Settings](https://hivemind.griiken.com/guide/settings/#notifications)). Guide: [Know who is waiting](https://hivemind.griiken.com/guide/know-who-is-waiting/#hear-it).

```text
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, popups
```

`set` 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) [#packages-preview]

To check a package before anything installs it. Installing packages is not built yet.

```text
hive packages inspect <dir>             # check a bundle and show what it would start, running nothing
```

<LastValidated />