Skip to content

Commit 593f648

Browse files
committed
docs(cli): clarify port-less mode for local servers
The 'About --port' section already promised that --port is optional when the server has a connected device, but the operating modes table only listed port-less attach implicitly via the remote-proxy row. - State that port-less attach applies to BOTH local and remote. - Add a 'Local proxy (port-less)' row to the modes table. - Clarify that 'offline fallback' is local-only: in remote mode the CLI still attaches the proxy when the server is reachable even if no device is connected (per Copilot review).
1 parent fc17feb commit 593f648

1 file changed

Lines changed: 7 additions & 4 deletions

File tree

Docs/CLI.md

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -47,21 +47,24 @@ Options:
4747

4848
### About `--port`
4949

50-
The serial port belongs to the **WebServer**, not the CLI. When a server is already running and has a device connected, `--port` is not needed — the CLI attaches to the server's existing connection.
50+
The serial port belongs to the **WebServer**, not the CLI. When a server is already running and has a device connected, `--port` is not needed — the CLI attaches to the server's existing connection. This applies to **both local and remote** servers: as long as `/api/status` reports `connected=true`, you can run device commands without `--port`.
5151

5252
`--port` is only required when:
5353
- No server is running locally (triggers auto-launch + direct fallback).
54-
- The remote server has no device connected yet (tells it which port to open).
54+
- The local or remote server is reachable but has no device connected yet (tells it which port to open).
55+
56+
Without `--port` the CLI never opens a serial port directly — it either attaches to a server that already owns one, or stays offline (ELF analysis / compile commands always work). In remote mode the CLI still attaches to a reachable server even before a device is connected; device commands will fail until you connect a device, but offline ELF/compile commands remain available.
5557

5658
## Operating Modes
5759

5860
| Mode | Trigger | Behavior |
5961
|------|---------|----------|
60-
| Offline | No `--port`, no server | ELF analysis / compile only |
62+
| Offline (local) | No `--port`, no local server (or server has no device) | ELF analysis / compile only |
63+
| Local proxy (port-less) | No `--port`, local server already has a device | Attach to server's existing connection |
6164
| Local proxy | `--port` + local server running | Attach to server, forward device ops |
6265
| Local auto-launch | `--port` + no local server | Auto-launch server, then proxy |
6366
| Local direct | `--direct --port` | Open serial directly (bypass server) |
64-
| Remote proxy | `--server-url http://remote:port` | Pure proxy to remote server, no auto-launch |
67+
| Remote proxy | `--server-url http://remote:port` | Pure proxy to remote server, no auto-launch (attaches even if no device yet) |
6568

6669
## Remote Control
6770

0 commit comments

Comments
 (0)