Skip to content

docs(cli): make command descriptions state what the command does - #61

Merged
naliyi merged 2 commits into
mainfrom
worktree-docker-style-descriptions
Sep 23, 2026
Merged

naliyi merged 2 commits into
mainfrom
worktree-docker-style-descriptions

Conversation

@naliyi

@naliyi naliyi commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

The help text had drifted into explaining itself rather than describing the command. profile was the clearest case — it recited which kinds it queries, then argued why it doesn't behave like find. That's the reasoning behind the command, not a description of it.

Rewritten flatter throughout, closer to how docker's CLI reads: say what the command does, state the rules a caller can't guess, drop the rationale.

Before

Looks up one identity's published records in a single query -- profile
metadata (kind:0), contact list (kind:3), relay list (kind:10002), and
Blossom server list (kind:10063) -- and prints them as one card.

Unlike "find", this aggregates across every target instead of stopping at
the first one with a match, since a relay list often lives on a different
relay than the profile.

After

Display the profile metadata, following count, relay list, Blossom
servers and lightning address published by an identity. Records are
merged across all targets.

The same pass across all 37 Long blocks and every Short:

  • Rationale, justification and "unlike X" comparisons removed.
  • Constraints stated flatly — "--targets cannot be combined with --relays or the inline filter flags" rather than "pick one, not both".
  • Short lines lose parentheticals and (s) plurals: "Upload one or more files to your Blossom server(s)" → "Upload files to your Blossom servers"; "List recently resolved requests (approved/rejected/expired)" → "List recently resolved signing requests".

The error that prompted this

ncli relay with no config printed three alternatives crammed into one line, and nothing else:

Error: no relay config found -- pass --config, run "ncli relay context use <name>", or add ncli.yaml/relay.yaml here

Now:

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

Run the Nostr relay server. The subcommands operate a relay that is
already running, over NIP-98 authenticated HTTP.

The config is read from --config, the current relay context, or an
ncli.yaml or relay.yaml in the working directory, in that order.
-c/--context runs against a named context, creating a minimal one backed
by a fresh identity if that name isn't saved yet.

Usage:
  ncli relay [flags]
...
Examples:
  ncli relay --config relay.yaml
  ncli relay --context myrelay

The error is short, the help carries the how, and the config search order moved into the description where it belongs. The relay admin subcommands missing nip11.privkey get the same treatment.

Exit code and --json are unchanged — still exit 2 / {"code":"usage"} with no help dump, verified.

Verification

gofmt, go build ./..., go vet ./..., go test -short -race ./..., golangci-lint v2.13.2 → 0 issues. No test asserts on Short/Long text, and the help output was spot-checked per command.

The help text had drifted into explaining itself. profile's description
was the clearest case -- it recited which kinds it queries and then
argued why it doesn't behave like find, which is the reasoning behind
the command rather than a description of it.

Rewritten flatter throughout, closer to how docker's CLI reads: say what
the command does, state the rules a caller can't guess ("--targets
cannot be combined with --relays"), and drop the rationale. Short lines
lose their parentheticals and "(s)" plurals.

Also fixes the error that prompted this. "ncli relay" with no config
printed three alternatives crammed into one line and nothing else:

  Error: no relay config found -- pass --config, run "ncli relay context
  use <name>", or add ncli.yaml/relay.yaml here

It now prints a short error and then the command's own help, so the
flags and examples are right there, and the config search order moved
into the description where it belongs. The admin subcommands missing
nip11.privkey get the same treatment. Exit code and --json output are
unchanged.
@naliyi
naliyi merged commit 6dc45f6 into main Sep 23, 2026
7 of 8 checks passed
@naliyi
naliyi deleted the worktree-docker-style-descriptions branch September 23, 2026 16:21
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