adom-bridge <verb> '<json-args>'

adom-bridge-cli ping
# { "echo": "pong", "roundTripMs": ..., "status": "connected" }

adom-bridge-cli targets
adom-bridge-cli --target azurevm desktop_screenshot_screen
adom-bridge-cli --target all hd_status

adom-bridge-cli desktop_list_windows
adom-bridge-cli desktop_screenshot_window '{"hwnd": 12345}'

adom-bridge-cli shell_execute '{"command":"echo hello","reason":"verifying the shell path works"}'

adom-bridge-cli notify_user '{"title":"Build done","body":"The nightly build finished."}'

adom-bridge-cli send_files '{"files":["/tmp/report.pdf"],"saveTo":"C:/Users/john/Downloads"}'
adom-bridge-cli pull_file '{"filePaths":["C:/Users/john/Downloads/image.png"],"saveTo":"/tmp"}'

adom-bridge-cli serve --supervise
adom-bridge-cli serve --stop

curl -sf http://127.0.0.1:8766/health

adom-bridge-cli commands            # every verb: args, returns, prerequisites, hints
adom-bridge-cli help <topic>        # one verb or namespace, e.g. help shell, help pup

# The adom-bridge CLI

The `adom-bridge` CLI is the caller surface for Adom Bridge. The GUI app runs on your
Windows machine and does the work; the CLI is how anything else (a cloud AI in a Linux
container, a local script, you at a terminal) asks it to do that work.

![The Adom Bridge window the CLI drives](main-view.png)

## Where it comes from

There are two homes for the same CLI:

- **Cloud Linux container**: installed by the package, `adom-wiki pkg install
  adom/adom-bridge`, which lays down the `adom-bridge-cli` binary and the Claude skill
  set. The container also runs the relay server the desktop connects to.
- **Windows, next to the GUI**: the Adom Bridge installer bundles
  `adom-bridge-cli.exe` into `%LOCALAPPDATA%\Adom Bridge\` and adds that directory to
  your PATH (per-user, no UAC). It finds the local GUI automatically over the loopback
  direct API, so it works from any fresh terminal with no relay running.

## The mental model

Almost nothing in the CLI is a traditional subcommand. You invoke a verb by name with a
JSON argument, and the CLI forwards it to the desktop app:

```bash
adom-bridge <verb> '<json-args>'
```

From a container the verb travels over the relay (a WebSocket hub the desktop dials out
to). On Windows with no target specified, it goes straight to the local GUI. Either way
the desktop executes it and you get back identical JSON: the same `status`
(`ok` | `timeout` | `busy` | `error`), `durationMs`, `_hint`, and error fields on every
path, so code written against one path works on all of them.

Note that `adom-bridge-cli --help` only lists the `serve` and `install` subcommands. The
real functionality is the dynamic verb catalog, discovered at runtime (see the last
section).

## Cookbook

Is the desktop reachable?

```bash
adom-bridge-cli ping
# { "echo": "pong", "roundTripMs": ..., "status": "connected" }
```

Which desktops are connected, and how do I address one? (With several desktops on one
relay, a call without `--target` fails as ambiguous rather than guessing.)

```bash
adom-bridge-cli targets
adom-bridge-cli --target azurevm desktop_screenshot_screen
adom-bridge-cli --target all hd_status
```

Take a screenshot of one window (the PNG is pulled to a local cache and the path
returned):

```bash
adom-bridge-cli desktop_list_windows
adom-bridge-cli desktop_screenshot_window '{"hwnd": 12345}'
```

Run a shell command on the desktop. This requires user approval when called over the
relay, and the `reason` is shown verbatim in the approval prompt:

```bash
adom-bridge-cli shell_execute '{"command":"echo hello","reason":"verifying the shell path works"}'
```

Send the user a desktop notification:

```bash
adom-bridge-cli notify_user '{"title":"Build done","body":"The nightly build finished."}'
```

Move files between the container and the desktop:

```bash
adom-bridge-cli send_files '{"files":["/tmp/report.pdf"],"saveTo":"C:/Users/john/Downloads"}'
adom-bridge-cli pull_file '{"filePaths":["C:/Users/john/Downloads/image.png"],"saveTo":"/tmp"}'
```

Start the relay in a container. Use `--supervise`: a plain backgrounded `serve &` dies
when your session is torn down and leaves every connected desktop stuck reconnecting.
The supervised relay detaches, restarts itself with backoff, and notifies the connected
desktops when it does:

```bash
adom-bridge-cli serve --supervise
adom-bridge-cli serve --stop
```

Check the relay is up:

```bash
curl -sf http://127.0.0.1:8766/health
```

## Learning every verb

The complete, always-current catalog lives in the tool itself:

```bash
adom-bridge-cli commands            # every verb: args, returns, prerequisites, hints
adom-bridge-cli help <topic>        # one verb or namespace, e.g. help shell, help pup
```

Run `commands` before reaching for `shell_execute`; most operations have a structured
verb with typed arguments (process control, file watching, window management, WSL,
tunnels) that needs no shell quoting at all. The full grouped reference is also in
[VERBS.md](../VERBS.md).