Skip to content

docs(minimal): hide --network and --ingress from the CLI surface - #999

Merged
norrietaylor merged 1 commit into
mainfrom
docs/hide-network-options
Jul 28, 2026
Merged

docs(minimal): hide --network and --ingress from the CLI surface#999
norrietaylor merged 1 commit into
mainfrom
docs/hide-network-options

Conversation

@norrietaylor

@norrietaylor norrietaylor commented Jul 28, 2026

Copy link
Copy Markdown
Member

Split out of #988 — unrelated to that PR's release packaging, and small enough to review on its own.

Why

own-ip cannot work on an installed host. minimald resolves 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 --help and the reference change:

$ min activate --help
      --sync <SYNC>
      --loadout <NAME>
      --no-loadouts
      ...                      # no --network, no --ingress

$ min activate --network own-ip --ingress 18080:80 …
                               # still accepted

$ min activate --network bogus
error: invalid value 'bogus' for '--network <NETWORK>'
  [possible values: no-net, host-net, own-ip]

host-net remains the default, so nothing that passes these flags today changes behaviour. Nothing in scripts/, the test harnesses, or the workflows passes them.

The matching rows come out of docs/reference/cli-min.md for 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 ci green. Help output and both parse cases checked against a built min (shown above). cargo test -p minimal is not runnable on macOS — its dev-dependencies pull minimaldprocfs — so the CLI-behaviour evidence here is the built binary rather than a unit test.

🤖 Generated with Claude Code

Note

Hide --network and --ingress options from the activate command CLI help

Applies #[clap(hide = true)] to the network and ingress fields in ActivateArgs so 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

    • Added documentation for the --sync option, including its available modes and default behavior.
    • Removed --network and --ingress from the documented min activate options.
  • User Experience

    • Hid the --network and --ingress options from min --help while preserving their availability for supported setups.

`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>
@coderabbitai

coderabbitai Bot commented Jul 28, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

The activation CLI now hides the --network and --ingress options from help output while retaining them, and the reference documentation adds --sync while removing those two flags.

Changes

CLI activation

Layer / File(s) Summary
Activation help and reference updates
crates/minimal/src/lib.rs, docs/reference/cli-min.md
The --network and --ingress flags are hidden from generated help, their limitations are documented, and the --sync option is added to the reference while those flags are removed.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested reviewers: twitchyliquid64

Poem

A bunny hops through help so bright,
Hiding network flags from sight.
Sync now joins the option row,
While ingress rests below.
Documentation follows light—
Two ears up for CLI night!

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title is concise, conventional, and accurately summarizes the main change to hide two CLI flags.
Description check ✅ Passed The description covers the change, rationale, verification, and rollout notes, though it doesn't follow the template headings exactly.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch

Comment @coderabbitai help to get the list of available commands.

@norrietaylor
norrietaylor merged commit 666c383 into main Jul 28, 2026
29 checks passed
@norrietaylor
norrietaylor deleted the docs/hide-network-options branch July 28, 2026 23:10
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>
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants