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

CHANGELOG.md

@@ -29,8 +29,8 @@
 - Updated `nmilat` to v0.4.0.
 - Rewrote every command's `--help` description in a flatter style: each
   one now states what the command does, with the rules a caller can't
-  guess stated plainly, instead of explaining the reasoning behind it.
-  (#61)
+  guess stated plainly, instead of explaining how it works internally.
+  (#61, #62)
 
 ### Fixed
 

cli/blossom/command.go

@@ -14,11 +14,8 @@ func NewBlossomCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "blossom",
 		Short: "Manage content on Blossom media servers",
-		Long: `A client for the Blossom protocol (BUD-01..12): content-addressed blob
-storage authenticated with a Nostr identity.
-
-upload, rm and mirror write to every configured server and exit non-zero
-if any fails. download reads from them in order until one answers.`,
+		Long: `A client for the Blossom protocol (BUD-01..12): file storage for Nostr
+identities.`,
 		Example: `  ncli blossom upload ./photo.jpg --identity satoshi
   ncli blossom download <hash> -o photo.jpg
   ncli blossom servers list`,

cli/blossom/download.go

@@ -29,11 +29,7 @@ func newDownloadCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "download <hash|blossom-uri|url>",
 		Short: "Download a blob by hash, blossom: URI, or server URL",
-		Long: `Download a blob, given a bare sha256 hash, a "blossom:<hash>.<ext>" URI
-(BUD-10), or a server URL ending in a hash. Servers are tried in order
-until one answers.
-
-Writes to --output, or to "<hash>.<ext>" in the current directory. Use
+		Long: `Writes to --output, or to "<hash>.<ext>" in the current directory. Use
 "-o -" to stream to stdout.`,
 		Example: `  ncli blossom download <hash>
   ncli blossom download <hash> -o -`,

cli/blossom/list.go

@@ -25,10 +25,7 @@ func newListCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list [identifier]",
 		Short: "List blobs stored under a pubkey",
-		Long: `List the blobs a pubkey has stored on the first configured server, or on
-every server with --all, merged and deduplicated by hash.
-
-identifier accepts a vault label, npub, hex pubkey, nprofile or nip-05
+		Long: `identifier accepts a vault label, npub, hex pubkey, nprofile or nip-05
 address, and defaults to --identity's pubkey.`,
 		Example: `  ncli blossom list --identity satoshi
   ncli blossom list --identity satoshi --all

cli/blossom/mirror.go

@@ -12,10 +12,8 @@ import (
 
 func newMirrorCommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "mirror <source-url>",
-		Short: "Mirror a blob from a URL to your Blossom servers",
-		Long: `Ask every target server to fetch and store a blob from source-url. Each
-server downloads it directly; no bytes pass through ncli.`,
+		Use:     "mirror <source-url>",
+		Short:   "Mirror a blob from a URL to your Blossom servers",
 		Example: `  ncli blossom mirror https://example.com/file.jpg --identity satoshi`,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) != 1 {

cli/blossom/report.go

@@ -12,10 +12,8 @@ import (
 
 func newReportCommand() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "report <hash>",
-		Short: "Report a blob to a Blossom server",
-		Long: `Submit a signed kind:1984 report event for a blob (BUD-09). Targets a
-single server: --server, or the first configured one.`,
+		Use:     "report <hash>",
+		Short:   "Report a blob to a Blossom server",
 		Example: `  ncli blossom report <hash> --identity satoshi`,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) != 1 {

cli/blossom/rm.go

@@ -18,10 +18,9 @@ func newRmCommand() *cobra.Command {
 	var yes bool
 
 	cmd := &cobra.Command{
-		Use:   "rm <hash>",
-		Short: "Delete a blob from your Blossom servers",
-		Long: `Delete a blob from every target server. Requires --yes in a
-non-interactive session.`,
+		Use:     "rm <hash>",
+		Short:   "Delete a blob from your Blossom servers",
+		Long:    `Requires --yes in a non-interactive session.`,
 		Example: `  ncli blossom rm <hash> --identity satoshi --yes`,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) != 1 {

cli/blossom/servers.go

@@ -20,7 +20,6 @@ func newServersCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "servers",
 		Short:   "Manage the default Blossom server list",
-		Long:    `Manage the server list used when a command is given no --server flag.`,
 		Example: `  ncli blossom servers list`,
 		RunE:    common.RequireSubcommand,
 	}
@@ -268,10 +267,7 @@ func newServersDiscoverCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "discover <identifier>",
 		Short: "Show another identity's published server list",
-		Long: `Print the Blossom servers another identity has published, from their
-most recent kind:10063 event (BUD-03).
-
-identifier accepts a vault label, npub, hex pubkey, nprofile or nip-05
+		Long: `identifier accepts a vault label, npub, hex pubkey, nprofile or nip-05
 address.`,
 		Example: `  ncli blossom servers discover npub1...`,
 		Args:    common.ExactArgs(1),

cli/blossom/upload.go

@@ -22,8 +22,7 @@ func newUploadCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "upload <file> [file...]",
 		Short: "Upload files to your Blossom servers",
-		Long: `Upload each file to every target server, reporting a result per (file,
-server) pair. Exits non-zero if any pair fails.
+		Long: `Exits non-zero if any file fails on any server.
 
 --optimize requests server-side transcoding (BUD-05) instead of storing
 the bytes as-is.`,

cli/bunker/command.go

@@ -34,12 +34,12 @@ func NewBunkerCommand() *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "bunker",
-		Short: "Run ncli as a NIP-46 remote signer",
-		Long: `Listen on relays for other clients' NIP-46 signing requests and approve
-or reject them from a TUI. Per-app decisions are remembered.
+		Short: "Sign other apps' events as a NIP-46 signer",
+		Long: `Approve or reject other clients' signing requests as they arrive.
+Per-app decisions are remembered.
 
-On Linux and macOS a background daemon keeps running when the TUI
-closes. Reattach with "ncli bunker attach".`,
+The signer keeps running after you close it. Reattach with
+"ncli bunker attach".`,
 		Example: `  ncli bunker
   ncli bunker --identity satoshi
   ncli bunker attach`,
@@ -89,10 +89,9 @@ func requireInteractive(cmd *cobra.Command) error {
 
 func newAttachCommand() *cobra.Command {
 	return &cobra.Command{
-		Use:   "attach",
-		Short: "Reattach the TUI to a running bunker daemon",
-		Long: `Reconnect the TUI to a bunker daemon already running in the background.
-Never starts one; fails if none is running.`,
+		Use:     "attach",
+		Short:   "Reattach to a running bunker",
+		Long:    `Fails if no bunker is running; never starts one.`,
 		Example: `  ncli bunker attach`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if err := requireInteractive(cmd); err != nil {
@@ -116,7 +115,7 @@ Never starts one; fails if none is running.`,
 func newStatusCommand() *cobra.Command {
 	return &cobra.Command{
 		Use:     "status",
-		Short:   "Show whether a bunker daemon is running",
+		Short:   "Show whether a bunker is running",
 		Example: `  ncli bunker status`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			jsonMode, _ := cmd.Flags().GetBool("json")
@@ -200,7 +199,7 @@ func printIdentityAndRelays(st StatusInfo) {
 func newStopCommand() *cobra.Command {
 	return &cobra.Command{
 		Use:     "stop",
-		Short:   "Stop the running bunker daemon",
+		Short:   "Stop the running bunker",
 		Example: `  ncli bunker stop`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			jsonMode, _ := cmd.Flags().GetBool("json")
@@ -256,7 +255,7 @@ func newSessionsCommand() *cobra.Command {
 
 	cmd.AddCommand(&cobra.Command{
 		Use:     "list",
-		Short:   "List every app with a remembered permission",
+		Short:   "List apps with remembered permissions",
 		Example: `  ncli bunker sessions list`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			jsonMode, _ := cmd.Flags().GetBool("json")
@@ -288,7 +287,7 @@ func newSessionsCommand() *cobra.Command {
 
 	cmd.AddCommand(&cobra.Command{
 		Use:     "revoke <pubkey>",
-		Short:   "Revoke every remembered permission for one app",
+		Short:   "Revoke all of an app's permissions",
 		Example: `  ncli bunker sessions revoke <pubkey>`,
 		Args:    common.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -318,7 +317,8 @@ func newSessionsCommand() *cobra.Command {
 
 	cmd.AddCommand(&cobra.Command{
 		Use:     "rename <pubkey> <name>",
-		Short:   "Set (or clear, with \"\") a trusted app's display name",
+		Short:   "Rename a trusted app",
+		Long:    `Pass an empty name to clear it.`,
 		Example: `  ncli bunker sessions rename <pubkey> "My Wallet"`,
 		Args:    common.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -392,7 +392,7 @@ func newSessionsCommand() *cobra.Command {
 
 	revokeGrantCmd := &cobra.Command{
 		Use:     "revoke-grant <pubkey>",
-		Short:   "Revoke one remembered permission, leaving the rest",
+		Short:   "Revoke one of an app's permissions",
 		Example: `  ncli bunker sessions revoke-grant <pubkey> --method sign_event`,
 		Args:    common.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -500,10 +500,9 @@ func newHistoryCommand() *cobra.Command {
 func newConnectCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "connect [nostrconnect-uri]",
-		Short: "Pair an app with a running bunker daemon",
-		Long: `Print a fresh bunker:// URI for another Nostr app to connect to. Given a
-nostrconnect:// URI, start that pairing instead and block until the
-client confirms or it times out.
+		Short: "Pair an app with a running bunker",
+		Long: `With no argument, prints a bunker:// URI for another app to connect to.
+Given a nostrconnect:// URI, pairs with that app instead.
 
 --grants pre-authorizes the paired app from a YAML permission file
 instead of prompting on first use.`,

cli/delegate/command.go

@@ -28,8 +28,8 @@ func NewDelegateCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "delegate",
 		Short: "Generate a NIP-26 delegation token",
-		Long: `Create and sign a NIP-26 delegation token. Runs an interactive wizard
-unless --issuer is set, via the flag or NCLI_DELEGATE_ISSUER.
+		Long: `Runs an interactive wizard unless --issuer is set, via the flag or
+NCLI_DELEGATE_ISSUER.
 
 --issuer and --delegatee accept a vault label, nsec, npub, hex pubkey,
 nprofile or nip-05 address, and must resolve to a private key.`,

cli/ncli/apply.go

@@ -15,7 +15,6 @@ var (
 	applyCmd = &cobra.Command{
 		Use:   "apply",
 		Short: "Run a stream, sync, or inspect workflow",
-		Long:  `Run a stream, sync, or inspect workflow defined in a YAML config file.`,
 		Example: `  ncli apply -f sync.yaml
   ncli apply -f sync.yaml --strict-pow`,
 		Args: func(cmd *cobra.Command, args []string) error {

cli/ncli/dump.go

@@ -18,10 +18,7 @@ import (
 var dumpCmd = &cobra.Command{
 	Use:   "dump",
 	Short: "Export events to JSON",
-	Long: `Export events matching a filter to a JSON file, merged and deduplicated
-by event ID across all targets.
-
---targets cannot be combined with --relays or the inline filter flags.
+	Long: `--targets cannot be combined with --relays or the inline filter flags.
 Omit both to use the relays from "ncli prefs relays".`,
 	Example: `  ncli dump -o events.json
   ncli dump -t targets.yaml -o events.json

cli/ncli/find.go

@@ -18,9 +18,9 @@ var (
 	findCmd = &cobra.Command{
 		Use:   "find [identifier]",
 		Short: "Query events by ID and/or filter",
-		Long: `Query events across relays and local stores, stopping at the first
-target with a match. An npub or nip-05 identifier returns that author's
-profile unless --kinds widens it. Prints a single JSON array.
+		Long: `Returns the first target's matches as a single JSON array. An npub or
+nip-05 identifier returns that author's profile unless --kinds widens
+it.
 
 --targets cannot be combined with --relays or the inline filter flags.
 Omit both to use the relays from "ncli prefs relays".`,

cli/ncli/miner.go

@@ -22,17 +22,14 @@ import (
 var minerCmd = &cobra.Command{
 	Use:     "miner",
 	Short:   "Mine and verify proof-of-work",
-	Long:    `Mine NIP-13 proof-of-work into an unsigned event, or verify PoW on already-mined events.`,
 	Example: `  ncli miner mine -e event.json -o mined.json`,
 	RunE:    common.RequireSubcommand,
 }
 
 var minerMineCmd = &cobra.Command{
 	Use:   "mine",
-	Short: "Mine proof-of-work into an unsigned event",
-	Long: `Mine NIP-13 proof-of-work for an event across multiple CPU cores.
-
-The event comes from --event, or inline from --content/--content-file;
+	Short: "Mine proof-of-work into an event",
+	Long: `The event comes from --event, or inline from --content/--content-file;
 these cannot be combined. Exactly one of --out or --in-place is
 required. A mined event is signed if --identity resolves to a private
 key.`,
@@ -265,8 +262,8 @@ func parseTagFlags(pairs []string) ([][]string, error) {
 var minerCheckCmd = &cobra.Command{
 	Use:   "check",
 	Short: "Verify proof-of-work",
-	Long: `Verify NIP-13 proof-of-work on already-mined events, read from --events
-or fetched live from every target. Exits non-zero if any event fails.
+	Long: `Checks events from --events, or fetched live. Exits non-zero if any
+event fails.
 
 --targets cannot be combined with --relays or the inline filter flags.
 Omit both to use the relays from "ncli prefs relays".`,

cli/ncli/ping.go

@@ -15,11 +15,11 @@ import (
 var pingCmd = &cobra.Command{
 	Use:   "ping [relay...]",
 	Short: "Test relay connectivity",
-	Long: `Probe each relay with a Limit-1 subscription. Local store paths are
-skipped. Exits non-zero if any relay is unreachable.
+	Long: `Exits non-zero if any relay is unreachable. Local store paths are
+skipped.
 
 --targets cannot be combined with relay arguments. Omit both to use the
-relays from "ncli prefs relays". --tui shows a live board.`,
+relays from "ncli prefs relays".`,
 	Example: `  ncli ping wss://relay.example.com
   ncli ping -t targets.yaml
   ncli ping --tui wss://relay.example.com`,

cli/ncli/prefs.go

@@ -12,15 +12,13 @@ import (
 var prefsCmd = &cobra.Command{
 	Use:     "prefs",
 	Short:   "Manage persistent ncli preferences",
-	Long:    `Manage the preferences ncli persists across projects.`,
 	Example: `  ncli prefs relays list`,
 	RunE:    common.RequireSubcommand,
 }
 
 var prefsRelaysCmd = &cobra.Command{
 	Use:     "relays",
 	Short:   "Manage the default relay list",
-	Long:    `Manage the relay list used when a command is given no explicit targets.`,
 	Example: `  ncli prefs relays list`,
 	RunE:    common.RequireSubcommand,
 }

cli/ncli/profile.go

@@ -63,9 +63,8 @@ func newProfileCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "profile <identifier>",
 		Short: "Display an identity's published profile",
-		Long: `Display the profile metadata, following count, relay list, Blossom
-servers and lightning address published by an identity. Records are
-merged across all targets.`,
+		Long: `Shows the profile metadata, following count, relay list, Blossom
+servers and lightning address an identity has published.`,
 		Example: `  ncli profile npub1...
   ncli profile name@example.com
   ncli profile satoshi --json`,

cli/ncli/publish.go

@@ -14,11 +14,10 @@ import (
 var publishCmd = &cobra.Command{
 	Use:   "publish",
 	Short: "Publish signed events to one or more relays",
-	Long: `Send already-signed events to every target relay and wait for each
-relay's OK. --events accepts a single event or an array.
+	Long: `--events accepts a single event or an array. Exits non-zero if any
+event fails on any relay.
 
-Omit --relays to use the relays from "ncli prefs relays". Exits non-zero
-if any event fails on any relay.`,
+Omit --relays to use the relays from "ncli prefs relays".`,
 	Example: `  ncli publish -e signed.json
   ncli publish -e signed.json -s wss://relay.example.com`,
 	Args: func(cmd *cobra.Command, args []string) error {