sphere-cli UX consistency: unified currency input, human-friendly default output, complete --help, autocomplete, auto-help on invalid input

[vrogojin]

Streamline the sphere-cli command-line UX so every command, subcommand, and sub-subcommand behaves consistently in how it takes input and how it presents output. This is a follow-up to the post-#397/#401 cleanup pass; the user will pick it up after a fresh-context session, so this issue is deliberately self-contained.

Scope — five concrete consistency goals

1. Unified currency input across all commands

Canonical syntax: human-friendly fractional amount separated from the coin symbol by a space.

sphere payments send <recipient> 100.5 UCT
sphere invoice create --target @alice --asset "7 UCT" --asset "0.001 BTC"
sphere swap propose --to @bob --offer "7 UCT" --want "2 ETH"
sphere invoice return <id> --recipient @bob --asset "100000 UCT"

Today this mostly works (src/legacy/legacy-cli.ts:425 parseAssetArg already handles "<amount> <symbol>" and several commands consume it), but coverage is incomplete and the argument shape diverges:

• payments send <recipient> <amount> <coin> uses positional amount + coin (separate tokens)
• invoice-create --asset "<amount> <coin>" uses quoted compound form
• swap-propose --offer "<amount> <coin>" matches invoice-create
• invoice-return --asset "<amount> <coin>" matches invoice-create

