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 * `reopen` — Reopen a closed issue
* `labels` — List / add / remove labels * `labels` — List / add / remove labels
* `assign` — Assign or unassign a user * `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>` * `reaction` — List / add / remove emoji reactions on the issue, or on one of its comments with `--comment <id>`
* `timeline` — List timeline events * `timeline` — List timeline events
@ -173,7 +173,7 @@ Create an issue
* `--body <BODY>` — Inline body text * `--body <BODY>` — Inline body text
* `--body-file <BODY_FILE>` — Read body from a file. `-` means stdin * `--body-file <BODY_FILE>` — Read body from a file. `-` means stdin
* `--assignee <ASSIGNEE>` — Initial assignee login * `--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:** ###### **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` * `--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` * `--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 * `--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:** ###### **Subcommands:**
* `list` — List labels (default when no action is given) * `list` — List labels (default when you give no action)
* `add` — Add labels by name * `add` — Add labels by name
* `remove` — Remove labels by name * `remove` — Remove labels by name
@ -293,7 +293,7 @@ List / add / remove labels
## `hive-forge issue labels list` ## `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` **Usage:** `hive-forge issue labels list`
@ -342,14 +342,14 @@ Assign or unassign a user
## `hive-forge issue dependency` ## `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]` **Usage:** `hive-forge issue dependency <NUMBER> [COMMAND]`
###### **Subcommands:** ###### **Subcommands:**
* `list` — List dependencies (default when no action is given) — the 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 this one is blocked by * `add` — Add one or more issues/PRs that block this one
* `remove` — Remove one or more dependency links * `remove` — Remove one or more dependency links
###### **Arguments:** ###### **Arguments:**
@ -360,7 +360,7 @@ List / add / remove dependencies (issues this one is blocked by)
## `hive-forge issue dependency list` ## `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` **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` ## `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]...` **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:** ###### **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` * `add` — Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket`
* `remove` — Remove your own reaction with this content * `remove` — Remove your own reaction with this content
###### **Arguments:** ###### **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:** ###### **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` ## `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` **Usage:** `hive-forge issue reaction list`
@ -458,7 +458,7 @@ List timeline events
###### **Options:** ###### **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` * `--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 * `--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 * `assign-reviewer` — Request (or withdraw with `--remove`) a review from a user
* `diff` — Print the PR's unified diff * `diff` — Print the PR's unified diff
* `view` — Show title + body + comments * `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 * `comment` — Post a comment on the PR
* `comments` — List comments on the PR * `comments` — List comments on the PR
* `close` — Close the PR * `close` — Close the PR
* `reopen` — Reopen a closed PR * `reopen` — Reopen a closed PR
* `labels` — List / add / remove labels * `labels` — List / add / remove labels
* `assign-committer` — Assign or unassign a user (the PR's assignee list) * `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>` * `reaction` — List / add / remove emoji reactions on the PR, or on one of its comments with `--comment <id>`
* `timeline` — List timeline events * `timeline` — List timeline events
@ -653,7 +653,7 @@ Show title + body + comments
## `hive-forge pr edit` ## `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>` **Usage:** `hive-forge pr edit [OPTIONS] <NUMBER>`
@ -705,7 +705,7 @@ List comments on the PR
###### **Options:** ###### **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` * `--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` * `--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 * `--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:** ###### **Subcommands:**
* `list` — List labels (default when no action is given) * `list` — List labels (default when you give no action)
* `add` — Add labels by name * `add` — Add labels by name
* `remove` — Remove labels by name * `remove` — Remove labels by name
@ -755,7 +755,7 @@ List / add / remove labels
## `hive-forge pr labels list` ## `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` **Usage:** `hive-forge pr labels list`
@ -804,14 +804,14 @@ Assign or unassign a user (the PR's assignee list)
## `hive-forge pr dependency` ## `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]` **Usage:** `hive-forge pr dependency <NUMBER> [COMMAND]`
###### **Subcommands:** ###### **Subcommands:**
* `list` — List dependencies (default when no action is given) — the 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 this one is blocked by * `add` — Add one or more issues/PRs that block this one
* `remove` — Remove one or more dependency links * `remove` — Remove one or more dependency links
###### **Arguments:** ###### **Arguments:**
@ -822,7 +822,7 @@ List / add / remove dependencies (issues/PRs this one is blocked by)
## `hive-forge pr dependency list` ## `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` **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` ## `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]...` **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:** ###### **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` * `add` — Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket`
* `remove` — Remove your own reaction with this content * `remove` — Remove your own reaction with this content
###### **Arguments:** ###### **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:** ###### **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` ## `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` **Usage:** `hive-forge pr reaction list`
@ -920,7 +920,7 @@ List timeline events
###### **Options:** ###### **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` * `--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 * `--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:** ###### **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:** ###### **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) * `--private` — Create the repo as private (default: public)
* `--default-branch <DEFAULT_BRANCH>` — Default branch name (for example `main`). Only takes effect with `--auto-init` * `--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 * `--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) * `-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 * `--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) * `--limit <LIMIT>` — Maximum number of results to return (default: 30)
Default value: `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. 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>` **Usage:** `hivectl github <COMMAND>`
@ -503,7 +503,7 @@ A fresh session by default, or resume a prior one. Requires root or `hive-admin`
###### **Options:** ###### **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. 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`. 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. 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. 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-]`. * `<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:** ###### **Options:**
* `--hive <HIVE>` — Hive in this swarm to deploy the agent to. * `--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. * `--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`. 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>

9
hive-forge/src/main.rs
View file

@ -226,7 +226,14 @@ fn run() -> Result<()> {
// credentials — just a pure render of the clap tree the docs build // credentials — just a pure render of the clap tree the docs build
// pipes into `docs/tools/forge-cli.md`. // pipes into `docs/tools/forge-cli.md`.
if let Verb::MarkdownDocs = verb { if let Verb::MarkdownDocs = verb {
print!("{}", clap_markdown::help_markdown::<Cli>()); // `show_footer(false)`: the default footer's wording ("This
// document was generated automatically by...") is clap-markdown's
// own fixed text, not ours to reword into active voice, and the
// repo's docs are prose we write ourselves throughout — so we
// drop the footer rather than carry the one string in this tree
// we have no control over.
let options = clap_markdown::MarkdownOptions::new().show_footer(false);
print!("{}", clap_markdown::help_markdown_custom::<Cli>(&options));
return Ok(()); return Ok(());
} }
let client = client::Client::from_env(cli.repo, cli.json, cli.forge) let client = client::Client::from_env(cli.repo, cli.json, cli.forge)

4
hive-forge/src/verbs/comments.rs
View file

@ -54,8 +54,8 @@ pub struct Args {
#[arg(long, conflicts_with = "tail")] #[arg(long, conflicts_with = "tail")]
limit: Option<u64>, limit: Option<u64>,
/// Return the last `N` comments (chronological) — the most recent /// Return the last `N` comments (chronological) — the most recent
/// activity. This is the default (`N` = 10) when neither `--limit` /// activity. Defaults to `N` = 10 when you pass neither `--limit`
/// nor `--tail` is given. Mutually exclusive with `--limit`/`--since`. /// nor `--tail`. Mutually exclusive with `--limit`/`--since`.
#[arg(long, conflicts_with = "since")] #[arg(long, conflicts_with = "since")]
tail: Option<usize>, tail: Option<usize>,
/// Only show comments at or after this RFC3339 timestamp (same /// Only show comments at or after this RFC3339 timestamp (same

6
hive-forge/src/verbs/dependency.rs
View file

@ -30,10 +30,10 @@ pub struct Args {
#[derive(Subcommand)] #[derive(Subcommand)]
enum Action { enum Action {
/// List dependencies (default when no action is given) — the /// List dependencies (default when you give no action) — the
/// issues/PRs this one is blocked by. /// issues/PRs blocking this one.
List, List,
/// Add one or more issues/PRs this one is blocked by. /// Add one or more issues/PRs that block this one.
Add { Add {
/// Issue/PR numbers to add as dependencies. /// Issue/PR numbers to add as dependencies.
deps: Vec<u64>, deps: Vec<u64>,

2
hive-forge/src/verbs/issue_cmd.rs
View file

@ -40,7 +40,7 @@ enum Cmd {
Labels(verbs::labels::Args), Labels(verbs::labels::Args),
/// Assign or unassign a user. /// Assign or unassign a user.
Assign(verbs::assign::Args), Assign(verbs::assign::Args),
/// List / add / remove dependencies (issues this one is blocked by). /// List / add / remove dependencies (issues blocking this one).
Dependency(verbs::dependency::Args), Dependency(verbs::dependency::Args),
/// List / add / remove emoji reactions on the issue, or on one of its /// List / add / remove emoji reactions on the issue, or on one of its
/// comments with `--comment <id>`. /// comments with `--comment <id>`.

2
hive-forge/src/verbs/issue_create.rs
View file

@ -25,7 +25,7 @@ pub struct Args {
assignee: Option<String>, assignee: Option<String>,
/// Label name to attach, repeatable (for example `--label area/ops --label /// Label name to attach, repeatable (for example `--label area/ops --label
/// type/bug`). Same spelling `labels add` accepts. An unresolved name /// type/bug`). Same spelling `labels add` accepts. An unresolved name
/// errors out (before the issue is created) rather than silently /// errors out (before creating the issue) rather than silently
/// attaching fewer labels than asked for. /// attaching fewer labels than asked for.
#[arg(long = "label")] #[arg(long = "label")]
labels: Vec<String>, labels: Vec<String>,

