GMTool

GMTool is a command line tool that allows using every command of Genymotion and virtual devices to automate series of actions. GMTool can be started by running gmtool from a command prompt. This section lists and explains all commands available in GMTool. This section also explains error messages that can be returned.

Location

gmtool command line tool is located in the following path:

Windows

C:\Program Files\Genymobile\Genymotion\

macOS

/Applications/Genymotion.app/Contents/MacOS/

Linux

$HOME/genymotion/ or opt/genymotion/

General commands and options

The version command returns Genymotion Desktop version and revision number.

Global options are:

• --timeout/-t: Timeout duration in seconds. Available range is 0-3600.
• --verbose/-v: Verbose mode.
• --help/-h: Displays help on commandline options.

gmtool license

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

• info: Returns the license type, number of activated workstations and expiration date.
• <license_key>: Registers a license key or renews Genymotion Desktop activation.
• count: Returns the number of activated workstations with the registered license key.
• validity: Returns the number of days of validity remaining for the registered license key.

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 defining Genymotion Desktop settings. Options available within this group are:

• --email <email>: Account Email.
• --password <password>: Account Password.
• --license_server <on/off>: Use a company license server instead of Genymobile ones to activate the copy of Genymotion. Default is off.
• --license_server_address <url>: Url of the license server.
• --statistics <on/off>: Allows statistics to be send 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.

gmtool admin

The admin command group allows administrating virtual devices.

Basic commands

• start <device>: Starts the specified virtual device. Add the --coldboot option to force a complete boot cycle.
• stop <device>: Stops the specified virtual device.
• list: Lists all virtual devices. Available filter options are:
• --running: lists running virtual devices only.
• --off: lists stopped virtual devices only.

Start the virtual device named "My Phone":

List all the running virtual devices:

Advanced commands

• 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.
• stopall: Stops all virtual devices.
• factoryreset <device>: Restores the specified virtual device to factory state.
• delete <device>: Deletes the specified virtual device.
• clone <source> <target>: Duplicates the specified virtual device (source) to a new virtual device (target).
• templates: Lists all online and offline available virtual device templates and their basic properties.

> Warning: This command is deprecated. Please use hwprofiles and osimages commands instead.

• hwprofiles: List all available hardware profiles.
• osimages: List all available Android images.
• logzip <path>: Generates an archive of all Genymotion Desktop log files. 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.
• create <hwprofile> <osimage> <device>: Creates a virtual device from the specified hardware profile (hwprofile) and Android OS version (osimage). Available options are:
• --density <value>: Sets the screen density of the virtual device in pixels per inch. Available densities are: 120, 160, 213, 240, 260, 280, 300, 320, 340, 360, 400, 420, 440, 450, 480, 560 and 640.
• --width <value>: Sets the screen width of the virtual device.
• --height <value>: Sets the screen height of the virtual device.
• --virtualkeyboard <on/off>: Activates or deactivates the virtual keyboard.
• --navbar <on/off>: Displays or hides the Android navigation bar in the virtual device.
• --nbcpu <value>: Sets the number of processors used by the virtual device.
• --ram <value>: Sets the memory space allocated to the virtual device in MB.
• --network-mode <nat/bridge>: Sets the host network interface mode for the virtual device. Only available with VirtualBox hypervisor.
• --bridged-if <interface_name>: When network mode is bridge, sets the bridged interface for the virtual device. Only available with VirtualBox hypervisor.
• --sysprop <property>:<value>: Sets a build system property of the virtual device. Available properties are: MODEL, PRODUCT, MANUFACTURER, BOARD, BRAND, DEVICE, DISPLAY, SERIAL, TYPE, FINGERPRINT and TAGS. Values for each property are detailed at developer.android.com.
• --quickboot <on/off>: Set default for the use of a resume state. Only available with QEMU hypervisor!
• --root-access <on/off>: Set root access. Only applies to non-rooted Android versions
• edit <device>: Edits the specified virtual device settings. See the create subcommand for detailed options and values.

Examples

Create a device named "My Samsung Phone" with the Samsung Galaxy S10 profile, Android 11.0 and default settings:

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

Create a device named "My Custom Phone" with the Custom Phone profile, Android 11.0, 1440x2560 display resolution, 560dpi, 4 CPUs and 4GB in RAM:

gmtool admin create "Custom Phone" "Android 11.0" "My Custom Phone" \
--width 1440 --height 2560 --density 560 --nbcpu 4 --ram 4096

Change the "My Custom Phone" device display resolution to 728x1024 and 240dpi (hdpi):

gmtool admin edit "My Custom Phone" --width 728 --height 1024 --density hdpi

gmtool device

The device command group allows directly interacting with a virtual device.

Options available for each subcommand within this group are:

• -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 options -n or --all is mandatory.

• --all: Interacts with all running virtual devices.
• --start: Starts the virtual device specified by -n if not already started.

Commands available in the device command group are:

• logcatdump <file>: Copies the logcat output onto the specified destination file.

If a logcat dump file already exists, it will be overwritten.

• logcatclear: Empties the logcat content of a virtual device.
• push <source> <destination>: Uploads a file or directory from the host computer to the virtual device.

If no destination path is specified, the file or directory is stored in /sdcard/Downloads by default.

• pull <source> <destination>: Copies a file or directory from the virtual device to the host computer.

If a destination file already exists, it will be overwritten.

Use --all option to create a destination directory for each running virtual device.

• install <apk>: Installs an APK file on the virtual device.
• flash <archive>: Flashes a .zip archive into the specified virtual device.
• adbconnect: Connects the specified virtual device using the ADB tool.
• adbdisconnect: Disconnects the specified virtual device from the ADB tool.

Example

./gmtool device logcatdump ~/logcat-2021-12-02.txt
Writing logcat for Samsung Galaxy S8_1 into /home/user/logcat-2021-12-02.txt...

Error messages

The table below explains error codes returned by GMTool:

| Code | Meaning | |---|---| | 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 . | | 7 | Unable to 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. We refer to:

• {GENYMOTION_DIR} as the directory containing the Genymotion Desktop installer.
• {GMTOOL_DIR} as the directory containing the GMTool binary.
• {COMPLETION_DIR} as the directory containing the completion script.

Linux

• {GENYMOTION_DIR} is where you installed Genymotion Desktop (usually, $HOME/genymotion).

macOS

• {GENYMOTION_DIR} is /Applications/Genymotion.app.

Directory mapping

• {GMTOOL_DIR} is the same as {GENYMOTION_DIR}.
• {COMPLETION_DIR} is {GENYMOTION_DIR}/completion.

macOS directory mapping

• {GMTOOL_DIR} is {GENYMOTION_DIR}/Contents/MacOS.
• {COMPLETION_DIR} is {GENYMOTION_DIR}/Contents/Resources/completion.

Requirements

To take advantage of shell completion, add gmsaas binary path, {GMTOOL_DIR}, to $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. Using at least version 4.0 is recommended, especially if working 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 compinit:

fpath=({COMPLETION_DIR}/zsh $fpath)