vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

hive-forge, hivectl, swarmctl: fix clap help passive voice, regen docs

Browse source 
Rewrites every write-good.Passive hit in the hive-forge clap help text
into terse, imperative, active voice (meaning unchanged) and drops
clap-markdown's own fixed footer ('This document was generated
automatically by...') via MarkdownOptions::show_footer(false), since
that string isn't ours to reword and vale flagged it too.

docs/tools/{hivectl,swarmctl,forge}-cli.md are generated from each
crate's clap tree (see hive-forge/src/main.rs's MarkdownDocs verb) —
regenerated here from the fixed source, not hand-edited.

Refs #4549
This commit is contained in:
atlas 2026-09-20 05:38:30 +02:00 • committed by mara
commit f0e3ed04d3
18 changed files with 87 additions and 89 deletions
Download patch file Download diff file Expand all files Collapse all files

70
docs/tools/forge-cli.md
View file

@ -143,7 +143,7 @@ Issue-scoped commands: `issue <show|create|edit|view|comment|comments|close|reop
* `reopen` — Reopen a closed issue
* `labels` — List / add / remove labels
* `assign` — Assign or unassign a user
* `dependency` — List / add / remove dependencies (issues this one is blocked by)
* `dependency` — List / add / remove dependencies (issues blocking this one)
* `reaction` — List / add / remove emoji reactions on the issue, or on one of its comments with `--comment <id>`
* `timeline` — List timeline events
@ -173,7 +173,7 @@ Create an issue
* `--body <BODY>` — Inline body text
* `--body-file <BODY_FILE>` — Read body from a file. `-` means stdin
* `--assignee <ASSIGNEE>` — Initial assignee login
* `--label <LABELS>` — Label name to attach, repeatable (for example `--label area/ops --label type/bug`). Same spelling `labels add` accepts. An unresolved name errors out (before the issue is created) rather than silently attaching fewer labels than asked for
* `--label <LABELS>` — Label name to attach, repeatable (for example `--label area/ops --label type/bug`). Same spelling `labels add` accepts. An unresolved name errors out (before creating the issue) rather than silently attaching fewer labels than asked for
@ -243,7 +243,7 @@ List comments on the issue
###### **Options:**
* `--limit <LIMIT>` — Number of comments from the start of the thread (oldest-first), or (with `--since`) the most this call returns — capped at [`crate::verbs::MAX_LIMIT`] in the latter case. An explicit opt-in: with neither this nor `--tail` given, the default is the newest 10 (see `--tail`). Mutually exclusive with `--tail`
* `--tail <TAIL>` — Return the last `N` comments (chronological) — the most recent activity. This is the default (`N` = 10) when neither `--limit` nor `--tail` is given. Mutually exclusive with `--limit`/`--since`
* `--tail <TAIL>` — Return the last `N` comments (chronological) — the most recent activity. Defaults to `N` = 10 when you pass neither `--limit` nor `--tail`. Mutually exclusive with `--limit`/`--since`
* `--since <SINCE>` — Only show comments at or after this RFC3339 timestamp (same format this verb's own output prints). Mutually exclusive with `--tail`
* `--show-reactions` — Fetch + display each shown comment's reaction summary. Costs one extra request per comment shown — opt-in, not the default
@ -281,7 +281,7 @@ List / add / remove labels
###### **Subcommands:**
* `list` — List labels (default when no action is given)
* `list` — List labels (default when you give no action)
* `add` — Add labels by name
* `remove` — Remove labels by name
@ -293,7 +293,7 @@ List / add / remove labels
## `hive-forge issue labels list`
List labels (default when no action is given)
List labels (default when you give no action)
**Usage:** `hive-forge issue labels list`
@ -342,14 +342,14 @@ Assign or unassign a user
## `hive-forge issue dependency`
List / add / remove dependencies (issues this one is blocked by)
List / add / remove dependencies (issues blocking this one)
**Usage:** `hive-forge issue dependency <NUMBER> [COMMAND]`
###### **Subcommands:**
* `list` — List dependencies (default when no action is given) — the issues/PRs this one is blocked by
* `add` — Add one or more issues/PRs this one is blocked by
* `list` — List dependencies (default when you give no action) — the issues/PRs blocking this one
* `add` — Add one or more issues/PRs that block this one
* `remove` — Remove one or more dependency links
###### **Arguments:**
@ -360,7 +360,7 @@ List / add / remove dependencies (issues this one is blocked by)
## `hive-forge issue dependency list`
List dependencies (default when no action is given) — the issues/PRs this one is blocked by
List dependencies (default when you give no action) — the issues/PRs blocking this one
**Usage:** `hive-forge issue dependency list`
@ -368,7 +368,7 @@ List dependencies (default when no action is given) — the issues/PRs this one
## `hive-forge issue dependency add`
Add one or more issues/PRs this one is blocked by
Add one or more issues/PRs that block this one
**Usage:** `hive-forge issue dependency add [DEPS]...`
@ -398,13 +398,13 @@ List / add / remove emoji reactions on the issue, or on one of its comments with
###### **Subcommands:**
* `list` — List reactions (default when no action is given)
* `list` — List reactions (default when you give no action)
* `add` — Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket`
* `remove` — Remove your own reaction with this content
###### **Arguments:**
* `<NUMBER>` — Issue or PR number. Ignored (but still required) when `--list-allowed` is set
* `<NUMBER>` — Issue or PR number. Ignored (but still required) when you pass `--list-allowed`
###### **Options:**
@ -415,7 +415,7 @@ List / add / remove emoji reactions on the issue, or on one of its comments with
## `hive-forge issue reaction list`
List reactions (default when no action is given)
List reactions (default when you give no action)
**Usage:** `hive-forge issue reaction list`
@ -458,7 +458,7 @@ List timeline events
###### **Options:**
* `--limit <LIMIT>` — Return the first `N` events (oldest-first), or (with `--since`) the most this call returns — capped at [`crate::verbs::MAX_LIMIT`] in the latter case. An explicit opt-in: with neither this nor `--tail` given, the default is the newest 10 (see `--tail`). Mutually exclusive with `--tail`
* `--tail <TAIL>` — Return the last `N` events (chronological) — the most recent activity. This is the default (`N` = 10) when neither `--limit` nor `--tail` is given. Mutually exclusive with `--limit`/`--since`
* `--tail <TAIL>` — Return the last `N` events (chronological) — the most recent activity. Defaults to `N` = 10 when you pass neither `--limit` nor `--tail`. Mutually exclusive with `--limit`/`--since`
* `--since <SINCE>` — Only show events at or after this RFC3339 timestamp (same format this verb's own output prints) — pass back the last-seen row's `created_at` to fetch only what's new
@ -480,14 +480,14 @@ PR-scoped commands: `pr <show|status|create|merge|reviews|assign-reviewer|commit
* `assign-reviewer` — Request (or withdraw with `--remove`) a review from a user
* `diff` — Print the PR's unified diff
* `view` — Show title + body + comments
* `edit` — Edit the PR's title / body / state / milestone. Fields not passed are left unchanged
* `edit` — Edit the PR's title / body / state / milestone. Fields you don't pass keep their current value
* `comment` — Post a comment on the PR
* `comments` — List comments on the PR
* `close` — Close the PR
* `reopen` — Reopen a closed PR
* `labels` — List / add / remove labels
* `assign-committer` — Assign or unassign a user (the PR's assignee list)
* `dependency` — List / add / remove dependencies (issues/PRs this one is blocked by)
* `dependency` — List / add / remove dependencies (issues/PRs blocking this one)
* `reaction` — List / add / remove emoji reactions on the PR, or on one of its comments with `--comment <id>`
* `timeline` — List timeline events
@ -653,7 +653,7 @@ Show title + body + comments
## `hive-forge pr edit`
Edit the PR's title / body / state / milestone. Fields not passed are left unchanged
Edit the PR's title / body / state / milestone. Fields you don't pass keep their current value
**Usage:** `hive-forge pr edit [OPTIONS] <NUMBER>`
@ -705,7 +705,7 @@ List comments on the PR
###### **Options:**
* `--limit <LIMIT>` — Number of comments from the start of the thread (oldest-first), or (with `--since`) the most this call returns — capped at [`crate::verbs::MAX_LIMIT`] in the latter case. An explicit opt-in: with neither this nor `--tail` given, the default is the newest 10 (see `--tail`). Mutually exclusive with `--tail`
* `--tail <TAIL>` — Return the last `N` comments (chronological) — the most recent activity. This is the default (`N` = 10) when neither `--limit` nor `--tail` is given. Mutually exclusive with `--limit`/`--since`
* `--tail <TAIL>` — Return the last `N` comments (chronological) — the most recent activity. Defaults to `N` = 10 when you pass neither `--limit` nor `--tail`. Mutually exclusive with `--limit`/`--since`
* `--since <SINCE>` — Only show comments at or after this RFC3339 timestamp (same format this verb's own output prints). Mutually exclusive with `--tail`
* `--show-reactions` — Fetch + display each shown comment's reaction summary. Costs one extra request per comment shown — opt-in, not the default
@ -743,7 +743,7 @@ List / add / remove labels
###### **Subcommands:**
* `list` — List labels (default when no action is given)
* `list` — List labels (default when you give no action)
* `add` — Add labels by name
* `remove` — Remove labels by name
@ -755,7 +755,7 @@ List / add / remove labels
## `hive-forge pr labels list`
List labels (default when no action is given)
List labels (default when you give no action)
**Usage:** `hive-forge pr labels list`
@ -804,14 +804,14 @@ Assign or unassign a user (the PR's assignee list)
## `hive-forge pr dependency`
List / add / remove dependencies (issues/PRs this one is blocked by)
List / add / remove dependencies (issues/PRs blocking this one)
**Usage:** `hive-forge pr dependency <NUMBER> [COMMAND]`
###### **Subcommands:**
* `list` — List dependencies (default when no action is given) — the issues/PRs this one is blocked by
* `add` — Add one or more issues/PRs this one is blocked by
* `list` — List dependencies (default when you give no action) — the issues/PRs blocking this one
* `add` — Add one or more issues/PRs that block this one
* `remove` — Remove one or more dependency links
###### **Arguments:**
@ -822,7 +822,7 @@ List / add / remove dependencies (issues/PRs this one is blocked by)
## `hive-forge pr dependency list`
List dependencies (default when no action is given) — the issues/PRs this one is blocked by
List dependencies (default when you give no action) — the issues/PRs blocking this one
**Usage:** `hive-forge pr dependency list`
@ -830,7 +830,7 @@ List dependencies (default when no action is given) — the issues/PRs this one
## `hive-forge pr dependency add`
Add one or more issues/PRs this one is blocked by
Add one or more issues/PRs that block this one
**Usage:** `hive-forge pr dependency add [DEPS]...`
@ -860,13 +860,13 @@ List / add / remove emoji reactions on the PR, or on one of its comments with `-
###### **Subcommands:**
* `list` — List reactions (default when no action is given)
* `list` — List reactions (default when you give no action)
* `add` — Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket`
* `remove` — Remove your own reaction with this content
###### **Arguments:**
* `<NUMBER>` — Issue or PR number. Ignored (but still required) when `--list-allowed` is set
* `<NUMBER>` — Issue or PR number. Ignored (but still required) when you pass `--list-allowed`
###### **Options:**
@ -877,7 +877,7 @@ List / add / remove emoji reactions on the PR, or on one of its comments with `-
## `hive-forge pr reaction list`
List reactions (default when no action is given)
List reactions (default when you give no action)
**Usage:** `hive-forge pr reaction list`
@ -920,7 +920,7 @@ List timeline events
###### **Options:**
* `--limit <LIMIT>` — Return the first `N` events (oldest-first), or (with `--since`) the most this call returns — capped at [`crate::verbs::MAX_LIMIT`] in the latter case. An explicit opt-in: with neither this nor `--tail` given, the default is the newest 10 (see `--tail`). Mutually exclusive with `--tail`
* `--tail <TAIL>` — Return the last `N` events (chronological) — the most recent activity. This is the default (`N` = 10) when neither `--limit` nor `--tail` is given. Mutually exclusive with `--limit`/`--since`
* `--tail <TAIL>` — Return the last `N` events (chronological) — the most recent activity. Defaults to `N` = 10 when you pass neither `--limit` nor `--tail`. Mutually exclusive with `--limit`/`--since`
* `--since <SINCE>` — Only show events at or after this RFC3339 timestamp (same format this verb's own output prints) — pass back the last-seen row's `created_at` to fetch only what's new
@ -979,7 +979,7 @@ Create a forge repo under the current user (or `--org`). Prints the repo URL
###### **Arguments:**
* `<NAME>` — Repository name (required). Created under the authenticated user unless `--org` is given
* `<NAME>` — Repository name (required). Creates it under the authenticated user unless you pass `--org`
###### **Options:**
@ -987,7 +987,7 @@ Create a forge repo under the current user (or `--org`). Prints the repo URL
* `--private` — Create the repo as private (default: public)
* `--default-branch <DEFAULT_BRANCH>` — Default branch name (for example `main`). Only takes effect with `--auto-init`
* `--org <ORG>` — Create under this organisation instead of your own namespace
* `--auto-init` — Seed an initial commit (README) so the repo is non-empty and can be cloned immediately. Omit to create a bare repo you push into
* `--auto-init` — Seed an initial commit (README) so you can clone the repo immediately instead of getting an empty one. Omit to create a bare repo you push into
@ -1040,7 +1040,7 @@ Search the forge for repositories by keyword, topic, or description
* `-q`, `--query <QUERY>` — Keyword to search for (matches repo name by default; combine with `--include-desc` to also match description text)
* `--topic` — Restrict matches to repositories that have the keyword as a **topic** tag rather than in the name
* `--include-desc` — Extend the keyword search to repository descriptions (in addition to names, or topics when `--topic` is set)
* `--include-desc` — Extend the keyword search to repository descriptions (in addition to names, or topics when you pass `--topic`)
* `--limit <LIMIT>` — Maximum number of results to return (default: 30)
Default value: `30`
@ -1398,9 +1398,3 @@ List CI Actions runs, newest first (`--workflow`, `--branch`, `--limit`, `--page
<hr/>
<small><i>
This document was generated automatically by
<a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
</i></small>

12
docs/tools/hivectl-cli.md
View file

@ -247,7 +247,7 @@ Invite a matrix user to the hive Space, or a specific room with `--room`. Idempo
GitHub account provisioning.
Store an operator-supplied personal access token (PAT) for an agent so its `gh` and git can authenticate. No account is created — the PAT is for an existing GitHub account.
Store an operator-supplied personal access token (PAT) for an agent so its `gh` and git can authenticate. Creates no account — the PAT is for an existing GitHub account.
**Usage:** `hivectl github <COMMAND>`
@ -503,7 +503,7 @@ A fresh session by default, or resume a prior one. Requires root or `hive-admin`
###### **Options:**
* `--resume <SESSION>` — Resume a prior claude session by its session id, passed through as `claude --resume <value>` (claude's `--continue` takes no value — it resumes the cwd's latest session, which is the harness's, so choom never uses it; this flag matches the claude flag it maps to). Omit for a fresh blank session. A value is required when the flag is given
* `--resume <SESSION>` — Resume a prior claude session by its session id, passed through as `claude --resume <value>` (claude's `--continue` takes no value — it resumes the cwd's latest session, which is the harness's, so choom never uses it; this flag matches the claude flag it maps to). Omit for a fresh blank session. Requires a value
@ -641,7 +641,7 @@ Export a snapshot to a local file via `btrfs send` — the local-file half of th
Stream a snapshot to the swarm's snapshot store over the WireGuard mesh — the network half of the migration transport.
Nothing is staged locally: `btrfs send` writes straight into the connection, so a multi-gigabyte agent needs no scratch space on this host. The mesh is the authentication (cryptokey routing binds the sender's address to its key), so there is no credential to pass here.
Stages nothing locally: `btrfs send` writes straight into the connection, so a multi-gigabyte agent needs no scratch space on this host. The mesh is the authentication (cryptokey routing binds the sender's address to its key), so there is no credential to pass here.
No destination argument exists: a swarm has one store, read from `services.hyperhive.swarm.snapshotStore`.
@ -901,9 +901,3 @@ Supports bash, zsh, fish, elvish, and powershell. The NixOS module already insta
<hr/>
<small><i>
This document was generated automatically by
<a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
</i></small>

12
docs/tools/swarmctl-cli.md
View file

@ -52,7 +52,7 @@ Queue creation of a new agent on a hive in this swarm.
Asks the swarm-controller to insert its agent-creation job graph — SSO identity, forge user, config repo, and the deploy message that puts the agent on `--hive` — and prints the queued job's node id.
**This returns as soon as the work is queued.** It doesn't wait, and a finished graph would not mean the agent is up either: the last node publishes a deploy, after which the hive converges on its own clock. Watch the swarm UI's job view, or the hive itself, for the rest.
**This returns as soon as it queues the work.** It doesn't wait, and a finished graph would not mean the agent is up either: the last node publishes a deploy, after which the hive converges on its own clock. Watch the swarm UI's job view, or the hive itself, for the rest.
No approval gate guards this: running this binary already means being root on the controller's host.
@ -62,13 +62,13 @@ No approval gate guards this: running this binary already means being root on th
* `<NAME>` — Name for the new agent: 1–63 characters of `[a-z0-9-]`.
Becomes an SSO subject, a forge user and a repository name, so it's validated here before anything is queued.
Becomes an SSO subject, a forge user and a repository name, so it's validated here before queuing.
###### **Options:**
* `--hive <HIVE>` — Hive in this swarm to deploy the agent to.
Required, and deliberately not defaulted: it's an *address* — the hive a deploy message is sent to — and only the operator knows which one they mean. The controller checks it against the swarm's hive roster and names the known hives if it misses.
Required, and deliberately not defaulted: it's an *address* — the hive that gets the deploy message — and only the operator knows which one they mean. The controller checks it against the swarm's hive roster and names the known hives if it misses.
* `--controller-socket <PATH>` — swarm-controller's unix socket.
Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`.
@ -157,9 +157,3 @@ Dispatched before `PathArgs::resolve()` for the same reason as `markdown-docs`:
<hr/>
<small><i>
This document was generated automatically by
<a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
</i></small>