4
hive-forge/src/verbs/issue_edit.rs
View file

@ -1,6 +1,6 @@
//! `issue edit <number> [--title <t>] [body sources] [--state s] //! `issue edit <number> [--title <t>] [body sources] [--state s]
//! [--milestone id] [repo]` — partial update of an issue. Fields not //! [--milestone id] [repo]` — partial update of an issue. Omitted
//! provided are left unchanged. Also backs `pr edit`: Forgejo serves //! fields keep their current value. Also backs `pr edit`: Forgejo serves
//! both kinds off the same `/issues/<n>` endpoint, so this is shared //! both kinds off the same `/issues/<n>` endpoint, so this is shared
//! as-is — `pr_cmd.rs` wires it in with a `Kind::Pr` check, the same //! as-is — `pr_cmd.rs` wires it in with a `Kind::Pr` check, the same
//! pattern `close`/`reopen`/`labels` already use. //! pattern `close`/`reopen`/`labels` already use.

2
hive-forge/src/verbs/labels.rs
View file

@ -19,7 +19,7 @@ pub struct Args {
#[derive(Subcommand)] #[derive(Subcommand)]
enum Action { enum Action {
/// List labels (default when no action is given). /// List labels (default when you give no action).
List, List,
/// Add labels by name. /// Add labels by name.
Add { Add {

6
hive-forge/src/verbs/pr_cmd.rs
View file

@ -39,8 +39,8 @@ enum Cmd {
Diff(verbs::diff::Args), Diff(verbs::diff::Args),
/// Show title + body + comments. /// Show title + body + comments.
View(verbs::view::Args), View(verbs::view::Args),
/// Edit the PR's title / body / state / milestone. Fields not passed /// Edit the PR's title / body / state / milestone. Fields you don't
/// are left unchanged. /// pass keep their current value.
Edit(verbs::issue_edit::Args), Edit(verbs::issue_edit::Args),
/// Post a comment on the PR. /// Post a comment on the PR.
Comment(verbs::comment::Args), Comment(verbs::comment::Args),
@ -55,7 +55,7 @@ enum Cmd {
/// Assign or unassign a user (the PR's assignee list). /// Assign or unassign a user (the PR's assignee list).
#[command(alias = "assign")] #[command(alias = "assign")]
AssignCommitter(verbs::assign::Args), AssignCommitter(verbs::assign::Args),
/// List / add / remove dependencies (issues/PRs this one is blocked by). /// List / add / remove dependencies (issues/PRs blocking this one).
Dependency(verbs::dependency::Args), Dependency(verbs::dependency::Args),
/// List / add / remove emoji reactions on the PR, or on one of its /// List / add / remove emoji reactions on the PR, or on one of its
/// comments with `--comment <id>`. /// comments with `--comment <id>`.

6
hive-forge/src/verbs/reaction.rs
View file

@ -29,8 +29,8 @@ use crate::verbs::{comment_reactions, issue_reactions, print_json};
#[derive(ClapArgs)] #[derive(ClapArgs)]
pub struct Args { pub struct Args {
/// Issue or PR number. Ignored (but still required) when /// Issue or PR number. Ignored (but still required) when you pass
/// `--list-allowed` is set. /// `--list-allowed`.
pub(crate) number: u64, pub(crate) number: u64,
/// Target a specific comment's reactions instead of the issue/PR /// Target a specific comment's reactions instead of the issue/PR
/// itself — the comment's own id (from `comments`/`comment-show`), /// itself — the comment's own id (from `comments`/`comment-show`),
@ -48,7 +48,7 @@ pub struct Args {
#[derive(Subcommand)] #[derive(Subcommand)]
enum Action { enum Action {
/// List reactions (default when no action is given). /// List reactions (default when you give no action).
List, List,
/// Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket`. /// Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket`.
Add { content: String }, Add { content: String },

9
hive-forge/src/verbs/repo_create.rs
View file

@ -18,8 +18,8 @@ use crate::verbs::print_json;
#[derive(ClapArgs)] #[derive(ClapArgs)]
pub struct Args { pub struct Args {
/// Repository name (required). Created under the authenticated user /// Repository name (required). Creates it under the authenticated
/// unless `--org` is given. /// user unless you pass `--org`.
name: String, name: String,
/// Repository description. /// Repository description.
#[arg(long)] #[arg(long)]
@ -33,8 +33,9 @@ pub struct Args {
/// Create under this organisation instead of your own namespace. /// Create under this organisation instead of your own namespace.
#[arg(long)] #[arg(long)]
org: Option<String>, org: Option<String>,
/// Seed an initial commit (README) so the repo is non-empty and can /// Seed an initial commit (README) so you can clone the repo
/// be cloned immediately. Omit to create a bare repo you push into. /// immediately instead of getting an empty one. Omit to create a
/// bare repo you push into.
#[arg(long = "auto-init")] #[arg(long = "auto-init")]
auto_init: bool, auto_init: bool,
} }

2
hive-forge/src/verbs/repo_search.rs
View file

@ -26,7 +26,7 @@ pub struct Args {
#[arg(long)] #[arg(long)]
topic: bool, topic: bool,
/// Extend the keyword search to repository descriptions (in addition to /// Extend the keyword search to repository descriptions (in addition to
/// names, or topics when `--topic` is set). /// names, or topics when you pass `--topic`).
#[arg(long = "include-desc")] #[arg(long = "include-desc")]
include_desc: bool, include_desc: bool,
/// Maximum number of results to return (default: 30). /// Maximum number of results to return (default: 30).

4
hive-forge/src/verbs/timeline.rs
View file

@ -46,8 +46,8 @@ pub struct Args {
#[arg(long, conflicts_with = "tail")] #[arg(long, conflicts_with = "tail")]
limit: Option<u64>, limit: Option<u64>,
/// Return the last `N` events (chronological) — the most recent /// Return the last `N` events (chronological) — the most recent
/// activity. This is the default (`N` = 10) when neither `--limit` /// activity. Defaults to `N` = 10 when you pass neither `--limit`
/// nor `--tail` is given. Mutually exclusive with `--limit`/`--since`. /// nor `--tail`. Mutually exclusive with `--limit`/`--since`.
#[arg(long, conflicts_with = "since")] #[arg(long, conflicts_with = "since")]
tail: Option<usize>, tail: Option<usize>,
/// Only show events at or after this RFC3339 timestamp (same format /// Only show events at or after this RFC3339 timestamp (same format

8
hivectl/src/cli.rs
View file

@ -49,8 +49,8 @@ pub enum Cmd {
/// GitHub account provisioning. /// GitHub account provisioning.
/// ///
/// Store an operator-supplied personal access token (PAT) for an agent /// Store an operator-supplied personal access token (PAT) for an agent
/// so its `gh` and git can authenticate. No account is created — the /// so its `gh` and git can authenticate. Creates no account — the PAT
/// PAT is for an existing GitHub account. /// is for an existing GitHub account.
Github { Github {
#[command(subcommand)] #[command(subcommand)]
cmd: GithubCmd, cmd: GithubCmd,
@ -551,7 +551,7 @@ pub enum AgentCmd {
/// takes no value — it resumes the cwd's latest session, which /// takes no value — it resumes the cwd's latest session, which
/// is the harness's, so choom never uses it; this flag matches /// is the harness's, so choom never uses it; this flag matches
/// the claude flag it maps to). Omit for a fresh blank session. /// the claude flag it maps to). Omit for a fresh blank session.
/// A value is required when the flag is given. /// Requires a value.
#[arg(long = "resume", value_name = "SESSION")] #[arg(long = "resume", value_name = "SESSION")]
resume_session: Option<String>, resume_session: Option<String>,
}, },
@ -662,7 +662,7 @@ pub enum SnapshotCmd {
/// Stream a snapshot to the swarm's snapshot store over the /// Stream a snapshot to the swarm's snapshot store over the
/// WireGuard mesh — the network half of the migration transport. /// WireGuard mesh — the network half of the migration transport.
/// ///
/// Nothing is staged locally: `btrfs send` writes straight into the /// Stages nothing locally: `btrfs send` writes straight into the
/// connection, so a multi-gigabyte agent needs no scratch space on /// connection, so a multi-gigabyte agent needs no scratch space on
/// this host. The mesh is the authentication (cryptokey routing /// this host. The mesh is the authentication (cryptokey routing
/// binds the sender's address to its key), so there is no credential /// binds the sender's address to its key), so there is no credential

6
hivectl/src/main.rs
View file

@ -127,7 +127,11 @@ async fn main() -> Result<()> {
Cmd::Start { scope, no_wait } => start(&socket, scope.to_scope(), no_wait).await, Cmd::Start { scope, no_wait } => start(&socket, scope.to_scope(), no_wait).await,
Cmd::Restart { scope, graceful } => restart(&socket, scope.to_scope(), graceful).await, Cmd::Restart { scope, graceful } => restart(&socket, scope.to_scope(), graceful).await,
Cmd::MarkdownDocs => { Cmd::MarkdownDocs => {
print!("{}", clap_markdown::help_markdown::<Cli>()); // `show_footer(false)`: drop clap-markdown's own fixed
// "This document was generated automatically by..." footer —
// it's the one string in this doc that isn't ours to reword.
let options = clap_markdown::MarkdownOptions::new().show_footer(false);
print!("{}", clap_markdown::help_markdown_custom::<Cli>(&options));
Ok(()) Ok(())
} }
Cmd::Open { target } => open_url(&socket, target).await, Cmd::Open { target } => open_url(&socket, target).await,

12
swarmctl/src/main.rs
View file

@ -159,7 +159,7 @@ enum AgentVerb {
/// SSO identity, forge user, config repo, and the deploy message that /// SSO identity, forge user, config repo, and the deploy message that
/// puts the agent on `--hive` — and prints the queued job's node id. /// 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, /// **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 /// 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 /// 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 /// own clock. Watch the swarm UI's job view, or the hive itself, for
@ -175,12 +175,12 @@ struct AgentCreateArgs {
/// Name for the new agent: 1–63 characters of `[a-z0-9-]`. /// Name for the new agent: 1–63 characters of `[a-z0-9-]`.
/// ///
/// Becomes an SSO subject, a forge user and a repository name, so /// Becomes an SSO subject, a forge user and a repository name, so
/// it's validated here before anything is queued. /// it's validated here before queuing.
name: String, name: String,
/// Hive in this swarm to deploy the agent to. /// Hive in this swarm to deploy the agent to.
/// ///
/// Required, and deliberately not defaulted: it's an *address* — the /// Required, and deliberately not defaulted: it's an *address* — the
/// hive a deploy message is sent to — and only the operator knows /// hive that gets the deploy message — and only the operator knows
/// which one they mean. The controller checks it against the swarm's /// which one they mean. The controller checks it against the swarm's
/// hive roster and names the known hives if it misses. /// hive roster and names the known hives if it misses.
#[arg(long, value_name = "HIVE")] #[arg(long, value_name = "HIVE")]
@ -275,7 +275,11 @@ fn main() -> Result<()> {
command: UserVerb::List, command: UserVerb::List,
} => user_list(&paths.resolve()?), } => user_list(&paths.resolve()?),
Verb::MarkdownDocs => { Verb::MarkdownDocs => {
print!("{}", clap_markdown::help_markdown::<Cli>()); // `show_footer(false)`: drop clap-markdown's own fixed
// "This document was generated automatically by..." footer —
// it's the one string in this doc that isn't ours to reword.
let options = clap_markdown::MarkdownOptions::new().show_footer(false);
print!("{}", clap_markdown::help_markdown_custom::<Cli>(&options));
Ok(()) Ok(())
} }
Verb::Completions { shell } => { Verb::Completions { shell } => {