gmsaas CLI Runbook — AI Assistant Guide

Prerequisites Check

# Step 1: Verify gmsaas is installed
$ which gmsaas || echo "NOT INSTALLED"

# If not installed:
$ pip3 install gmsaas
# On PEP 668 systems (Ubuntu 24.04+, recent macOS Homebrew Python) you may see:
#   error: externally-managed-environment
# Fix: install with --user, --break-system-packages, or use a virtualenv:
$ pip3 install --user gmsaas
# OR:
$ pip3 install gmsaas --break-system-packages

# Step 2: Verify authentication and configuration
$ gmsaas doctor
# Exit code 0 = ready. Non-zero = needs configuration.

# If Android SDK path is needed:
$ gmsaas config set android-sdk-path /path/to/android/sdk

# Optional: set JSON as default output
$ gmsaas config set output-format json

# Linux / macOS:
$ export GENYMOTION_API_TOKEN="your_token_here"

# Windows (PowerShell):
> $env:GENYMOTION_API_TOKEN = "your_token_here"

Workflow 1: Start an Android Virtual Device

1 List available recipes

$ gmsaas --format json recipes list

Returns a JSON object with a "recipes" array:

// Response structure:
{
  "recipes": [
    {
      "uuid": "3990323a-1e9a-...",      // Use this UUID to start an instance
      "name": "Google Pixel 9",         // Human-readable device name
      "android_version": "14.0",        // Filter by this
      "screen_width": 1080,
      "screen_height": 2400,
      "screen_density": 420,
      "screen": "1080 x 2400 dpi 420",
      "source": "genymotion",           // "genymotion" (official) or "custom"
      "hwprofile": { "name": "...", "cpu_count": 8, "ram_size": 8192, ... },
      "osimage": { "android_version": "14.0", "architecture": "x86_64", ... }
    },
    ...
  ]
}

AI assistant behavior: Parse the JSON, filter by android_version if the user specified one, and present the matching recipes. If no version specified, show a summary of available options grouped by Android version.

Filtering by name: gmsaas --format json recipes list --name "Pixel"

Filtering by source: gmsaas --format json recipes list --source official

2 Start the instance

$ gmsaas --format json instances start <recipe_uuid> "device-name"

Returns:

{
  "uuid": "inst-5678-...",          // Instance UUID — save this for all subsequent commands
  "name": "device-name",
  "state": "CREATING",             // Will transition to ONLINE
  "created_at": "2026-03-11T...",
  "adb_serial": "localhost:null",  // Not connected yet
  "recipe": { ... }
}

Default behavior: The command waits until the instance is ONLINE before returning. Use --no-wait to return immediately.

Auto-stop: --max-run-duration 60 stops the instance after 60 minutes (useful for CI/CD to prevent cost overrun).

# Poll up to 10 times (≈5 minutes total)
$ gmsaas --format json instances get <instance_uuid>
# Read the "state" field:
#   ONLINE  → proceed to step 3
#   BOOTING → sleep 30s, retry (announce progress to the user: "attempt N/10")
#   ERROR / DELETING / unknown → stop, report to user, link to https://cloud.geny.io/instances

# If still not ONLINE after 10 attempts (~5 min):
# Do NOT proceed to adbconnect. Inform the user and point to the cloud dashboard.

3 Connect ADB

$ gmsaas --format json instances adbconnect <instance_uuid>
// Returns: { "adb_serial": "localhost:PORT" }

# ALWAYS verify the connection — adbconnect exit code 0 does not guarantee ADB sees it:
$ adb devices
List of devices attached
localhost:PORT    device

# If the list is empty, the local ADB daemon may not be running:
$ gmsaas adb start
$ adb devices   # retry

# If still empty after that, the Android SDK path is likely misconfigured:
$ gmsaas doctor

The adb_serial value (e.g., localhost:6555) is the ADB address for all subsequent adb commands.

4 Use the device

# Install an APK
$ adb -s localhost:PORT install path/to/app.apk

# Run instrumented tests
$ adb -s localhost:PORT shell am instrument -w com.example.test/androidx.test.runner.AndroidJUnitRunner

# Take a screenshot
$ adb -s localhost:PORT exec-out screencap -p > screenshot.png

# Open a shell
$ adb -s localhost:PORT shell

# Push a file to the device
$ adb -s localhost:PORT push local-file.txt /sdcard/

5 Stop the instance

$ gmsaas instances stop <instance_uuid>
# Waits for full shutdown. Use --no-wait to return immediately.

# Verify the instance actually stopped:
$ gmsaas instances list
# Expected: the instance no longer appears. If it still shows RUNNING/BOOTING,
# retry the stop command or point the user to https://cloud.geny.io/instances

$ gmsaas instances list --quiet | xargs -I {} gmsaas instances stop {}

Workflow 2: CI/CD Pipeline Integration

Complete CI Script Template

#!/bin/bash
# Genymotion SaaS CI/CD script
# Requires: GENYMOTION_API_TOKEN env var set in CI secrets

