rewrite generated CLI docs' passive voice to active
hive-forge and hivectl doc-comment strings for pr-create --label, diff --full, list --label, ci-runs --branch, and several hivectl subcommand options read as if things happened to themselves. Name the actor (hivectl, hive-forge, or the CLI) instead, and regenerate the three docs/tools/*-cli.md files from the rebuilt binaries. swarmctl-cli.md needs no source change: its only passive hit is clap-markdown's own generated boilerplate, out of scope here.
This commit is contained in:
iris
mara
parent
97e2a993e3
commit
7396903994
7 changed files with 39 additions and 39 deletions
|
|
@ -540,7 +540,7 @@ Create a pull request
|
|||
* `--remote <REMOTE>` — Remote to push to (default: `forge`, or `origin` in `--agit` mode)
|
||||
* `--agit` — Open the PR via Forgejo's `AGit` flow instead of pushing a branch — works for read-only collaborators. Run from inside a cloned repo
|
||||
* `--topic <TOPIC>` — `AGit` topic — groups repeated pushes into one PR (re-run with the same topic to update it). Defaults to the branch name. Only meaningful with `--agit`
|
||||
* `--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 rather than silently attaching fewer labels than asked for. In `--agit` mode this is applied as a follow-up call once the PR number is known (the `AGit` push itself has no label field), so it's silently skipped (not a label-resolution error) if the PR URL couldn't be parsed back out of the push output — same fallback as the deferred multi-line body
|
||||
* `--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 rather than silently attaching fewer labels than asked for. In `--agit` mode `pr-create` applies this as a follow-up call once it learns the PR number (the `AGit` push itself has no label field), so it silently skips them (not a label-resolution error) if it couldn't parse the PR URL back out of the push output — same fallback as the deferred multi-line body
|
||||
|
||||
|
||||
|
||||
|
|
@ -632,7 +632,7 @@ Print the PR's unified diff
|
|||
|
||||
###### **Options:**
|
||||
|
||||
* `--full` — Print the unfiltered diff. By default, autogenerated-file hunks (`flake.lock`, `Cargo.lock`, …) are collapsed to a placeholder so human-authored changes stay readable
|
||||
* `--full` — Print the unfiltered diff. By default, hive-forge collapses autogenerated-file hunks (`flake.lock`, `Cargo.lock`, …) to a placeholder so human-authored changes stay readable
|
||||
|
||||
|
||||
|
||||
|
|
@ -1185,7 +1185,7 @@ List issues / PRs with filters (`--kind`, `--state`, `--assignee`, `--author`, `
|
|||
* `--assignee <ASSIGNEE>` — Filter to items assigned to this user (single login)
|
||||
* `--author <AUTHOR>` — Filter to items authored by this user (single login)
|
||||
* `--mention <MENTION>` — Filter to items mentioning this user
|
||||
* `--label <LABELS>` — Filter to items carrying any of these label names. Repeatable. Validated client-side: a name the forge can't resolve is dropped from the filter rather than rejected, which returns MORE results than asked for, not fewer
|
||||
* `--label <LABELS>` — Filter to items carrying any of these label names. Repeatable. Validated client-side: the CLI drops a name the forge can't resolve from the filter rather than rejecting it, which returns MORE results than asked for, not fewer
|
||||
* `--milestone <MILESTONES>` — Filter to items in any of these milestones, by title or id. Repeatable. Validated client-side against the repo's milestones (closed ones included), since the forge would silently discard a name it can't resolve and return the UNFILTERED list
|
||||
* `--search <SEARCH>` — Full-text search over title AND body, server-side. Composes with every filter above — this is the duplicate-hunting path that grepping `list` output can't cover, since grep only ever sees the titles
|
||||
* `--limit <LIMIT>` — Page size — items per page (default: 30). The forge clamps this to its own `api.MAX_RESPONSE_ITEMS` (50 by default), so a large `--limit` silently returns a smaller page; the trailer reports the real total rather than trusting this number. Must be >= 1
|
||||
|
|
@ -1388,7 +1388,7 @@ List CI Actions runs, newest first (`--workflow`, `--branch`, `--limit`, `--page
|
|||
###### **Options:**
|
||||
|
||||
* `--workflow <WORKFLOW>` — Only runs of this workflow file (for example `ci.yml`)
|
||||
* `--branch <BRANCH>` — Only runs on this ref. A branch name (`main`, `damocles/foo`) or a PR (`#N`) is qualified for you; a `refs/…` value is used as given. An all-digit value is read as a PR number — to filter a branch literally named that, pass `refs/heads/<name>`
|
||||
* `--branch <BRANCH>` — Only runs on this ref. hive-forge qualifies a branch name (`main`, `damocles/foo`) or a PR (`#N`) for you, uses a `refs/…` value as given, and reads an all-digit value as a PR number — to filter a branch literally named that, pass `refs/heads/<name>`
|
||||
* `--limit <LIMIT>` — How many runs to print (default 20)
|
||||
|
||||
Default value: `20`
|
||||
|
|
|
|||
|
|
@ -113,7 +113,7 @@ Manual entry point to the same idempotent provisioning c0re runs at boot — for
|
|||
|
||||
Create or refresh the Forgejo account + token for `<name>`.
|
||||
|
||||
For an existing agent, persists the token to its state dir; for a human/other account, prints the token to stdout. Set a password to enable forge web-UI login (a random throwaway is used otherwise).
|
||||
For an existing agent, persists the token to its state dir; for a human/other account, prints the token to stdout. Set a password to enable forge web-UI login (otherwise it uses a random throwaway).
|
||||
|
||||
**Usage:** `hivectl forge create-user [OPTIONS] <NAME>`
|
||||
|
||||
|
|
@ -142,7 +142,7 @@ Always prints the diff first. `--from forge` resets the local checkout to forge
|
|||
|
||||
###### **Options:**
|
||||
|
||||
* `--from <FROM>` — Which side to reconcile from. Omit to be prompted after the diff
|
||||
* `--from <FROM>` — Which side to reconcile from. Omit it and hivectl prompts you after the diff
|
||||
|
||||
Possible values:
|
||||
- `forge`:
|
||||
|
|
@ -176,7 +176,7 @@ Manual entry point to the same idempotent provisioning c0re runs at boot — for
|
|||
|
||||
Create or refresh the matrix account + access token for `<name>`.
|
||||
|
||||
For an existing agent, persists the token to its state dir; for a human/other account, prints the access token to stdout. Set a password to enable matrix web-client login (a random throwaway is used otherwise).
|
||||
For an existing agent, persists the token to its state dir; for a human/other account, prints the access token to stdout. Set a password to enable matrix web-client login (otherwise it uses a random throwaway).
|
||||
|
||||
**Usage:** `hivectl matrix create-user [OPTIONS] <NAME>`
|
||||
|
||||
|
|
@ -372,7 +372,7 @@ Stop and start this agent container without rebuilding config
|
|||
|
||||
###### **Options:**
|
||||
|
||||
* `--no-wait` — Return immediately after the restart DAG is queued
|
||||
* `--no-wait` — Return immediately after hivectl queues the restart DAG
|
||||
|
||||
|
||||
|
||||
|
|
@ -386,7 +386,7 @@ The harness stops driving turns but keeps serving its web UI and MCP daemons, so
|
|||
|
||||
###### **Options:**
|
||||
|
||||
* `--no-wait` — Return immediately after the pause DAG is queued instead of waiting for the harness to acknowledge it
|
||||
* `--no-wait` — Return immediately after hivectl queues the pause DAG instead of waiting for the harness to acknowledge it
|
||||
|
||||
|
||||
|
||||
|
|
@ -406,7 +406,7 @@ Start this EXISTING agent container. Fails immediately if `name` has no config/t
|
|||
|
||||
###### **Options:**
|
||||
|
||||
* `--paused` — Start (or leave) the agent paused: if it's currently down, the pause marker is written before the container boots, so it comes up paused instead of driving turns immediately. If it's already running, this pauses it in place and doesn't attempt a (re)start
|
||||
* `--paused` — Start (or leave) the agent paused: if it's currently down, hivectl writes the pause marker before the container boots, so it comes up paused instead of driving turns immediately. If it's already running, this pauses it in place and doesn't attempt a (re)start
|
||||
|
||||
|
||||
|
||||
|
|
@ -814,8 +814,8 @@ Bare `hivectl stop` stops everything; scope flags narrow it to specific sub-agen
|
|||
* `--forge` — The forge container (`hive-forge`)
|
||||
* `--gateway` — The gateway (`hive-gateway`) — nginx on the host, not a container
|
||||
* `--matrix` — The matrix container (`hive-matrix`)
|
||||
* `--graceful` — Gracefully quiesce each agent before stopping, instead of a hard stop. Each agent gets a graceful-stop DAG on the job queue: the harness is signalled, runs one stop-checkpoint turn to flush durable `/state`, drains, then the container is stopped (bounded by a 3-min timeout that falls back to a hard stop). All drains overlap. Applies to agents only
|
||||
* `--no-wait` — Return immediately after the stop DAGs are queued instead of waiting for them with live per-node progress
|
||||
* `--graceful` — Gracefully quiesce each agent before stopping, instead of a hard stop. Each agent gets a graceful-stop DAG on the job queue: it signals the harness, which runs one stop-checkpoint turn to flush durable `/state` and drains, then the DAG stops the container (bounded by a 3-min timeout that falls back to a hard stop). All drains overlap. Applies to agents only
|
||||
* `--no-wait` — Return immediately after hivectl queues the stop DAGs instead of waiting for them with live per-node progress
|
||||
|
||||
|
||||
|
||||
|
|
@ -835,7 +835,7 @@ Bare `hivectl start` restores the agents stopped by the last broad-scope `stop`
|
|||
* `--forge` — The forge container (`hive-forge`)
|
||||
* `--gateway` — The gateway (`hive-gateway`) — nginx on the host, not a container
|
||||
* `--matrix` — The matrix container (`hive-matrix`)
|
||||
* `--no-wait` — Return immediately after the start DAGs are queued instead of waiting for them with live per-node progress
|
||||
* `--no-wait` — Return immediately after hivectl queues the start DAGs instead of waiting for them with live per-node progress
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -21,9 +21,9 @@ pub struct Args {
|
|||
/// Only runs of this workflow file (for example `ci.yml`).
|
||||
#[arg(long)]
|
||||
workflow: Option<String>,
|
||||
/// Only runs on this ref. A branch name (`main`, `damocles/foo`) or a
|
||||
/// PR (`#N`) is qualified for you; a `refs/…` value is used as
|
||||
/// given. An all-digit value is read as a PR number — to filter a
|
||||
/// Only runs on this ref. hive-forge qualifies a branch name (`main`,
|
||||
/// `damocles/foo`) or a PR (`#N`) for you, uses a `refs/…` value as
|
||||
/// given, and reads an all-digit value as a PR number — to filter a
|
||||
/// branch literally named that, pass `refs/heads/<name>`.
|
||||
#[arg(long)]
|
||||
branch: Option<String>,
|
||||
|
|
|
|||
|
|
@ -23,9 +23,9 @@ use crate::client::{Client, index};
|
|||
pub struct Args {
|
||||
/// PR number.
|
||||
number: u64,
|
||||
/// Print the unfiltered diff. By default, autogenerated-file hunks
|
||||
/// (`flake.lock`, `Cargo.lock`, …) are collapsed to a placeholder so
|
||||
/// human-authored changes stay readable.
|
||||
/// Print the unfiltered diff. By default, hive-forge collapses
|
||||
/// autogenerated-file hunks (`flake.lock`, `Cargo.lock`, …) to a
|
||||
/// placeholder so human-authored changes stay readable.
|
||||
#[arg(long)]
|
||||
full: bool,
|
||||
}
|
||||
|
|
|
|||
|
|
@ -97,8 +97,8 @@ pub struct Args {
|
|||
#[arg(long)]
|
||||
mention: Option<String>,
|
||||
/// Filter to items carrying any of these label names. Repeatable.
|
||||
/// Validated client-side: a name the forge can't resolve is dropped
|
||||
/// from the filter rather than rejected, which returns MORE results
|
||||
/// Validated client-side: the CLI drops a name the forge can't resolve
|
||||
/// from the filter rather than rejecting it, which returns MORE results
|
||||
/// than asked for, not fewer.
|
||||
#[arg(long = "label")]
|
||||
labels: Vec<String>,
|
||||
|
|
|
|||
|
|
@ -71,11 +71,11 @@ pub struct Args {
|
|||
/// Label name to attach, repeatable (for example `--label area/ops --label
|
||||
/// type/bug`). Same spelling `labels add` accepts — an unresolved name
|
||||
/// errors out rather than silently attaching fewer labels than asked
|
||||
/// for. In `--agit` mode this is applied as a follow-up call once the
|
||||
/// PR number is known (the `AGit` push itself has no label field), so
|
||||
/// it's silently skipped (not a label-resolution error) if the PR URL
|
||||
/// couldn't be parsed back out of the push output — same fallback as
|
||||
/// the deferred multi-line body.
|
||||
/// for. In `--agit` mode `pr-create` applies this as a follow-up call
|
||||
/// once it learns the PR number (the `AGit` push itself has no label
|
||||
/// field), so it silently skips them (not a label-resolution error) if
|
||||
/// it couldn't parse the PR URL back out of the push output — same
|
||||
/// fallback as the deferred multi-line body.
|
||||
#[arg(long = "label")]
|
||||
labels: Vec<String>,
|
||||
}
|
||||
|
|
|
|||
|
|
@ -130,13 +130,13 @@ pub enum Cmd {
|
|||
scope: ScopeArgs,
|
||||
/// Gracefully quiesce each agent before stopping, instead of a
|
||||
/// hard stop. Each agent gets a graceful-stop DAG on the job
|
||||
/// queue: the harness is signalled, runs one stop-checkpoint
|
||||
/// turn to flush durable `/state`, drains, then the container
|
||||
/// is stopped (bounded by a 3-min timeout that falls back to a
|
||||
/// queue: it signals the harness, which runs one stop-checkpoint
|
||||
/// turn to flush durable `/state` and drains, then the DAG stops
|
||||
/// the container (bounded by a 3-min timeout that falls back to a
|
||||
/// hard stop). All drains overlap. Applies to agents only.
|
||||
#[arg(long)]
|
||||
graceful: bool,
|
||||
/// Return immediately after the stop DAGs are queued instead of
|
||||
/// Return immediately after hivectl queues the stop DAGs instead of
|
||||
/// waiting for them with live per-node progress.
|
||||
#[arg(long)]
|
||||
no_wait: bool,
|
||||
|
|
@ -149,7 +149,7 @@ pub enum Cmd {
|
|||
Start {
|
||||
#[command(flatten)]
|
||||
scope: ScopeArgs,
|
||||
/// Return immediately after the start DAGs are queued instead
|
||||
/// Return immediately after hivectl queues the start DAGs instead
|
||||
/// of waiting for them with live per-node progress.
|
||||
#[arg(long)]
|
||||
no_wait: bool,
|
||||
|
|
@ -252,7 +252,7 @@ pub enum ForgeCmd {
|
|||
///
|
||||
/// For an existing agent, persists the token to its state dir; for a
|
||||
/// human/other account, prints the token to stdout. Set a password to
|
||||
/// enable forge web-UI login (a random throwaway is used otherwise).
|
||||
/// enable forge web-UI login (otherwise it uses a random throwaway).
|
||||
CreateUser {
|
||||
/// Forgejo username. For agents: the container/agent name
|
||||
/// (`<n>` in `h-<n>`; manager uses the literal `manager`).
|
||||
|
|
@ -281,7 +281,7 @@ pub enum ForgeCmd {
|
|||
ReconcileConfig {
|
||||
/// Agent whose config branches to reconcile.
|
||||
agent: String,
|
||||
/// Which side to reconcile from. Omit to be prompted after the diff.
|
||||
/// Which side to reconcile from. Omit it and hivectl prompts you after the diff.
|
||||
#[arg(long, value_enum)]
|
||||
from: Option<ReconcileFrom>,
|
||||
/// Include the full diff (not just `--stat`) in the report.
|
||||
|
|
@ -315,8 +315,8 @@ pub enum MatrixCmd {
|
|||
///
|
||||
/// For an existing agent, persists the token to its state dir; for a
|
||||
/// human/other account, prints the access token to stdout. Set a
|
||||
/// password to enable matrix web-client login (a random throwaway is
|
||||
/// used otherwise).
|
||||
/// password to enable matrix web-client login (otherwise it uses a
|
||||
/// random throwaway).
|
||||
CreateUser {
|
||||
/// Matrix localpart. For agents: the container/agent name.
|
||||
/// For humans: any matrix localpart — `mara`, `damocles`, etc.
|
||||
|
|
@ -454,7 +454,7 @@ pub(crate) use hive_host_sock::HOST_SOCKET as DEFAULT_HOST_SOCKET;
|
|||
pub enum AgentCmd {
|
||||
/// Stop and start this agent container without rebuilding config.
|
||||
Restart {
|
||||
/// Return immediately after the restart DAG is queued.
|
||||
/// Return immediately after hivectl queues the restart DAG.
|
||||
#[arg(long)]
|
||||
no_wait: bool,
|
||||
},
|
||||
|
|
@ -466,7 +466,7 @@ pub enum AgentCmd {
|
|||
/// backlog drains on `resume`. Sticky: it survives a restart, and
|
||||
/// pausing a stopped agent makes it come up paused.
|
||||
Pause {
|
||||
/// Return immediately after the pause DAG is queued instead of
|
||||
/// Return immediately after hivectl queues the pause DAG instead of
|
||||
/// waiting for the harness to acknowledge it.
|
||||
#[arg(long)]
|
||||
no_wait: bool,
|
||||
|
|
@ -477,8 +477,8 @@ pub enum AgentCmd {
|
|||
/// has no config/topology entry at all — it never attempts
|
||||
/// first-time creation. Use `create` for that.
|
||||
Start {
|
||||
/// Start (or leave) the agent paused: if it's currently down, the
|
||||
/// pause marker is written before the container boots, so it comes
|
||||
/// Start (or leave) the agent paused: if it's currently down, hivectl
|
||||
/// writes the pause marker before the container boots, so it comes
|
||||
/// up paused instead of driving turns immediately. If it's already
|
||||
/// running, this pauses it in place and doesn't attempt a
|
||||
/// (re)start.
|
||||
|
|
|
|||
Loading…
Reference in a new issue