GMTool - Desktop User Guide

Source:

Published:

Keywords: GMTool, Genymotion, license, config, admin, device, autocompletion, bash completion, zsh completion, error messages

Document ID: https://docs.genymotion.com/desktop/06_GMTool#split1

GMTool

GMTool is a command line tool allowing you to use every command of Genymotion and virtual devices, in order to automate series of actions. It can be started by running gmtool from a command prompt.

This section lists and explains all commands available in GMTool, as well as error messages that can be returned.

Location

gmtool command line tool is located in the following path:

General commands and options

The version command returns Genymotion Desktop version and revision number:

Example 

$ ./gmtool
version
Version
: 3.3.2
Revision
: 20221202-872c52ef45

Global options are:

| Short | Description | | ----- | ----------- | | -t, --timeout <value> | Timeout duration in seconds. Available range is 0-3600. | | -v, --verbose | Verbose mode. | | -h, --help | Displays help on command line options. |

---

gmtool license

The license command group allows you to perform actions related to the Genymotion license. Commands available within this group are:

Example 

gmtool license 0123456789
Registers the license key 0123456789 and authenticates the user with the email and password provided by the config command.

---

gmtool config

The config command group allows you to define Genymotion Desktop settings. Options available within this group are:

| Option | Description | | ------ | ----------- | | --email <email> | Account Email. | | --password <password> | Account Password. | | --license_server <on|off> | Use a company license server instead of Genymobile ones to activate your copy of Genymotion. Default is off. | | --license_server_address <url> | Url of the license server. | | --statistics <on|off> | Allows statistics to be sent anonymously. | | --virtual_device_path <path> | Path to where the devices are deployed. | | --use_custom_sdk <on|off> | Enable or disable the use of a specified Android SDK. | | --sdk_path <path> | Path to the Android SDK. | | --screen_capture_path <path> | Screen capture destination folder. | | --proxy <on|off> | Enable or disable the use of a proxy. | | --proxy_type <http|socks5> | Type of proxy: http or socks5. | | --proxy_address <url> | Proxy URL. | | --proxy_port <port> | Proxy port. | | --proxy_auth <on|off> | Enable or disable proxy authentication. | | --proxy_username <username> | Proxy authentication username. | | --proxy_password <password> | Proxy authentication password. | | --trusted_hosts <host, ...> | Trusted hosts for which SSL errors will be ignored. | | --shared_clipboard <on|off> | Enable or disable shared clipboard. | | --hypervisor <virtualbox|qemu> | Select which hypervisor to use: virtualbox or qemu. | | --root-access <on|off> | Set root access. Only applies to non-rooted Android versions. |

---

gmtool admin

The admin command group allows you to administrate virtual devices.

Basic commands

| Command | Description | | ------- | ----------- | | start <device> | Starts the specified virtual device. | | --coldboot | Forces a complete boot cycle. | | stop <device> | Stops the specified virtual device. | | list | Lists all virtual devices. | | --running | Lists running virtual devices only. | | --off | Lists turned off virtual devices only. | | stopall | Stops all virtual devices. |

Advanced commands

| Command | Description | | ------- | ----------- | | details <device> | Returns the properties of one or more specified virtual devices. If no virtual device is specified, returns the properties of all virtual devices. | | delete <device> | Deletes the specified virtual device using the device name or the device uuid. | | clone <device> <new_device> | Clones a device using a target device name or uuid. | | templates | deprecated — Lists all online and offline available virtual device templates and their basic properties. This command is deprecated. Please use hwprofiles and osimages commands instead. | | hwprofiles | List all available hardware profiles. | | osimages | List all available Android OS images. | | edit <device> | Edits the specified virtual device settings. See create subcommand for detailed options and values. | | factoryreset <device> | Restores the specified virtual device to factory state. | | logzip <path> | Creates an archive of one or all current devices. Specify path to generate the logs in a specific path. Add option -n | --name <device> <path> to generate a log archive of the specified virtual device, at the defined location. If an archive file already exists, it will be overwritten. |

Examples

gmtool admin create "Samsung Galaxy S10" "Android 11.0" "My Samsung Phone"

gmtool admin create "Custom Phone" "Android 11.0" "My Custom Phone" \

--width 1440 --height 2560 --density 560 --nbcpu 4 --ram 4096

gmtool admin edit "My Custom Phone" \

--width 728 --height 1024 --density hdpi

---

gmtool device

The device command group allows you to directly interact with a virtual device.

Options for subcommands

| Option | Description |

| ------ | ----------- |

| -n|--name <device> | Interacts with the specified virtual device. If not specified, interacts with the running virtual device. If more than one virtual device is running, the use of -n or --all is mandatory. |

| --all | Interacts with all running virtual devices. |

Subcommands

Example 

$ ./gmtool device logcatdump ~/logcat-2021-12-02.txt

---

Error messages

The table below explains error codes returned by GMTool:

| Code | Message | |-----|---------| | 1 | The command does not exist. | | 2 | A wrong parameter value has been entered. | | 3 | The command has failed. | | 4 | The virtualization engine does not respond. | | 5 | The specified virtual device could not be found. | | 6 | Unable to sign in. | | 7 | Unable to register the license key. | | 8 | Unable to activate the license. | | 9 | The license has not been activated. | | 10 | The license key is invalid. | | 11 | The command has missing arguments. | | 12 | Unable to stop the virtual device. | | 13 | Unable to start the virtual device. | | 14 | This command can only run with Indie and Business licenses. |

---

Autocompletion

To be more productive with GMTool, you can install a completion script for your shell. We provide completion scripts for Bash and Zsh shells.

In this section, we explain how to install those scripts and we refer to the directory containing the Genymotion Desktop installer as {GENYMOTION_DIR}, the directory containing the GMTool binary as {GMTOOL_DIR} and the directory containing the completion script as {COMPLETION_DIR}:

{GENYMOTION_DIR} is where you installed Genymotion Desktop (usually, $HOME/genymotion) {GMTOOL_DIR} is the same as {GENYMOTION_DIR} {COMPLETION_DIR} is {GENYMOTION_DIR}/completion

{GENYMOTION_DIR} is /Applications/Genymotion.app {GMTOOL_DIR} is {GENYMOTION_DIR}/Contents/MacOS {COMPLETION_DIR} is {GENYMOTION_DIR}/Contents/Resources/completion

Requirements

To take advantage of shell completion, add GMTOOL_DIR to your PATH. If you use VirtualBox hypervisor, you will also need to add your VirtualBox installation directory to PATH.

Installing the Bash completion script

To install the Bash completion script, add this line at the end of your ~/.bash_profile file: 

. {COMPLETION_DIR}/bash/gmtool.bash
Completion works with Bash 3.2 or later, but we recommend using at least version 4.0, especially if you work with file names containing spaces.

Installing the Zsh completion script

To install the Zsh completion script, open your ~/.zshrc and add this line before the call to autocompinit: 

fpath=({COMPLETION_DIR}/zsh $fpath)

Back to top

---

Example blocks

Example blocks throughout the GMTool documentation illustrate common usage and formatting. Refer to the original page for full context and additional examples.