set -euo pipefail

# Install gmsaas
pip3 install gmsaas

# Authenticate via environment variable (no interactive login needed)
export GENYMOTION_API_TOKEN="$GENYMOTION_API_TOKEN"

# Configure Android SDK
gmsaas config set android-sdk-path "$ANDROID_HOME"

# Start instance with auto-stop safety (30 min max)
RECIPE_UUID="abcd1234-..."  # Set to your recipe UUID
INSTANCE_UUID=$(gmsaas --format json instances start "$RECIPE_UUID" "ci-test-$(date +%s)" \
  --max-run-duration 30 | python3 -c "import sys,json; print(json.load(sys.stdin)['uuid'])")

# Connect ADB
ADB_SERIAL=$(gmsaas --format json instances adbconnect "$INSTANCE_UUID" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['adb_serial'])")

# Wait for device to be fully booted
adb -s "$ADB_SERIAL" wait-for-device
adb -s "$ADB_SERIAL" shell getprop sys.boot_completed | grep -q 1

# Run your tests
adb -s "$ADB_SERIAL" install app.apk
adb -s "$ADB_SERIAL" shell am instrument -w com.example.test/runner

# Cleanup (always runs)
trap "gmsaas instances stop $INSTANCE_UUID --no-wait" EXIT

Key CI/CD Notes

• Authentication: Set GENYMOTION_API_TOKEN as a CI secret — no interactive login
• Safety: Always use --max-run-duration to prevent orphaned instances
• Cleanup: Use trap with --no-wait so cleanup runs even if tests fail
• Recipe UUID: Find it once with gmsaas --format json recipes list, then hardcode in CI config

Workflow 3: Custom Device Configuration

# Step 1: Create a custom hardware profile
$ gmsaas --format json hwprofiles create "custom-tablet" \
    --width 1920 --height 1200 --density 240 \
    --form-factor TABLET --navigation-bar
// Returns: hwprofile UUID

# Step 2: List available OS images
$ gmsaas --format json osimages list
// Each image: { "uuid": "...", "android_version": "14.0", "architecture": "x86_64" }

# Step 3: Create recipe combining hardware + OS
$ gmsaas --format json recipes create <hwprofile_uuid> <osimage_uuid> "my-custom-recipe"
// Returns: recipe UUID

# Step 4: Start instance from custom recipe
$ gmsaas --format json instances start <recipe_uuid> "custom-device"

Workflow 4: Monitor and Manage Running Instances

# List all instances with full details
$ gmsaas --format json instances list

# Get details for a specific instance
$ gmsaas --format json instances get <instance_uuid>

# Just get instance UUIDs (useful for scripting)
$ gmsaas instances list --quiet
// Returns one UUID per line

# Stop a specific instance
$ gmsaas instances stop <instance_uuid>

# Stop ALL running instances (useful for cleanup)
$ gmsaas instances list --quiet | xargs -I {} gmsaas instances stop {}

# Save instance state (preserves installed apps, data)
$ gmsaas instances save <instance_uuid>

# Save as a new reusable recipe
$ gmsaas instances saveas <instance_uuid> \
    --osimage-name "my-configured-image" \
    --recipe-name "my-configured-recipe"

Workflow 5: Embed a SaaS Instance in a Web Page (device-web-player)

Genymotion exposes a JavaScript SDK — device-web-player — that streams a running SaaS instance into an HTML page via WebRTC. You need two things from the Genymotion API: a WebRTC URL and a short-lived access token.

1 Confirm an instance is running

$ gmsaas instances list
# Need an instance in state ONLINE. If none, start one first (Workflow 1).

2 Fetch the WebRTC URL and access token (user runs these)

Give the user these commands to run in their own shell. Both require GENYMOTION_API_TOKEN to already be exported.

# 1. Get the WebRTC websocket URL for the instance
$ curl -s -H "x-api-token: $GENYMOTION_API_TOKEN" \
     "https://api.geny.io/cloud/v1/instances/<instance_uuid>" \
     | jq -r '.webrtc_url'
wss://...cloud.geny.io/...

# 2. Get a short-lived access token for that instance
$ curl -s -X POST -H "x-api-token: $GENYMOTION_API_TOKEN" \
     "https://api.geny.io/cloud/v1/instances/<instance_uuid>/accesstoken" \
     | jq -r '.token'

3 Drop values into the HTML template

The official device-web-player template is published under MIT licence in Genymotion's skill repo: templates/device-web-player.html. Copy it locally and replace:

• REPLACE_WITH_WSS_ADDRESS → the webrtc_url from step 2
• REPLACE_WITH_ACCESS_TOKEN → the token from step 2

4 Serve over HTTP (required for WebRTC)

# WebRTC will NOT work from file:// — you must serve over HTTP.
$ python3 -m http.server 8080
# Then open http://localhost:8080/device-web-player.html

Complete Command Reference

Error Handling Patterns

Global Options