Skip to content

docs: add help text to CLI options #41

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
Nelson Spence (Fieldnote-Echo) wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add help text to CLI options #41

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
17 changes: 11 additions & 6 deletions src/navi_bootstrap/cli.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,9 @@ def cli() -> None:
"--spec",
Copy link
Contributor

@github-actions github-actions bot Mar 12, 2026

Choose a reason for hiding this comment

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

🔵 LOW: Consistent and Complete CLI Help Texts Added

Confidence: 95%

Help text has now been added to all key CLI options, improving usability and self-documentation for users. This change also helps ensure argument meaning is visible via --help, aligning with best practices for CLI tool UX.

Suggestion: No action required unless further detail is desired for edge case options. Consider reviewing all remaining options to ensure similar clarity.

— Observable code is debuggable code. Consistency helps everyone (even me).

required=True,
type=click.Path(exists=True, path_type=Path),
help="Path to the project spec YAML file",
)
Comment on lines 53 to 57
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

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

The new --spec help text says "YAML", but load_spec() loads JSON (see src/navi_bootstrap/spec.py), and init writes nboot-spec.json. This will mislead users; update the help string to reference a JSON spec file (or broaden it only if YAML is actually supported).

Copilot uses AI. Check for mistakes.
@click.option("--pack", type=str, default=None)
@click.option("--pack", type=str, default=None, help="Name of the template pack to validate")
def validate(spec: Path, pack: str | None) -> None:
"""Validate a spec (and optionally a pack manifest)."""
try:
Expand All @@ -80,14 +81,16 @@ def validate(spec: Path, pack: str | None) -> None:
"--spec",
required=True,
type=click.Path(exists=True, path_type=Path),
help="Path to the project spec YAML file",
)
Comment on lines 81 to 85
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

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

The new --spec help text says "YAML", but this command calls load_spec() which parses JSON specs. Update the help string to reference a JSON spec file to match actual behavior.

Copilot uses AI. Check for mistakes.
@click.option("--pack", required=True, type=str)
@click.option("--pack", required=True, type=str, help="Name of the template pack to render")
@click.option(
"--out",
type=click.Path(path_type=Path),
default=None,
help="Output directory (defaults to spec name)",
)
@click.option("--dry-run", is_flag=True, default=False)
@click.option("--dry-run", is_flag=True, default=False, help="Preview output without writing files")
@click.option("--skip-resolve", is_flag=True, default=False, help="Skip SHA resolution (offline)")
@click.option("--trust", is_flag=True, default=False, help="Execute hooks from manifest (unsafe)")
def render_cmd(
Expand Down Expand Up @@ -183,12 +186,13 @@ def render_cmd(
"--spec",
required=True,
type=click.Path(exists=True, path_type=Path),
help="Path to the project spec YAML file",
)
Comment on lines 186 to 190
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

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

The new --spec help text says "YAML", but load_spec() parses JSON specs. Please adjust the help text to say JSON (consistent with init producing nboot-spec.json).

Copilot uses AI. Check for mistakes.
@click.option("--pack", required=True, type=str)
@click.option("--pack", required=True, type=str, help="Name of the template pack to apply")
@click.option(
"--target", required=True, type=click.Path(exists=True, file_okay=False, path_type=Path)
)
@click.option("--dry-run", is_flag=True, default=False)
@click.option("--dry-run", is_flag=True, default=False, help="Preview output without writing files")
@click.option("--skip-resolve", is_flag=True, default=False, help="Skip SHA resolution (offline)")
@click.option(
"--trust", is_flag=True, default=False, help="Execute hooks/validations from manifest (unsafe)"
Expand Down Expand Up @@ -291,8 +295,9 @@ def apply(
"--spec",
required=True,
type=click.Path(exists=True, path_type=Path),
help="Path to the project spec YAML file",
Copy link

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

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

The new --spec help text refers to a YAML spec file, but this command uses load_spec() which loads JSON. Update the help string to reference JSON (or otherwise align it with supported formats).

Suggested change
help="Path to the project spec YAML file",
help="Path to the project spec JSON file",

Copilot uses AI. Check for mistakes.
)
@click.option("--pack", required=True, type=str)
@click.option("--pack", required=True, type=str, help="Name of the template pack to diff")
@click.option(
"--target", required=True, type=click.Path(exists=True, file_okay=False, path_type=Path)
)
Expand Down
Loading