mobitru-mobile-cli 1.0.0-beta.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobitru-mobile-cli",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0",
   "description": "Mobitru CLI (mobile) — command-line tool for AI agents to automate mobile testing on Mobitru cloud (Appium-backed)",
   "keywords": [
     "mobitru",

package/skills/SKILL.md

@@ -116,6 +116,44 @@ Snapshot refs are session-type-specific (native AX tree ≠ web DOM tree).
 Re-snapshot after switching. Recording and logs survive a switch unchanged —
 the cloud captures the device's screen regardless of which session is active.
 
+## Parallel sessions
+
+Drive multiple devices in parallel by naming each session with `-s/--session`
+(or `MOBITRU_CLI_SESSION` env). Each session has its own daemon and its own
+active booking; commands sent to different sessions don't interfere.
+
+```bash
+# Terminal 1
+mobitru-mobile-cli -s android device-use <serial-a>
+mobitru-mobile-cli -s android snapshot
+
+# Terminal 2 — runs in parallel
+mobitru-mobile-cli -s ios device-use <serial-b>
+mobitru-mobile-cli -s ios snapshot
+```
+
+Set a per-shell default and skip the flag; `-s` still overrides the env for
+a single invocation:
+
+```bash
+export MOBITRU_CLI_SESSION=android
+mobitru-mobile-cli device-use <serial-a>             # uses session "android"
+mobitru-mobile-cli -s ios device-use <serial-b>      # one-off override
+```
+
+Management:
+
+```bash
+mobitru-mobile-cli session-list      # what's running, on what device
+mobitru-mobile-cli session-current   # which session the next command resolves to
+mobitru-mobile-cli stop              # stop the current session (releases its device + cleans up)
+mobitru-mobile-cli stop --all        # stop every session
+```
+
+Without `-s` or the env, commands go to the implicit `default` session —
+fully backward-compatible. See [references/mobile-sessions.md](references/mobile-sessions.md)
+for details.
+
 ### Observation
 
 ```bash

package/skills/references/mobile-sessions.md

@@ -1,9 +1,10 @@
 # Mobitru Mobile Sessions
 
-This CLI leases **one real device at a time** from Mobitru cloud. Every
-command runs against a remote phone or tablet — there is no local emulator.
-Session state (active booking, Appium session) persists across short-lived
-CLI invocations until you `stop` or `device-release`.
+This CLI leases real devices from Mobitru cloud — one per session, with
+multiple sessions running in parallel if you need to drive several devices
+at once. Every command runs against a remote phone or tablet — there is no
+local emulator. Session state (active booking, Appium session) persists
+across short-lived CLI invocations until you `stop` or `device-release`.
 
 ## Booking lifecycle
 
@@ -27,10 +28,10 @@ mobitru-mobile-cli device-release
 `device-use` is the entry point. Without an active booking, interaction
 commands fail with `no active device — run device-use first`.
 
-## Single-device model
+## One device per session
 
-The CLI holds exactly **one active booking at a time**. Trying to book a
-different device without releasing the current one fails:
+A session holds **one active booking at a time**. Trying to book a different
+device in the same session without releasing the current one fails:
 
 ```
 device "<serial>" is currently in use. Run device-release first, then device-use <new-serial>.
@@ -40,6 +41,43 @@ This is deliberate. Refs from `snapshot` describe screen coordinates on the
 booked device; if the booking silently switched, `tap e3` would land on a
 different phone. Releasing first makes the switch explicit.
 
+## Parallel sessions
+
+To drive multiple devices simultaneously, name each session with
+`-s/--session`. Each session has its own daemon under
+`~/.mobitru-cli/mobile/sessions/<name>/` and its own active booking; commands
+target the right session by name.
+
+```bash
+# Terminal 1
+mobitru-mobile-cli -s android device-use <serial-a>
+mobitru-mobile-cli -s android snapshot
+
+# Terminal 2 — runs in parallel
+mobitru-mobile-cli -s ios device-use <serial-b>
+mobitru-mobile-cli -s ios snapshot
+```
+
+Set `MOBITRU_CLI_SESSION` as a per-shell default to skip the flag on every
+command; `-s` still overrides the env for a single invocation. Without
+either, commands resolve to the `default` session.
+
+Session names match `[a-zA-Z0-9_-]+`, max 32 chars. The `-s` flag goes
+**before** the subcommand (Commander convention):
+`mobitru-mobile-cli -s ios device-use SERIAL`.
+
+### Managing sessions
+
+```bash
+mobitru-mobile-cli session-list      # all sessions on this machine + their state
+mobitru-mobile-cli session-current   # the session this shell resolves to
+mobitru-mobile-cli stop              # stop the current session: release device + clean up
+mobitru-mobile-cli stop --all        # stop every session: release every device
+```
+
+`session-list` flags directories whose daemon is dead/absent as `stale`.
+A subsequent `stop` (with the right `-s` selector) cleans them up.
+
 ## Cleanup window
 
 After `device-release`, the cloud puts the device through a cleanup phase —
@@ -88,6 +126,18 @@ Edit `~/.mobitru-cli/config.json` directly:
 }
 ```
 
+### Or via `config --set`
+
+```bash
+mobitru-mobile-cli config --set baseUrl=app.mobitru.com
+mobitru-mobile-cli config --set apiKey=mobitru_ak_...
+mobitru-mobile-cli config --set slug=your-workspace-slug
+```
+
+Repeatable; writes atomically to `~/.mobitru-cli/config.json` with mode
+`0600`. Allowed keys: `baseUrl`, `browserHubBaseUrl`, `apiKey`, `slug`,
+`wid`.
+
 ### Inspect the merged view
 
 ```bash
@@ -99,8 +149,8 @@ API key redacted) so you can verify what the next `device-use` will use.
 
 ## Sequential calls only
 
-Commands are serialized — only one runs at a time. Parallel calls fail-fast
-with:
+Within a session, commands are serialized — only one runs at a time.
+Parallel calls to the same session fail-fast with:
 
 ```
 another command is in flight; CLI calls must be sequential
@@ -113,13 +163,16 @@ single device session anyway.
 ## Cleanup
 
 ```bash
-# Release the current device (graceful)
+# Release the current device but keep the daemon alive
 mobitru-mobile-cli device-release
 
-# Reset session state (releases the device first if held)
+# Stop the current session: release device + shut down daemon + remove session dir
 mobitru-mobile-cli stop
+
+# Stop every session at once (e.g. end of a CI job)
+mobitru-mobile-cli stop --all
 ```
 
 > ⚠️ **Always release when done.** A leaked booking holds the device until
-> the lease expires (default 180 minutes). `stop` at the end of any
-> workflow is the safe default.
+> the lease expires (default 180 minutes). `stop` (or `stop --all`) at the
+> end of any workflow is the safe default.