Skip to content

docs: backfill CLI reference for reports and diagnostics commands - #210

Open
gregggreg wants to merge 1 commit into
marcus:mainfrom
gregggreg:docs/backfill-missing-docs
Open

docs: backfill CLI reference for reports and diagnostics commands#210
gregggreg wants to merge 1 commit into
marcus:mainfrom
gregggreg:docs/backfill-missing-docs

Conversation

@gregggreg

@gregggreg gregggreg commented Aug 9, 2026

Copy link
Copy Markdown

Gap

website/docs/cli-reference.md documented run, preview, task, and budget, but the reports and diagnostics commands had no coverage at all — no flag tables, and report and busfactor were missing from the command table entirely.

Scope

One file, one commit, branched from origin/main.

  • Added a Reports and Diagnostics section documenting all 32 flags across status (2), logs (12), stats (2), report (9), busfactor (7), and doctor (0 — noted explicitly as taking no flags), each with names, shorthands, defaults, and accepted values.
  • Added nightshift report and nightshift busfactor rows to the Core Commands table.
  • Added --help/-h to the Global Flags table (cobra adds it to every command), and documented --version/-v separately as a root-only flag.

Verification

  • Every flag name, shorthand, default, and enum value was read directly from the Flags().* registrations in cmd/nightshift/commands/{status,logs,stats,report,busfactor,doctor}.go — nothing inferred.
  • --version/-v and --help/-h confirmed against a locally built binary. --version comes from Version: Version on rootCmd, not a persistent flag, so it is documented as root-only rather than global — nightshift status --version errors with unknown flag: --version.
  • The busfactor positional-vs---path precedence is documented from busfactor.go (the flag wins; the positional is used only when the flag is empty; current directory otherwise).
  • npm run build in website/ succeeds.

Identified but intentionally out of scope

  • The Global Flags table lists --provider and --timeout as global, but they are per-command: --provider is on budget, budget snapshot, and budget history; --timeout is on run and daemon start. Neither is registered on the root command. Correcting this is a behavior-claim fix rather than a backfill, so it is left for a separate PR.
  • config, init, install, uninstall, and completion are still absent from the Core Commands table.
  • daemon, install, and uninstall have no flag documentation.
  • preview, task, and budget still have example blocks without flag tables.

Nightshift-Task: docs-backfill
Nightshift-Ref: https://github.com/marcus/nightshift

@gregggreg
gregggreg force-pushed the docs/backfill-missing-docs branch from fb36ce7 to ffdeca0 Compare August 9, 2026 09:10
Document the flags for status, logs, stats, report, busfactor, and
doctor, none of which were covered in the CLI reference. Add the
missing `report` and `busfactor` rows to the command table, and
document the root `--version` and `--help` flags.

Nightshift-Task: docs-backfill
Nightshift-Ref: https://github.com/marcus/nightshift
@gregggreg
gregggreg force-pushed the docs/backfill-missing-docs branch from ffdeca0 to b40a220 Compare August 9, 2026 09:17
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.

1 participant