Skip to content

docs(cli): say what each command does, not how it works - #62

Merged
naliyi merged 4 commits into
mainfrom
docs-command-descriptions
Sep 23, 2026
Merged

naliyi merged 4 commits into
mainfrom
docs-command-descriptions

Conversation

@naliyi

@naliyi naliyi commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

Follow-on to #61. The descriptions still explained how things work; this makes them say what the command does.

What came out

Mechanism, across the board: the NIP-98 transport the admin subcommands use, "deduplicated by hash", ping's Limit-1 subscription, the config search order, "merged across all targets", "each server downloads it directly; no bytes pass through ncli", "wait for each relay's OK", and the last of the TUI/daemon jargon.

Eight descriptions disappeared entirely once the mechanism was gone and only a restatement of the headline remained: blossom mirror, blossom report, blossom servers, relay, apply, miner, prefs, prefs relays.

ncli relay with no config — the case that started this — is now:

Error: no relay config found; pass --config <file> or --context <name>

Run and operate a Nostr relay

Usage:
  ncli relay [flags]
  ncli relay [command]

Examples:
  ncli relay --config relay.yaml
  ncli relay --context myrelay

The create-if-missing behaviour that appeared twice now lives only on the --context flag.

Headlines

before after
Reindex a running relay without restarting it Rebuild a relay's indexes while it runs
Show live relay metrics and worker status Show live relay metrics
Reattach the TUI to a running bunker daemon Reattach to a running bunker
Run ncli as a NIP-46 remote signer Sign other apps' events as a NIP-46 signer
Set (or clear, with "") a trusted app's display name Rename a trusted app
Revoke one remembered permission, leaving the rest Revoke one of an app's permissions

Coverage

Checked rather than eyeballed. Walked all 71 user-reachable commands out of the built binary (plus root and the hidden daemon = 73, matching the source count), then:

  • scanned every description against a mechanism-wording pattern — one hit remained (bunker), now zero;
  • scanned for descriptions restating their own headline — fourteen hits, all resolved by dropping or trimming.

What stays is only what the rest of the help doesn't already show: what the output contains, what the exit code means, and which flags conflict.

Verification

gofmt, go build ./..., go vet ./..., go test -short ./... clean. No test asserts on Short/Long text.

The create-if-missing behaviour of -c/--context is already spelled out
on the flag itself, so the description repeated it. Drops to the two
facts that aren't visible elsewhere: what the command runs, and where
the config is read from.
Descriptions were explaining mechanism: which transport the admin
subcommands use, that blobs are deduplicated by hash, that ping sends a
Limit-1 subscription, the order config files are searched in. None of
that helps anyone run the command.

Stripped throughout. Four descriptions went away entirely once the
mechanism was removed and only a restatement of the headline was left
(blossom mirror, blossom report, blossom servers, relay). Headlines lost
their internals too -- "daemon", "TUI", "worker status", "without
restarting it".

What stays is what a caller can't see elsewhere: what the output
contains, what the exit code means, and which flags conflict.
A sweep across all 71 commands found the last of the mechanism wording
(bunker still said "TUI" twice) and fourteen descriptions that mostly
repeated the line above them.

Four are gone entirely -- apply, miner, prefs, prefs relays -- and the
rest keep only what the headline doesn't already say: that roles can't
be deleted, that members add skips the invite flow, which flags
conflict.
@naliyi
naliyi merged commit d4dcf92 into main Sep 23, 2026
7 of 8 checks passed
@naliyi
naliyi deleted the docs-command-descriptions branch September 23, 2026 16:43
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