docs(minimal): hide --network and --ingress from the CLI surface - #999
Merged
Conversation
`own-ip` cannot work on an installed host: minimald resolves a switch binary that no install ships (#980), so the mode is reachable only from a dev checkout with an explicit override. Advertising the flag offers users a mode that fails for reasons they cannot see or fix. Hidden, not removed. Both flags still parse, still validate their values, and `host-net` remains the default, so nothing passing them today changes behaviour — this is only about what we put in front of someone reading `--help` or the reference. Drops the matching rows from docs/reference/cli-min.md for the same reason; a documented flag that cannot work is worse than an undocumented one that can. The doc comments record the unhide condition so this does not become permanent by forgetting: restore both when own-ip works from an install. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
📝 WalkthroughWalkthroughThe activation CLI now hides the ChangesCLI activation
Estimated code review effort: 1 (Trivial) | ~5 minutes Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
Comment |
twitchyliquid64
approved these changes
Jul 28, 2026
norrietaylor
added a commit
that referenced
this pull request
Jul 29, 2026
… unhide note Two corrections to the `min login` hide, no change in behaviour. `#[clap(hide = true)]` becomes `#[command(hide = true)]`. The three other hidden subcommands in this enum — `Proxy`, `Spin`, `CompleteSessionStr` — all use the `#[command(...)]` spelling. #999 used `#[clap(...)]`, but that was on struct fields, where the neighbouring attribute is `#[arg(...)]`; inside `Command` the matching form is `#[command(...)]`. The unhide instruction said "restore the section in docs/reference/cli-min.md". There is no such section to restore — it was dropped in bfaddc4 — so a future maintainer would go looking for something that does not exist. It now says to document the command there when unhiding. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Jul 29, 2026
norrietaylor
added a commit
that referenced
this pull request
Jul 29, 2026
* docs(minimal): hide `min login` from the CLI surface `min login` cannot work against an installed daemon. It issues an mTLS client certificate through minimald's `IssueClientCert` RPC, which exists only under minimald's off-by-default `networking-proxy` feature, and the release jobs build minimald with no `--features` at all. A shipped daemon answers that RPC with "minimald was built without the networking-proxy feature" and never binds the :7655 proxy listener, so the command is usable only from a dev checkout, whose guest initramfs the justfile does build with the feature. Hidden, not removed. The command still parses and still dispatches; `LoginArgs`, the dispatch arm, and `cmd_login` are untouched, so nothing running it today changes behaviour — this is only about what we put in front of someone reading `--help`. docs/reference/cli-min.md already carries no `login` section (dropped in bfaddc4), so unlike #999 there is no reference row to remove. The doc comment records the unhide condition so this does not become permanent by forgetting: unhide, and restore the reference section, once shipped minimald builds the proxy in. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(minimal): match the hide attribute to its neighbours and fix the unhide note Two corrections to the `min login` hide, no change in behaviour. `#[clap(hide = true)]` becomes `#[command(hide = true)]`. The three other hidden subcommands in this enum — `Proxy`, `Spin`, `CompleteSessionStr` — all use the `#[command(...)]` spelling. #999 used `#[clap(...)]`, but that was on struct fields, where the neighbouring attribute is `#[arg(...)]`; inside `Command` the matching form is `#[command(...)]`. The unhide instruction said "restore the section in docs/reference/cli-min.md". There is no such section to restore — it was dropped in bfaddc4 — so a future maintainer would go looking for something that does not exist. It now says to document the command there when unhiding. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(minimal): drop the hide rationale from the source comment Keeps the `#[command(hide = true)]` attribute and removes the eleven-line doc-comment paragraph that explained it, leaving `min login`'s pre-existing help text exactly as it was on main. The diff against main is now a single added line. The paragraph was reaching the wrong audience. `hide` only removes a subcommand from the parent listing, so `min login --help` still rendered the whole thing — maintainer-facing build-system reasoning, shown to the one user who managed to find the command. Recording it here and in the pull request keeps it with the change without putting it in front of that user. Why the command is hidden, verified against this tree: - Issuance rides minimald's `IssueClientCert` RPC, which is `#[cfg(feature = "networking-proxy")]` (crates/minimald/src/rpc.rs). - `networking-proxy` is off by default; crates/minimald/Cargo.toml declares no `default` feature set. - .github/workflows/release.yml builds `--package minimald` with no `--features` at all, for both linux-amd64 and linux-arm64, and build-release-initramfs repacks those same binaries by setting MINIMALD_BIN, which makes scripts/build-initramfs.sh ignore FEATURES. So the guest daemon in a shipped microVM lacks the feature too. A shipped daemon therefore answers the RPC with "minimald was built without the networking-proxy feature; client certificate issuance is unavailable" and never binds the :7655 proxy listener. The command only works from a dev checkout, where the justfile passes `features := "networking-proxy"` into the guest initramfs. Unhide once shipped minimald builds the proxy in, and document `login` in docs/reference/cli-min.md at that point — the reference carries no `login` section today, having dropped it in bfaddc4. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Split out of #988 — unrelated to that PR's release packaging, and small enough to review on its own.
Why
own-ipcannot work on an installed host.minimaldresolves a switch binary that no install ships (#980), so the mode is only reachable from a dev checkout with an explicit override. Advertising the flag offers users a mode that fails for reasons they can neither see nor fix.Hidden, not removed
Both flags still parse and still validate. Only
--helpand the reference change:host-netremains the default, so nothing that passes these flags today changes behaviour. Nothing inscripts/, the test harnesses, or the workflows passes them.The matching rows come out of
docs/reference/cli-min.mdfor the same reason — a documented flag that cannot work is worse than an undocumented one that can.Reversing this
The doc comments carry the unhide condition, so it does not become permanent by forgetting: unhide both, and restore the reference rows, once own-ip works from an install. #988 is what makes that true on Linux by shipping the switch binary.
Worth being explicit that this is a judgement call about surface, not capability — happy to drop it if you would rather document the dev-checkout path instead.
Verification
just cigreen. Help output and both parse cases checked against a builtmin(shown above).cargo test -p minimalis not runnable on macOS — its dev-dependencies pullminimald→procfs— so the CLI-behaviour evidence here is the built binary rather than a unit test.🤖 Generated with Claude Code
Note
Hide
--networkand--ingressoptions from theactivatecommand CLI helpApplies
#[clap(hide = true)]to thenetworkandingressfields inActivateArgsso they no longer appear in generated help output. Both options remain functional at runtime with the same defaults and parsing. The corresponding rows are also removed from cli-min.md.Macroscope summarized ce58cab.
Summary by CodeRabbit
Documentation
--syncoption, including its available modes and default behavior.--networkand--ingressfrom the documentedmin activateoptions.User Experience
--networkand--ingressoptions frommin --helpwhile preserving their availability for supported setups.