Skip to content

Docs: one command line reference for the Darling service (#6413) - #6699

Merged
erikdarlingdata merged 4 commits into
devfrom
fix/6413-darling-cli-reference
Oct 24, 2026
Merged

erikdarlingdata merged 4 commits into
devfrom
fix/6413-darling-cli-reference

Conversation

@erikdarlingdata

@erikdarlingdata erikdarlingdata commented Oct 24, 2026 •

Copy link
Copy Markdown
Owner

Claude posting for Erik Darling.

Fixes #6413.

Why

The service exe has about 35 verbs. Each was explained only where its feature is explained, and the exit codes sat in long paragraphs in the Quick Start. There was no one list with the purpose, elevation, service state and exit codes of every verb.

What changes

  • New docs/darling/cli.md: one table row per verb (verb, what it does, needs elevation, service running, exit codes, link), a legend for the columns, one exit code section in one format (a table per verb family), and a short section for each verb that needs more than a row (arguments, example command lines).
  • Darling/README.md: the four exit-code paragraphs (--check-settings, --enable-collector/--disable-collector, the "every other verb" paragraph, --diagnostics-bundle) are now one line each that links to the new page. The links go to the page's #exit-codes section, because the paragraphs they replace were about exit codes and a table row has no anchor.
  • docs/darling/README.md: the index lists the page.
  • Two tests pinned the wording of the removed README paragraphs: DarlingCollectorToggleExitCodeTests.TheExitCodes_AreTheDocumentedNumbers (kept the number pins and the other README assertions) and DropXeSessionsVerbTests (dropped the "every other verb that opens the store" assertion). The rule behind them was spelling, so those assertions were deleted, as the lane rules say. Nothing else changed in the tests.

Where each fact comes from (all in Darling/PerformanceMonitor.Darling.Service/)

  • Verb list and aliases: DarlingCliCommands.cs IsKnownVerb (line 379) and the Is...Verb methods (lines 69-370). --help text: UsageText() (line 465). -? and /? are help (line 372). -v is version (line 364). Unknown option exits 1: Program.cs line 40.
  • Windows-only verbs: the OperatingSystem.IsWindows() guards in Program.cs (--encrypt-password line 54, --print-viewer-connection 121, --configure-network 193, --configure-firewall 211, --harden-files 229, --export-viewer-config 166, enable/disable mcp/web 257-300, print tokens 136-155). --add-server, --drop-xe-sessions, the three rollup verbs and the collector verbs have no guard (Program.cs comments at lines 306, 424, 440).
  • Elevation: code checks in PrintEndpointToken (line 1553, both token verbs), ConfigureFirewallAsync (line 5467), HardenTlsKeyFilesOnly (line 4899), and IsElevated() for the firewall step of the enable/disable verbs (line 4211) and the service control in --configure-network (line 3389). --harden-files and --diagnostics-bundle say "run elevated" in UsageText(). No other verb checks.
  • Exit codes: DiagnosticsBundleExitCode (line 951), CheckSettingsExitCode (1168), CollectorToggleExitCode (7865, also used by the alert-source verbs at 7184-7472, --reset-password-key at 300-340, and DarlingCliCommands.ExportInvestigations.cs lines 225-302 with the cancel code 130 at line 216), DropXeSessionsExitCode (8649), HardenTlsKeyFilesOnly (lines 4900-4945, 2 only when it could not run). The return 0/1 sites of every other verb (lines 535-6520 and GrantScript.cs 167-228).
  • Service running: the store is the managed Postgres that the service owns (DarlingCliCommands.cs line 4368: "the store is unreadable because the service is stopped"). So the store verbs are "either (1)" with the footnote. --enable-collector is run in-process, not queued, for that reason (line 7897).
  • Bare config path: Program.cs dispatch for each verb (args[1]); --backfill-rollups and --collapse-legacy-slices take any non---dry-run argument as the path (lines 449-490); ParseRecompressArgs (line 6124).

Code and docs disagree

  • The README says --diagnostics-bundle must run elevated. The code has no check. The page marks it "yes on the store host" because the README and UsageText() both say so and a managed store's credential file is not readable to other accounts, but it is not enforced.
  • The README said --backfill-rollups "runs while the service is up". The code does not require it, so the page marks it "either (1)".

Considered, not added

Test plan

  • Link check: a script resolved every relative link in docs/darling/cli.md and every anchor in Darling/README.md that the new page targets (all resolve).
  • Plain-English checker on docs/darling/cli.md: kept 1 long sentence (a list of causes in a table cell), the "could not" modals (real inability), and the word "print" (the verb's action).
  • Built Darling.Tests (0 errors) and ran DarlingCollectorToggleExitCodeTests and DropXeSessionsVerbTests: Total: 139, Failed: 0.
  • Not run: the full suite and the pre-push gate (laptop rule; CI decides).

CHANGELOG

Added a command line reference for the Darling service (docs/darling/cli.md). It lists every verb with what it does, whether it needs elevation, whether the service must be running, and its exit codes. The Quick Start now links to it instead of repeating the exit codes.

Seat corrections

Edits to docs/darling/cli.md, from Darling/PerformanceMonitor.Darling.Service/DarlingCliCommands.cs unless noted. The README text they restore is on origin/dev in Darling/README.md: the paragraphs on --check-settings, the collector verbs and "every other verb that opens the store".

  • Three-number table, row 2: now says the store cannot be reached, refuses the login (a wrong password is the store's answer, so 2), or refuses the change, and that a failed read-back after the write counts too (CollectorToggleExitCode.StoreUnavailable, :7860-7875; the catches around the connection and the write at :331-334, :7131-7135 and :7971-7975 file every store exception, login refusal included, under it). For --drop-xe-sessions, 2 is only the monitored server (DropXeSessionsExitCode.TargetUnavailable, :8649-8661, catch at :8925-8929), so the row says the store is not part of that number.
  • Three-number table, row 1: now names a connection string that cannot be used and a managed store credential that cannot be read (TryCreateCollectorStoreDataSource, :7991-8045, used by the collector verbs :7943, --reset-password-key :307-314, the alert source verbs :7107-7110 and --export-investigations DarlingCliCommands.ExportInvestigations.cs:150-152). --drop-xe-sessions uses 1 for an invalid config or a store setting that cannot be used (:8863-8879).
  • New list under that table, other cases the code files under 1: a managed credential that was never stored (the verbs that share TryCreateCollectorStoreDataSource; not --drop-xe-sessions, which does not call it); a store not yet upgraded (RunTimeTableMissingMessage for --set-collector-run-at, :8641-8644; NoTables for the alert source verbs, :7193-7195 and :7443-7448); an invalid, taken or unknown alert source name (:7190-7207); an output file that cannot be written or exists without --force (DarlingCliCommands.ExportInvestigations.cs:156-212, :289-292). --export-investigations returns 2 when the store cannot be read (:266, :299-302).
  • Checked and unchanged: the two-number list (no return other than 0 or 1 in the validate, add-server, rollup, enable and disable, viewer connection, export viewer config, configure-network and configure-firewall bodies); --check-settings (CheckSettingsExitCode, :1168-1174); --diagnostics-bundle (DiagnosticsBundleExitCode, :951-969); the --harden-files paragraph (:4880-4890, returns at :4900-4945 and :5193-5226).
  • Defects noticed: the earlier note about a broken Darling/README.md anchor #run-on-linux-docker-compose-or-systemd-1804 was wrong. An explicit <a id> with that name sits above the Linux heading (Darling/README.md:182). Removed from the Test plan.
  • Plain English: the checker reports 7 hits, all on text this change did not write (the long sentence at the top of the section, and "could not" in table rows that were already there).

Adds docs/darling/cli.md with one row per verb, the exit codes in one format, and a section for each verb that needs more than a row. The Quick Start exit code paragraphs in Darling/README.md now link to it. Two tests that pinned the removed paragraphs' wording lose those assertions.
@erikdarlingdata
erikdarlingdata marked this pull request as ready for review October 24, 2026 06:38

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Verdict: LGTM

Claims

  • VERIFIED — "New docs/darling/cli.md: one table row per verb ... a legend for the columns, one exit code section ... a short section for each verb that needs more than a row" — the file is added exactly this way (docs/darling/cli.md, new file in the diff).
  • VERIFIED — "Darling/README.md: the four exit-code paragraphs ... are now one line each that link to the new page" — confirmed in the diff (three link lines replacing the --check-settings, collector-verb, "every other verb", and --diagnostics-bundle paragraphs).
  • VERIFIED — "docs/darling/README.md: the index lists the page" — item 5 added in the diff.
  • VERIFIED — "Two tests pinned the wording ... assertions were deleted" — DarlingCollectorToggleExitCodeTests.cs and DropXeSessionsVerbTests.cs diffs drop exactly the assertions that quoted the now-removed README prose, and no stale copy of that prose remains anywhere in the tree (grepped for the removed strings).
  • VERIFIED — "The README says --diagnostics-bundle must run elevated. The code has no check." — DiagnosticsBundleAsync (DarlingCliCommands.cs:977) has no IsElevated() call; every IsElevated() call site (lines 1494, 1523, 3389, 4211, 4891, 5467) is elsewhere.
  • VERIFIED — "The README said --backfill-rollups 'runs while the service is up'. The code does not require it" — BackfillRollupsAsync (DarlingCliCommands.cs:9059) opens its own store connection and has no service-running gate.
  • VERIFIED — line citations for CollectorToggleExitCode (7865), DiagnosticsBundleExitCode (951), CheckSettingsExitCode (1168), DropXeSessionsExitCode (8649) — all exact.
  • UNVERIFIED — "Built Darling.Tests (0 errors) and ran ... Total: 139, Failed: 0" — a live build/test run; not checkable from a read-only tree.
  • UNVERIFIED — "Link check: a script resolved every relative link ... (all resolve)" — a live script run against the rendered docs; not checkable from a read-only tree, though a manual spot-check of the #exit-codes anchor and the docs/darling/README.md index entry found them consistent.

Riskiest lines

  1. docs/darling/cli.md exit-code tables (the three-number and six-number tables under "Exit codes") — these replace prose that scripts and operators gate on; a wrong number here is a silent behavior-doc regression. Spot-checked against CollectorToggleExitCode, DropXeSessionsExitCode, DiagnosticsBundleExitCode, CheckSettingsExitCode and InvestigationExportCancelledExitCode in DarlingCliCommands.cs — all matched. UNCOVERED by any test (deliberately, per the PR body's "Considered, not added" section, which cites #5833's ban on source-text/census tests); no behaviour test fails if a number here drifts from the code.
  2. Darling/README.md's three new link lines (exit codes now live only in docs/darling/cli.md#exit-codes) — if the anchor or file ever moves, the README silently points nowhere useful. UNCOVERED (the removed assertions were exactly the kind of source-text pin #5833 forbids re-adding); the PR body's "Link check" claim (unverified here) is the closest thing to coverage.
  3. Darling/Darling.Tests/DarlingCollectorToggleExitCodeTests.cs's surviving assertions (the "wrong password exits 2" and "does not tell its own mistake from a store that is down" checks) — still pin exact README wording for the three exit-code numbers themselves (not the removed paragraphs), so a future drift in those numbers is still caught by TheExitCodes_AreTheDocumentedNumbers. Covered by that existing test.

Traps near this diff

  • Tests and censuses ruling (#5833): "never add one, and never answer a trap with a test that reads source text or asserts how code is spelled" — does not apply: this PR deletes stale source-text assertions in DarlingCollectorToggleExitCodeTests.cs and DropXeSessionsVerbTests.cs rather than adding new ones, and adds no new test for cli.md's content (the PR body's "Considered, not added" section explicitly declines a table-vs-code test for this reason).
  • Lite/Darling parity (CONTRIBUTING's two-store rule) — does not apply: docs/darling/cli.md documents Darling-only CLI verbs that have no Lite counterpart; this is additive documentation for an existing Darling-only surface, not a behavior change needing a Lite-side counterpart.

Divergence (blind read vs PR body)

None — the body's account matches the diff on every claim graded above, including the two "code and docs disagree" notes, which the body itself surfaces rather than glossing over.

Reviewer checklist

  • Run the link-checker script (or click through manually) to confirm every relative link and the #exit-codes anchor in docs/darling/cli.md and Darling/README.md resolve on the rendered GitHub page.
  • Run Darling.Tests (DarlingCollectorToggleExitCodeTests, DropXeSessionsVerbTests, and the full suite) to confirm the claimed 139/0 result.

@erikdarlingdata
erikdarlingdata enabled auto-merge (squash) October 24, 2026 06:51
@claude

claude Bot commented Oct 24, 2026

Copy link
Copy Markdown

Follow-up pass, range b476eb32..300af4e07.

This range is a single commit: 300af4e07 ("Merge remote-tracking branch 'origin/dev' into fix/6699-merge"). Its second parent is 324d5db9c (tip of dev at merge time); diffing the two parents against their merge-base (6ddaf2f5) confirms this branch's own unique commits are only b476eb32c and 69ab8805a (both already reviewed in the prior pass), and everything else the merge brings in — 324d5db9c, d1571187, a1d978d3, 947f2adb5, 79353d12, 3b8d13ed — is dev's own already-merged work (PR numbers #6698, #6669, #6680, #6673, #6615, #6663), not this PR's author's change. Per the follow-up instructions, that content is left alone.

The one place both sides touched the same lines is docs/darling/README.md's numbered index: this PR's side added a 5. entry for the new cli.md page, dev's side added a 5. entry for the new admin.md page. The merge resolved the collision by keeping dev's item as 5 and renumbering this PR's item to 6 — both links present, nothing duplicated or dropped (confirmed against the file as merged: admin.md at item 5, cli.md at item 6, both targets exist on disk). No conflict markers remain anywhere in the tree (git grep for <<<<<<</>>>>>>> is empty).

Darling/README.md was also touched on both sides, but at disjoint line ranges (PR side: the four exit-code paragraphs around line ~147-174; dev side: the admin.md callout near the top and the new MCP service-flag section near line ~1250), so git merged it without a real conflict — both sets of changes are present in the result.

No new public signature, SQL statement, or behavior was introduced by this range, so the CALLERS RULE and the traps file have nothing new to apply to beyond the doc-list merge above, which isn't a code or SQL shape any trap covers.

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Verdict: LGTM

Claims

No new claims: the PR body is unchanged from the prior review pass (head b476eb32), and this range's only commit is a merge of origin/dev into the branch, not a new author commit with new claims about the code. The prior review already graded every body claim; those grades stand and are not re-litigated here.

Riskiest lines

  1. docs/darling/README.md (the numbered index, item 5/6) — both sides of the merge added a 5. entry (this PR's cli.md, dev's admin.md); the resolution renumbers this PR's entry to 6 and keeps both links, verified against the merged file and confirming both admin.md and cli.md exist on disk — UNCOVERED (a doc-index link isn't something a behaviour test asserts; not needed here since the file was read directly).
    No other lines qualify: the merge introduced no other overlapping edits, no new public signature, SQL, or behavior change of its own — everything else in the range's diff is dev's own already-merged work (#6698, #6669, #6680, #6673, #6615, #6663), out of scope per the follow-up instructions.

Traps near this diff

  • None apply: the only new content this range's own commit contributes is a markdown list-item renumbering during merge conflict resolution, which doesn't match the shape of any SQL, collector, analysis, alerting, storage/MCP, test-census, CI, or repository-mechanics trap in .github/REVIEW-TRAPS.md.

Divergence (blind read vs PR body)

None — the PR body makes no claims about this range's commit (the merge), so there is nothing to diverge from.

Reviewer checklist

  • Confirm the auto-merge (squash) picks up the resolved docs/darling/README.md list correctly and renders with both admin.md (5) and cli.md (6) entries on GitHub.

@erikdarlingdata
erikdarlingdata merged commit f50b345 into dev Oct 24, 2026
22 checks passed
@erikdarlingdata
erikdarlingdata deleted the fix/6413-darling-cli-reference branch October 24, 2026 08:54
@github-actions github-actions Bot mentioned this pull request Oct 24, 2026
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