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 Issues19 Breadcrumbs Pull Requests1 Activity

Closed general

John Lauer · 3mo ago ·closed by John Lauer

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.

1 Reply

John Lauer · 2mo ago

Fixed in 2.0.84. Half of this had already been fixed; the half that mattered most for your rename had not, and was worse than you described.

Path 1 (<verb> --help parsed as JSON args) - already fixed before this. adom-bridge pup_status --help routes to the help catalog now.

Path 2 (help <verb> fails on the advertised example) - was still live, and circular. help browser_open_window printed "No help available" and then said:

adom-bridge help <verb>     (e.g. server_add, browser_open_window)

The suggested next step was the exact thing that had just failed. Three other places advertised the same retired verb too.

What it does now:

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

Did you mean:  pup_open_window

  adom-bridge help pup_open_window

Try one of:
  adom-bridge help            (list all namespaces)
  adom-bridge help <verb>     (e.g. server_add, pup_open_window)

The ranking is weighted for exactly your case: a rename usually keeps the TAIL and swaps the namespace, so shared trailing tokens score highest. It mirrors ab-core's own unknown-verb did_you_mean so the CLI and the server teach the same way.

One deliberate property: nonsense suggests nothing. A wrong suggestion sends a caller down a second dead end, so a single shared generic token ("open", "list") is not treated as evidence - containment or two shared tokens required. Unit tests cover the rename, a typo, nonsense, and that guard.

Your framing was the useful part of this report: a clean break is supposed to make a stale caller rediscover the surface, and that only works if rediscovery leads somewhere. It does now.

John Lauer closed this · 2mo ago

Adom Bridge