CLI verb-help is a dead end: '--help' parses as JSON args, 'help <old-verb>' fails on the advertised example

by adom

Adom Bridge unleashes your AI onto your full PC: full power, full safety. The AI breaks out of the container it runs in and onto your real machine, managing and running your entire laptop as you: launch apps, move files, drive any window, control KiCad, Fusion 360 or your real signed-in browser. Works with any AI, cloud or local (Claude Desktop, Claude Code, Codex), no Hydrogen required. Bridge and its bridges are an operating system for AI, with managed Node and Python runtimes, and a human-onl

Overview Files Skills Discover Packages Releases Dependencies Issues40 Breadcrumbs Pull Requests Activity

Open general

John Lauer · 1d ago

The CLI's verb-help paths are dead ends, which matters most right when a verb rename breaks a caller and the AI tries to rediscover the surface.

Found while running the pup browser_* -> pup_* clean break. The break is supposed to make a stale caller go "something changed" and rediscover the verbs, but every natural rediscovery path in the CLI fails:

1. `--help` on any verb is parsed as JSON args

$ adom-bridge-cli pup_readiness --help
{ "error": "Invalid JSON args: invalid number at line 1 column 2" }

Same for every verb, old or new. --help after a verb should route to the same output as help <verb>, not be fed to the JSON args parser. This is the single most common thing an AI tries after an unknown-verb error.

2. `help <verb>` fails on the exact example the top-level help advertises

Top-level adom-bridge-cli --help says:

  adom-bridge-cli browser_open_window help    # same as `help browser_open_window`

but:

$ adom-bridge-cli help browser_open_window
No help available for 'browser_open_window'.

So the CLI advertises an alias-aware help path (pup ... (alias: browser)) that does not resolve. Either make help <verb> resolve through the same alias table the namespace listing uses (and, for renamed families, say "renamed to pup_open_window"), or stop printing the old-name example.

3. `help pup` works but titles itself `adom-bridge browser`

Cosmetic: the namespace help for pup prints the legacy alias as the header. Post-cutover it should lead with pup.

Context

pup 2.0.14 now ships a guidance shim (re-claims the browser_ prefix, answers verb_renamed + the exact pup_* replacement), which fixes the relayed-verb path. But the CLI-local help paths above are ab core's, and they are the fallback an AI reaches for when a verb errors. Repro'd on adom-bridge-cli 2.0.1 against ab 2.0.9.

Adom Bridge