Skip to content

docs(cli): add the boot-interface command reference pages #3410

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chet wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(cli): add the boot-interface command reference pages #3410

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface-candidates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# `nico-admin-cli boot-interface candidates`

_[Hardware commands](../../hardware.md) › [boot-interface](./boot-interface.md) › **candidates**_

## NAME

nico-admin-cli-boot-interface-candidates - List boot-interface
candidates for a machine and the picks among them

## SYNOPSIS

**nico-admin-cli boot-interface candidates** \[**--extended**\]
\[**--sort-by**\] \[**-h**\|**--help**\] \<*MACHINE*\>
Comment on lines +12 to +13

@coderabbitai coderabbitai Bot Jul 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

file='docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface-candidates.md'

printf '\n== File (numbered excerpt) ==\n'
cat -n "$file" | sed -n '1,120p'

printf '\n== Related boot-interface docs (filenames) ==\n'
fd -a 'boot-interface*.md' docs/manuals/nico-admin-cli/commands -t f

printf '\n== Similar synopsis patterns in sibling docs ==\n'
for f in docs/manuals/nico-admin-cli/commands/boot-interface/*.md; do
  printf '\n-- %s --\n' "$f"
  sed -n '1,40p' "$f"
done

Repository: NVIDIA/infra-controller

Length of output: 7774

Include <SORT_BY> in the synopsis. The usage line currently shows [--sort-by], but the option is defined as --sort-by <SORT_BY> below. Regenerate the page so the synopsis matches the accepted invocation.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface-candidates.md`
around lines 12 - 13, Update the nico-admin-cli boot-interface candidates
synopsis to show the required <SORT_BY> argument alongside --sort-by, matching
the option definition below; regenerate the documentation page without changing
other command options.

Source: Path instructions


## DESCRIPTION

List every NIC that could be the boot interface for a machine -- the
managed \`machine_interfaces\` rows and the pre-first-lease predictions
-- and mark the picks among them: \`current\` (what resolution targets
now: the primary interface if one is set, else the lowest-MAC
non-underlay interface), \`default\` (what the automatic selection would
choose if no primary interface were set), and \`explored\` (the default
site-explorer recorded for the BMC endpoint of the machine). Underlay
rows are listed but marked ineligible. Every pick is computed
server-side by the same selection code the machine-controller acts on.
Read-only.

## OPTIONS

**--extended**
Extended result output.

This used by measured boot, where basic output contains just what you
probably care about, and "extended" output also dumps out all the
internal UUIDs that are used to associate instances.

**--sort-by** *\<SORT_BY\>* \[default: primary-id\]
Sort output by specified field


*Possible values:*

> - primary-id: Sort by the primary id
>
> - state: Sort by state

**-h**, **--help**
Print help (see a summary with -h)

\<*MACHINE*\>
The machine ID whose boot-interface candidates to list

## Examples

```sh
nico-admin-cli boot-interface candidates 12345678-1234-5678-90ab-cdef01234567
nico-admin-cli --format json boot-interface candidates 12345678-1234-5678-90ab-cdef01234567
```

---

**See also:** [Hardware commands](../../hardware.md) · [CLI reference index](../../README.md)
67 changes: 67 additions & 0 deletions docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface-set.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
# `nico-admin-cli boot-interface set`

_[Hardware commands](../../hardware.md) › [boot-interface](./boot-interface.md) › **set**_

## NAME

nico-admin-cli-boot-interface-set - Set the boot interface for a machine
(promotes it to the primary interface)

## SYNOPSIS

**nico-admin-cli boot-interface set** \[**--reboot**\]
\[**--extended**\] \[**--sort-by**\] \[**-h**\|**--help**\]
\<*MACHINE*\> \<*INTERFACE*\>

## DESCRIPTION

Make an interface the boot interface for a machine by promoting it to
the primary interface -- the designation every boot flow keys on. This
is the same operation as \`managed-host set-primary-interface\`: the BMC
boot order is updated first, then the primary flag moves in the
database. The interface can be named by machine-interface UUID or by MAC
address; a MAC must match exactly one managed interface row on the
machine.

## OPTIONS

**--reboot**
Reboot the host after the update

**--extended**
Extended result output.

This used by measured boot, where basic output contains just what you
probably care about, and "extended" output also dumps out all the
internal UUIDs that are used to associate instances.

**--sort-by** *\<SORT_BY\>* \[default: primary-id\]
Sort output by specified field


*Possible values:*

> - primary-id: Sort by the primary id
>
> - state: Sort by state

**-h**, **--help**
Print help (see a summary with -h)

\<*MACHINE*\>
The machine whose boot interface to set

\<*INTERFACE*\>
The interface to boot from -- a machine-interface UUID or a MAC address

## Examples

```sh
nico-admin-cli boot-interface set 12345678-1234-5678-90ab-cdef01234567 00:11:22:33:44:55
nico-admin-cli boot-interface set 12345678-1234-5678-90ab-cdef01234567 abcdef01-2345-6789-abcd-ef0123456789
nico-admin-cli boot-interface set 12345678-1234-5678-90ab-cdef01234567 00:11:22:33:44:55 --reboot
```

---

**See also:** [Hardware commands](../../hardware.md) · [CLI reference index](../../README.md)
60 changes: 60 additions & 0 deletions docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface-show.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# `nico-admin-cli boot-interface show`

_[Hardware commands](../../hardware.md) › [boot-interface](./boot-interface.md) › **show**_

## NAME

nico-admin-cli-boot-interface-show - Show boot interfaces for a machine
from every store (troubleshooting)

## SYNOPSIS

**nico-admin-cli boot-interface show** \[**--extended**\]
\[**--sort-by**\] \[**-h**\|**--help**\] \<*MACHINE*\>

## DESCRIPTION

Gather the boot-interface view for one machine from all four stores and
print them together: the managed \`machine_interfaces\` rows
(authoritative for a managed machine), \`predicted_machine_interfaces\`
(pre-first-lease candidates), the \`explored_endpoints\` default (for
endpoints without a machine), and the retained post-deletion pairs
(including stale records). Also reports the effective boot interface the
system would select and flags when the stores disagree. Read-only.

## OPTIONS

**--extended**
Extended result output.

This used by measured boot, where basic output contains just what you
probably care about, and "extended" output also dumps out all the
internal UUIDs that are used to associate instances.

**--sort-by** *\<SORT_BY\>* \[default: primary-id\]
Sort output by specified field


*Possible values:*

> - primary-id: Sort by the primary id
>
> - state: Sort by state

**-h**, **--help**
Print help (see a summary with -h)

\<*MACHINE*\>
The machine ID whose boot interfaces to gather

## Examples

```sh
nico-admin-cli boot-interface show 12345678-1234-5678-90ab-cdef01234567
nico-admin-cli --format json boot-interface show 12345678-1234-5678-90ab-cdef01234567
nico-admin-cli --format yaml boot-interface show 12345678-1234-5678-90ab-cdef01234567
```

---

**See also:** [Hardware commands](../../hardware.md) · [CLI reference index](../../README.md)
50 changes: 50 additions & 0 deletions docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# `nico-admin-cli boot-interface`

_[Hardware commands](../../hardware.md) › **boot-interface**_

## NAME

nico-admin-cli-boot-interface - Machine boot-interface management

## SYNOPSIS

**nico-admin-cli boot-interface** \[**--extended**\] \[**--sort-by**\]
\[**-h**\|**--help**\] \<*subcommands*\>
Comment on lines +11 to +12

@coderabbitai coderabbitai Bot Jul 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect the target markdown and nearby generated command docs.
printf '\n## Target file\n'
cat -n docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface.md | sed -n '1,120p'

printf '\n## Related command docs\n'
for f in \
  docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface.md \
  docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface-extended.md \
  docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface-sort-by.md \
  docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface-help.md
do
  [ -f "$f" ] || continue
  printf '\n### %s\n' "$f"
  grep -nE 'sort-by|extended|Synopsis|Usage|`--sort-by`|<SORT_BY>' "$f" || true
done

printf '\n## Search for help source definitions\n'
rg -n --hidden --glob '!target' --glob '!**/node_modules/**' 'boot-interface|sort-by|SORT_BY|extended' \
  docs crates .github book . 2>/dev/null | sed -n '1,220p'

Repository: NVIDIA/infra-controller

Length of output: 30997

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Focus on the exact file and nearby command docs.
cat -n docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface.md | sed -n '1,120p'

printf '\n---\n'
find docs/manuals/nico-admin-cli/commands/boot-interface -maxdepth 1 -type f | sort | xargs -r -I{} sh -c 'printf "\n### %s\n" "{}"; grep -nE "sort-by|extended|<SORT_BY>|Synopsis|Usage|--help" "{}" || true'

Repository: NVIDIA/infra-controller

Length of output: 3275

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Show the exact markdown section around the synopsis and option table.
sed -n '1,80p' docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface.md

Repository: NVIDIA/infra-controller

Length of output: 1495

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect the target markdown and discover related generated pages in the same directory.
find docs/manuals/nico-admin-cli/commands/boot-interface -maxdepth 1 -type f | sort

printf '\n--- target ---\n'
sed -n '1,120p' docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface.md

Repository: NVIDIA/infra-controller

Length of output: 1811

Show --sort-by <SORT_BY> in the synopsis. docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface.md:11-12 omits the required value even though the option accepts one. The same synopsis pattern appears on the other boot-interface pages, so fix the generator/help source and regenerate the set.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface.md` around
lines 11 - 12, Update the boot-interface synopsis generator or help-source
definition so the --sort-by option is rendered with its required <SORT_BY>
value, then regenerate all boot-interface command pages to apply the corrected
synopsis consistently.

Source: Path instructions


## DESCRIPTION

Machine boot-interface management

## OPTIONS

**--extended**
Extended result output.

This used by measured boot, where basic output contains just what you
probably care about, and "extended" output also dumps out all the
internal UUIDs that are used to associate instances.
Comment on lines +23 to +25

@coderabbitai coderabbitai Bot Jul 12, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Fix the generated grammar before publishing.

Change “This used by measured boot” to “This is used by measured boot.” Since the text is repeated across the generated pages, fix the CLI help source/template and rerun generate-cli-docs rather than patching only one output file.

As per path instructions, Markdown documentation must be reviewed for spelling and grammar.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/manuals/nico-admin-cli/commands/boot-interface/boot-interface.md` around
lines 23 - 25, Correct the repeated measured-boot description in the CLI help
source or documentation template from “This used by measured boot” to “This is
used by measured boot,” then rerun generate-cli-docs so all generated pages
receive the grammar fix.

Source: Path instructions


**--sort-by** *\<SORT_BY\>* \[default: primary-id\]
Sort output by specified field


*Possible values:*

> - primary-id: Sort by the primary id
>
> - state: Sort by state

**-h**, **--help**
Print help (see a summary with -h)

## Subcommands

| Subcommand | Description |
|---|---|
| [`show`](./boot-interface-show.md) | Show boot interfaces for a machine from every store (troubleshooting) |
| [`candidates`](./boot-interface-candidates.md) | List boot-interface candidates for a machine and the picks among them |
| [`set`](./boot-interface-set.md) | Set the boot interface for a machine (promotes it to the primary interface) |

---

**See also:** [Hardware commands](../../hardware.md) · [CLI reference index](../../README.md)
1 change: 1 addition & 0 deletions docs/manuals/nico-admin-cli/hardware.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ For global flags and setup, see [the overview](./README.md) and [`setup.md`](./s
|---|---|
| [`attestation`](./commands/attestation/attestation.md) | MeasuredBoot or SPDM attestations. |
| [`bmc-machine`](./commands/bmc-machine/bmc-machine.md) | BMC Machine related handling. |
| [`boot-interface`](./commands/boot-interface/boot-interface.md) | Machine boot-interface management. |
| [`boot-override`](./commands/boot-override/boot-override.md) | Machine boot override. |
| [`browse`](./commands/browse/browse.md) | Browse subsystem resource trees via the API server. |
| [`component-manager`](./commands/component-manager/component-manager.md) | Component manager actions. |
Expand Down
Loading