mobitru-mobile-cli 1.0.0-beta.0

package/skills/references/mobile-sessions.md

@@ -0,0 +1,125 @@
+# 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`.
+
+## Booking lifecycle
+
+```bash
+# Find devices available now for a platform
+mobitru-mobile-cli device-list android
+mobitru-mobile-cli device-list ios
+
+# Book a specific device by its serial (default lease: 180 minutes)
+mobitru-mobile-cli device-use <serial>
+mobitru-mobile-cli device-use <serial> --duration=30
+
+# Any number of interaction commands here…
+mobitru-mobile-cli snapshot
+mobitru-mobile-cli tap e3
+
+# Release the device — frees the cloud slot
+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
+
+The CLI holds exactly **one active booking at a time**. Trying to book a
+different device without releasing the current one fails:
+
+```
+device "<serial>" is currently in use. Run device-release first, then device-use <new-serial>.
+```
+
+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.
+
+## Cleanup window
+
+After `device-release`, the cloud puts the device through a cleanup phase —
+typically **30 to 60 seconds** during which the same serial returns
+`Failed to take device: 404` on `device-use`. Two options:
+
+- Wait, then retry the same serial.
+- Pick a different serial from `device-list` and book that one.
+
+The CLI is not stuck — the cloud is. Other devices remain bookable
+throughout.
+
+## Device locale
+
+Mobitru routes devices across regional data centers (e.g. EU, CIS). The
+device's locale follows the DC, so geolocated services may serve UI in the
+local language — a EU device commonly hits **Hungarian** Google consent
+dialogs, **German** Play Store strings, etc. Identify elements by
+accessibility label and rect from `snapshot` rather than expecting English
+text. The labels are still localized, but their structure (button vs link,
+EditText vs TextView) and position remain stable.
+
+## Credentials
+
+Credentials are read from `~/.mobitru-cli/config.json` first, then
+overridden by environment variables (env vars win). Three values are
+required for mobile: `baseUrl`, `apiKey`, `slug`.
+
+### Via environment variables
+
+```bash
+export DEVICE_FARM_BASE_URL=app.mobitru.com
+export DEVICE_FARM_API_KEY=mobitru_ak_...
+export DEVICE_FARM_SLUG=your-workspace-slug
+```
+
+### Or via the config file
+
+Edit `~/.mobitru-cli/config.json` directly:
+
+```json
+{
+  "baseUrl": "app.mobitru.com",
+  "apiKey": "mobitru_ak_...",
+  "slug": "your-workspace-slug"
+}
+```
+
+### Inspect the merged view
+
+```bash
+mobitru-mobile-cli config
+```
+
+Prints the resolved credentials (config file plus env overrides, with the
+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:
+
+```
+another command is in flight; CLI calls must be sequential
+```
+
+Serialize from the caller side. The cloud Appium server takes hundreds of
+milliseconds per command and is not designed for concurrent traffic from a
+single device session anyway.
+
+## Cleanup
+
+```bash
+# Release the current device (graceful)
+mobitru-mobile-cli device-release
+
+# Reset session state (releases the device first if held)
+mobitru-mobile-cli stop
+```
+
+> ⚠️ **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.