Required: every command that takes amount-plus-coin must accept the same form. Pick one canonical syntax (recommendation: positional <amount> <coin> mirrors payments send's shape and avoids the quote-juggling), document it once, and adapt every other site to accept it. NFT (--nft <tokenId>) input rules also need to be consistent across invoice-create / swap-propose / payments send.

2. Human-friendly default output (not raw JSON)

Most commands today print a raw JSON.stringify(result, null, 2) blob. Inventory in src/legacy/legacy-cli.ts:

Line	Command
3093	nametag resolve/check
3129 / 3142	identity / address inspection
4166	invoice-list
4261	invoice-status (one of two sites)
4309	invoice-import
4383	invoice-deliver
4494 / 5266	invoice-status
4618	invoice-pay
4688	invoice-return
4722	invoice-cancel / similar

…plus ~17 more JSON.stringify outputs at lines 1798, 1894, 3015, 3093, 3177, 3195, 3216, etc.

Required: default output for end-user-facing commands should be a prettified table or labelled key-value block (see invoice-status line 4446 which already does ID: ... / Status: ... labelling — that style should be the template). Raw JSON output should be opt-in via a --json flag (machine-readable mode for scripts / pipes).

Acceptance: running e.g. sphere invoice create --target @alice --asset \"7 UCT\" and sphere invoice deliver <id> --to @bob should produce a readable table by default; --json should still emit the existing structured form for backwards compatibility with anyone scripting against the CLI.

3. Help works for every command, subcommand, sub-subcommand

Today the --help / -h / help handler is wired at a single top-level entrypoint (src/legacy/legacy-cli.ts:1716 and a second branch at line 1723), but the dispatch through to specific subcommands is patchy. Symptoms:

• sphere wallet --help may not print wallet-specific help
• sphere invoice deliver --help may not print deliver-specific help
• sphere swap propose --help likewise

Required: every command in the COMMANDS registry (search src/legacy/legacy-cli.ts for usage: — 57+ entries) should respond to --help / -h / help by printing its own usage + flag table + examples. Common idiom in similar CLIs: a single helper printHelpFor(commandName) that the early-dispatch path calls before any side-effecting work runs.

4. Bash/zsh autocompletion

A completion generator already exists at src/legacy/legacy-cli.ts:5599+ (sphere-cli completions bash), but the user reports autocompletion is not working at all in practice. Two likely causes, both worth verifying:

1. The generator output may not match the actual command shape (e.g. it's stale vs the current COMMANDS table at line 533+).
2. Installing the completion file requires a system path (/etc/bash_completion.d/sphere-cli) which needs sudo. The setup step may not be documented as part of sphere init / installation.

Required:

• Verify the generated completion is correct against the current command/flag inventory.
• Document the installation step in the README (sudo path) and offer a no-sudo per-user fallback (~/.bash_completion.d/ / zsh $fpath).
• If kernel/system-level setup is required, defer the actual install step but ship the verified-correct generator so the user can do the install themselves later.

5. Auto-help on invalid input

Today, invalid input typically falls through to console.error('Usage: ...') followed by process.exit(1). The single-line usage string isn't enough — it omits flag descriptions and examples. Recommended: on any parse failure (unknown subcommand, missing required arg, bad asset spec), the CLI should:

1. Print a one-line "Error: " message
2. Print the full help block for the closest matching subcommand
3. Exit non-zero

Common in modern CLIs (Cargo, kubectl, gh). Concrete example today: passing sphere invoice create with no --asset flag should print the full invoice-create help, not just the one-line usage.

Suggested phasing (for the implementer)

1. Pass A — output: route every JSON.stringify(result, ...) site through a shared formatOutput(payload, { json }) helper. Add --json to the global flag set so it applies everywhere. Define table formatters for the common payload shapes (Invoice, InvoiceStatus, TransferResult, Asset[], Token[], PeerInfo).
2. Pass B — input: pick the canonical <amount> <coin> syntax and write one parseAssetArg (the existing one at line 425 is a good base) that every command uses. Update help strings + examples in lockstep.
3. Pass C — help: add printHelpFor(commandName) and a single early-dispatch shim at the top of runCli() that catches --help / -h / help <cmd> / missing-required-arg cases and prints help instead of running the command.
4. Pass D — completion: verify generator output, document install (with sudo + no-sudo paths), add a CI smoke that diffs the generator output against a golden file so it can't drift.

Each pass is mergeable independently. Pass A delivers the most visible user win and should land first.

Out of scope

• Cosmetic redesign (colors, ASCII art, etc.) — focus is consistency, not theming.
• Migrating off the legacy-cli.ts monolith — that's its own refactor; this issue can land within the existing file structure.
• Daemon-mode commands (sphere daemon ...) — separate UX surface; consistency goals apply but daemon-output formats can be tackled in a follow-up if needed.

Related

• invoice status crashes with 'Cannot read properties of undefined' when invoice not found locally #21 invoice status crashes with 'Cannot read properties of undefined' when invoice not found locally — adjacent UX failure mode (invalid input should print help, not crash)
• invoice-status uses ensureSync(sphere, 'nostr') — should be 'full' to trigger IPFS pull #24 invoice-status uses ensureSync(sphere, 'nostr') — should be 'full' to trigger IPFS pull — adjacent invoice-command issue
• Recently merged in sphere-sdk: #397 (PR #400) routed invoice delivery through the token pipeline; #401 (PR #402) wired OUTBOX/SENT durability for that path. Neither changed the CLI surface, so this UX consistency pass is the natural next step on the invoice-flow polish.

[vrogojin]

Closing summary — 2026-06-05

All five UX goals landed across three sphere-cli PRs and one sphere-sdk PR. Soak suite green end-to-end.

What shipped

PR	Merge	What
sphere-cli #33	946ff48b	feat(cli)(#32): canonical UX — --json, --help, asset-pair input, auto-help on errors — the primary issue-#32 implementation
sphere-cli #34	55fdde6c	chore: merge integration/all-fixes into main (50-commit rollup) — required for PR #33 to land against a main that included sphere invoice deliver and the other dev-line features
sphere-cli #35	02f56dfd	fix(cli): bump SDK pin past #397 + treat invoice amounts as human units — the cross-command semantic fix that closes the "all canonical" gap PR #33 missed
sphere-sdk #403	1d2d7e26	test(soak): adapt to canonical CLI UX — soak scripts updated for the dropped legacy form + --json opt-in

Per-goal status

1. Unified currency input across all commands ✅

Canonical: <amount> <coin> as two positional tokens. Quoted compound form (--asset "7 UCT") removed entirely (no legacy shim).

• sphere payments send @bob 100.5 UCT (already canonical)
• sphere invoice create --target @alice --asset 7 UCT --asset 0.5 BTC (multi-asset supported)
• sphere invoice return <id> --recipient @bob --asset 100 UCT
• sphere swap propose --to @bob --offer 10 UCT --want 5 USDU

NFT input: --nft <tokenId> on invoice-create consistently.

2. Human-friendly default output ✅

Default output for every end-user command is a labelled key-value block (e.g. Invoice Status: followed by state : COVERED). Raw JSON is opt-in via --json (global flag honoured by every command).

Routed through formatOutput(payload, shape, label?) helper. ~22 console.log(JSON.stringify(...)) sites converted.

3. Help works for every command, subcommand, sub-subcommand ✅

--help / -h works at any depth. Early-dispatch shim in main() resolves compound keys (wallet create, daemon start) against COMMAND_HELP registry, falls back to the top-level command key. sphere help <cmd> and sphere <cmd> --help are equivalent.

Universal flags block (--json, --help/-h) appears in every help block.

4. Bash/zsh autocompletion ✅

getCompletionCommands() audited against COMMAND_HELP (drift-guard test in legacy-cli-ux.test.ts makes them stay in sync). README documents install paths: no-sudo (~/.local/share/bash-completion/completions/sphere), system-wide (sudo tee /etc/bash_completion.d/sphere), per-user zsh (~/.zsh/completions/_sphere).

5. Auto-help on invalid input ✅

Single failWithHelp(cmdName, errorMsg) helper:

1. Prints Error: <msg> to stderr
2. Prints the full COMMAND_HELP block to stderr
3. Exits 1

Every console.error('Usage: ...'); process.exit(1) stub replaced (~40 call sites). Closes the invoice status UX issue referenced in #21.

Static invariants guard

src/legacy/legacy-cli-ux.test.ts — 7 regex-over-source tests that fail CI when:

• A stray console.log(JSON.stringify(...)) appears in the dispatch body
• A legacy console.error('Usage: …'); process.exit(1) stub reappears
• A parseAssetArg(...) call site reappears (the deleted quoted-form parser)
• A COMMAND_HELP key isn't reachable through the completion generator
• formatOutput / failWithHelp / consumeAssetPair helpers go missing
• The --json / --help early dispatch shims go missing

End-to-end verification

All three sphere-sdk soaks green against the merged state:

Soak	Result
manual-test-roundtrip-391.sh	✅ PASS (193s)
manual-test-accounting-roundtrip.sh	✅ PASS (118s)
manual-test-full-recovery.sh	✅ PASS (513s)

Plus the existing 126/126 unit-test suite stays green.

Known follow-up

• invoice pay --amount does not yet do human-unit conversion (still treats amount as smallest-unit integer). Needs an SDK lookup of the invoice's coin/decimals; warrants its own PR. The accounting-roundtrip soak doesn't exercise --amount, so this is non-urgent. Tracking as a deferred TODO; happy to file a separate issue if useful.

Lessons surfaced during implementation

Two real regressions surfaced and were fixed during soak verification:

1. SDK pin lag broke invoice DM ingestion — the initial pin predated sphere-sdk PR #400 / #397 (route invoice delivery through the standard TOKEN_TRANSFER pipeline). Receiver decoder couldn't ingest bespoke invoice_delivery: DMs. Fix: bump pin to sphere-sdk main tip.
2. Invoice amount atom-vs-UCT inconsistency — payments send 7 UCT meant 7 UCT but invoice create --asset 7 UCT meant 7 atoms. Fix: toSmallestUnit(amount, decimals) in invoice create / invoice return. The canonical-UX rule is now: same syntax AND same semantics across the whole command surface.