gmsaas User Guide
Commands
The --help/-h option is suitable for every gmsaas command. It will provide you with all the supported commands, sub-commands, options, and a quick explanation of what they do.
Create a Hardware Profile
Hardware Profiles define virtual device hardware specifications. This includes screen resolution, form factor, and related settings.
gmsaas hwprofiles create <name> \
[--width INTEGER] \
[--height INTEGER] \
[--density INTEGER] \
[--form-factor PHONE|TABLET] \
[--navigation-bar]
Default output: JSON output
<hwprofile_uuid> is printed.
Example:
$ gmsaas hwprofiles create test
3aa57c4c-1372-4d82-8405-2ab668805b3c
{
"hwprofile": {
"uuid": "3aa57c4c-1372-4d82-8405-2ab668805b3c",
"name": "test",
"form_factor": "PHONE",
"cpu_count": 2,
"ram_size": 2048,
"data_disk_size": 16384,
"source": "a@b.c",
"display_settings": {
"hw_navigation_keys": true,
"displays": [
{
"width": 768,
"height": 1280,
"density": 320,
"screen": "768 x 1280 dpi 320"
}
]
}
},
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Get Hardware Profile details
Retrieve the details of a hardware profile by its UUID.
gmsaas hwprofiles get <hwprofile_uuid>
Default output: JSON output
The Hardware Profile is formatted as a table.
UUID NAME DISPLAY SOURCE
------------------------------------ -------- -------- --------
3aa57c4c-1372-4d82-8405-2ab668805b3c test 768 x 1280 a@b.c
{
"hwprofile": {
"uuid": "3aa57c4c-1372-4d82-8405-2ab668805b3c",
"name": "test",
"form_factor": "PHONE",
"cpu_count": 2,
"ram_size": 2048,
"data_disk_size": 16384,
"source": "a@b.c",
"display_settings": {
"hw_navigation_keys": true,
"displays": [
{
"width": 768,
"height": 1280,
"density": 320,
"screen": "768 x 1280 dpi 320"
}
]
}
},
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
List Hardware Profiles
List all hardware profiles.
gmsaas hwprofiles list
Default output: JSON output
The Hardware Profile list is formatted as a table.
UUID NAME DISPLAY SOURCE
------------------------------------ ------------- -------- -----
e104f058-b291-4764-8e0d-d9ff78a41192 Custom Phone 768 x 1280 genymotion
c65db329-511a-4c2a-9761-c7259649e8c7 Custom Tablet 1536 x 2048 genymotion
c6e1222c-993e-4bf2-840f-4795792f2143 Google Nexus 10 2560 x 1600 genymotion
{
"hwprofiles": [
{
"uuid": "e104f058-b291-4764-8e0d-d9ff78a41192",
"name": "Custom Phone",
"form_factor": "PHONE",
"cpu_count": 4,
"ram_size": 2048,
"data_disk_size": 8192,
"source": "genymotion",
"display_settings": {
"hw_navigation_keys": false,
"displays": [
{ "width": 768, "height": 1280, "density": 320, "screen": "768 x 1280 dpi 320" }
]
}
},
...
],
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Delete a Hardware Profile
Delete a hardware profile by UUID.
gmsaas hwprofiles delete <hwprofile_uuid>
Default output: JSON output
$ gmsaas hwprofiles delete a0d9acf6-08e8-400c-93a5-b44cc666506b
HwProfile 'a0d9acf6-08e8-400c-93a5-b44cc666506b' deleted successfully.
{
"hwprofile_uuid": "a0d9acf6-08e8-400c-93a5-b44cc666506b",
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Clone an Image
Images are virtual device Android OS disk images.
gmsaas osimages clone <base_osimage_uuid> <name>
Default output: JSON output
<osimage_uuid> is printed.
{
"osimage": {
"uuid": "6cb23b1a-f6c6-4c0d-90d7-60e184f7670f",
"name": "test",
"image_version": "3.0.2",
"android_version": "13.0",
"api_version": 33,
"architecture": "x86_64",
"source": "a@b.c",
"status": "READY",
"is_beta": false
},
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Get Image details
Retrieve details for a specific image.
gmsaas osimages get <osimage_uuid>
Default output: JSON output
Image is printed as a table.
{
"osimage": {
"uuid": "6cb23b1a-f6c6-4c0d-90d7-60e184f7670f",
"name": "test",
"android_version": "13",
"api_version": 33,
"architecture": "x86_64",
"source": "a@b.c",
"status": "READY",
"is_beta": false
},
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
List Images
List all images.
gmsaas osimages list
Default output: JSON output
Image list formatted as a table.
{
"osimages": [
{
"uuid": "0c15f956-55a9-4622-a2a0-cfaaedd3a0e9",
"name": "Android 13.0",
"image_version": "3.0.2",
"android_version": "13.0",
"api_version": 33,
"architecture": "x86_64",
"source": "genymotion",
"status": "READY",
"is_beta": false
},
...
],
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Get Image details (detailed list)
The image detail table includes UUID, Name, Android Version, API Version, Architecture, Source. The exact layout is shown for multiple images in the example above.
Delete an Image
Delete an image by UUID.
gmsaas osimages delete <osimage_uuid>
Default output: JSON output
{
"osimage_uuid": "<uuid>",
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Create a Recipe
Recipes are a combination of Hardware Profiles and Images.
gmsaas recipes create <hwprofile_uuid> <osimage_uuid> <name>
Default output: JSON output
$ gmsaas recipes create e104f058-b291-4764-8e0d-d9ff78a41192 0c15f956-55a9-4622-a2a0-cfaaedd3a0e9 test
{
"recipe": {
"uuid": "6bc927c9-777e-471c-af5b-6dc737f3aaef",
"name": "test",
"source": "a@b.c",
"hwprofile": { "uuid": "...", "name": "Custom Phone", "form_factor": "PHONE", "cpu_count": 4, "ram_size": 2048, "source": "genymotion" },
"osimage": { "uuid": "...", "name": "Android 13.0", "android_version": "13.0", "source": "genymotion" }
},
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Get Recipe details
Retrieve details for a recipe.
gmsaas recipes get <recipe_uuid>
Default output: JSON output
Recipe is printed as a table.
{
"recipe": {
"uuid": "6bc927c9-777e-471c-af5b-6dc737f3aaef",
"name": "test",
"android_version": "13.0",
"screen_width": 768,
"screen_height": 1280,
"screen_density": 320,
"screen": "768 x 1280 dpi 320",
"source": "a@b.c",
"hwprofile": {
"uuid": "e104f058-b291-4764-8e0d-d9ff78a41192",
"name": "Custom Phone",
"form_factor": "PHONE",
"cpu_count": 4,
"ram_size": 2048,
"source": "genymotion",
"display_settings": { "hw_navigation_keys": false, "displays": [{ "width": 768, "height": 1280, "density": 320, "screen": "768 x 1280 dpi 320" }] }
},
"osimage": {
"uuid": "0c15f956-55a9-4622-a2a0-cfaaedd3a0e9",
"name": "Android 13.0",
"android_version": "13.0",
"api_version": 33,
"architecture": "x86_64",
"source": "genymotion",
"status": "READY",
"is_beta": false
}
},
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
List Recipes
List all recipes.
gmsaas recipes list
Default output: JSON output
Recipe list formatted as a table.
{
"recipes": [
{
"uuid": "e104f058-b291-4764-8e0d-d9ff78a41192",
"name": "Custom Phone",
"android_version": "11.0",
"screen_width": 768,
"screen_height": 1280,
"screen_density": 320,
"screen": "768 x 1280 dpi 320",
"source": "genymotion",
"hwprofile": { "uuid": "...", "name": "Custom Phone" },
"osimage": { "uuid": "...", "name": "Android 11.0" }
},
...
],
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
List Recipes (alternative)
Alternative formatting example for listing.
{
"recipes": [
{
"uuid": "e104f058-b291-4764-8e0d-d9ff78a41192",
"name": "Custom Phone",
"android_version": "11.0",
"screen_width": 768,
"screen_height": 1280,
"screen_density": 320,
"source": "genymotion",
"hwprofile": { "uuid": "...", "name": "Custom Phone" }
},
...
],
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Delete a Recipe
Delete a recipe.
gmsaas recipes delete <recipe_uuid> [--delete-osimage] [--delete-hwprofile]
Default output: JSON output
{
"recipe_uuid": "<uuid>",
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
{
"recipe_uuid": "6bc927c9-777e-471c-af5b-6dc737f3aaef",
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Start an Instance
Create and start an instance from a recipe.
gmsaas instances start <recipe_uuid> <name> [--no-wait] [--max-run-duration INTEGER]
A warning is shown about using the instance UUID to refer to an instance when issuing commands.
Default output: JSON output
<instance_uuid> is printed.
{
"instance": {
"uuid": "62ec330e-47d2-4a6b-939f-122718505329",
"name": "test",
"created_at": "2021-05-29T11:54:35.000Z",
"max_run_duration": 1440,
"max_inactivity_duration": 0,
"state": "ONLINE",
"adbtunnel_state": "CONNECTED",
"adb_serial": "localhost:39745",
"adb_serial_port": 39745,
"recipe": {
"uuid": "b9cf7b2c-4d11-4777-97c7-29d3b5c68d59",
"name": "Samsung Galaxy S8",
"android_version": "8.0",
"screen_width": 1440,
"screen_height": 2960,
"screen_density": 480,
"screen": "1440 x 2960 dpi 480",
"source": "genymotion",
"hwprofile": { "uuid": "...", "name": "Samsung Galaxy S8" },
"osimage": { "uuid": "...", "name": "Android 8.0 (Oreo)" }
}
},
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Get Instance details
Display details for a running instance.
gmsaas instances get <instance_uuid>
Default output: JSON output
Instance information formatted as a table. This also provides the ADB serial used if the instance is connected to ADB.
{
"instance": {
"uuid": "5a4d74e6-e6b2-4dd3-8d6c-1eea275b5ea7",
"name": "test1",
"created_at": "2021-05-29T11:54:35.000Z",
"max_run_duration": 1440,
"max_inactivity_duration": 0,
"state": "ONLINE",
"adbtunnel_state": "CONNECTED",
"adb_serial": "localhost:39745",
"adb_serial_port": 39745,
"recipe": {
"uuid": "b9cf7b2c-4d11-4777-97c7-29d3b5c68d59",
"name": "Samsung Galaxy S8",
"android_version": "8.0",
"screen_width": 1440,
"screen_height": 2960,
"screen_density": 480,
"screen": "1440 x 2960 dpi 480",
"source": "genymotion"
}
},
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
List Instances
List all instances.
gmsaas instances list
Default output: JSON output
Instances list formatted as a table. This also provides the ADB serial used if the instance is connected to ADB.
{
"instances": [
{
"uuid": "5a4d74e6-e6b2-4dd3-8d6c-1eea275b5ea7",
"name": "test1",
"created_at": "2021-05-29T11:54:35.000Z",
"max_run_duration": 1440,
"max_inactivity_duration": 0,
"state": "ONLINE",
"adbtunnel_state": "CONNECTED",
"adb_serial": "localhost:39745",
"adb_serial_port": 39745,
"recipe": {
"uuid": "b9cf7b2c-4d11-4777-97c7-29d3b5c68d59",
"name": "Samsung Galaxy S8",
"android_version": "8.0",
"screen_width": 1440,
"screen_height": 2960,
"screen_density": 480,
"screen": "1440 x 2960 dpi 480",
"source": "genymotion"
}
},
...
],
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Connect an Instance to ADB
Connect a running instance to ADB.
gmsaas instances adbconnect [--adb-serial-port PORT] <instance_uuid>
Default output: JSON output
<adb_serial> (URL:port) on which ADB is connected is printed.
{
"instance": {
"uuid": "099bd927-a0b9-4ff0-b4bc-d474175945b7",
"name": "test3",
"created_at": "2021-03-29T11:54:35.000Z",
"max_run_duration": 1440,
"max_inactivity_duration": 0,
"state": "ONLINE",
"adbtunnel_state": "CONNECTED",
"adb_serial": "localhost:37007",
"adb_serial_port": 37007,
"recipe": {
"uuid": "b9cf7b2c-4d11-4777-97c7-29d3b5c68d59",
"name": "Samsung Galaxy S8",
"android_version": "8.0",
"screen_width": 1440,
"screen_height": 2960,
"screen_density": 480,
"screen": "1440 x 2960 dpi 480",
"source": "genymotion"
}
},
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Save an Instance
Save changes to an instance manually.
gmsaas instances save <instance_uuid>
Default output: JSON output
Instance '<instance_uuid>' has been saved successfully.
{
"instance_uuid": "<instance_uuid>",
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Save As an Instance
Save an existing running instance as a new custom recipe and image.
gmsaas instances saveas <instance_uuid> --osimage-name <image_name> --recipe-name <recipe_name>
Default output: JSON output
Instance '<instance_uuid>' has been saved successfully.
Recipe '<recipe_name>' and Image '<image_name>' have been created.
{
"instance_uuid": "<instance_uuid>",
"recipe_name": "<recipe_name>",
"osimage_name": "<image_name>",
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Stop an Instance
Stops a running instance.
> Warning: Instances launched with gmsaas will not stop until this command is issued, or it is stopped from the Web interface. Credits accrue while running.
gmsaas instances stop [--no-wait] <instance_uuid>
Default output: JSON output
No output.
{
"instance": { "uuid": "<instance_uuid>", "exit_code": 0, "exit_code_desc": "NO_ERROR" }
}
Display Instances (gmsaas portal)
Generate a URL to display the instances in the gmsaas portal.
gmsaas instances display [<instance_uuid>, ...]
Default output: JSON output
"url": "<hidden>",
"message": "Generated URL copied in your clipboard, paste it in your web browser.",
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
{
"url": "<hidden>",
"message": "Generated URL copied in your clipboard, paste it in your web browser.",
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Setting Up and Tearing Down ADB
The gmsaas tool uses an internal component called ADB Tunnel. This enables secure ADB connections to instances. If you see failures with adbconnect, consider using the adb start and adb stop commands to manage ADB connections more reliably.
Recommended flow for test runs
1. Install gmsaas
2. Configure the SDK path: gmsaas config set android-sdk-path <path>
3. Authenticate using your API token: gmsaas auth token <token>
4. Start the ADB stack before running tests: gmsaas adb start
5. Run your test suite
6. Stop the ADB stack after tests complete: gmsaas adb stop
7. Unauthenticate when finished: gmsaas auth reset
This workflow helps prevent connectivity issues during intensive usage.
Start ADB
gmsaas adb start
Default output JSON output
{
"issues": [],
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Stop ADB
gmsaas adb stop
Default output JSON output
{
"issues": [],
"exit_code": 0,
"exit_code_desc": "NO_ERROR"
}
Back to top
[END OF CONTENT]