You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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).
Copy file name to clipboardExpand all lines: Docs/CLI.md
+7-4Lines changed: 7 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,21 +47,24 @@ Options:
47
47
48
48
### About `--port`
49
49
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`.
51
51
52
52
`--port` is only required when:
53
53
- 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.
55
57
56
58
## Operating Modes
57
59
58
60
| Mode | Trigger | Behavior |
59
61
|------|---------|----------|
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 |
61
64
| Local proxy |`--port` + local server running | Attach to server, forward device ops |
62
65
| Local auto-launch |`--port` + no local server | Auto-launch server, then proxy |
63
66
| 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) |
0 commit comments