# 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.

# General commands

The following commands return information related to the use of GMTool:

Command Result
version Returns Genymotion Desktop version and revision number.
help Displays the help for the entire tool, for a command group or for a specific command.

Example:

The command gmtool admin create help or gmtool help admin create displays all commands and options available for the admin create command:

$ gmtool help admin create
admin create <TEMPLATE_NAME> <VIRTUAL_DEVICE_NAME> [--density=<SCREEN_DENSITY>] [--width=<SCREEN_WIDTH>] [--height=<SCREEN_HEIGHT>] [--virtualkeyboard=<on|off>] [--navbar=<on|off>] [--nbcpu=<NUMBER_OF_CPUs>] [--ram=<RAM_IN_MB>] [--network-mode=<nat|bridge>] [--bridged-if=<BRIDGED_INTERFACE>] [--sysprop=<PROPERTY:VALUE>] [--sysprop=<PROPERTY:VALUE>]...

# Command groups

Some commands are contained within a group, which allows you to interact on a given scope. Command groups are:

# License License required

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

Command Result
info Returns the license type, number of activated workstations and expiration date.
register {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.

Example:

The command gmtool license register 0123456789 registers the license key "0123456789" and authenticates the user with the username and password given previously with the config command.

# Config License required

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

Command Result
reset Restores default settings.
clearcache Removes temporary and downloaded files.
signout Signs out the user and removes the license.
print Returns values of the specified configuration options.
statistics=on|off Allows or prevents Genymotion Desktop to collect usage statistics.
username={USERNAME} Sets the user to authenticate.
password={PASSWORD} Sets the password to associate with the username.
store_credentials=on|off Remembers credentials or not.
license_server=on|off Activates or deactivates the use of a license server.
license_server_address={SERVER_ADDRESS} Sets the license server address.
proxy=on|off Activates or deactivates the use of a proxy.
proxy_address={PROXY_ADDRESS} Sets the proxy address.
proxy_port={PROXY_PORT} Sets the proxy port.
proxy_authentication=on|off Activates or deactivates proxy authentication.
proxy_username={PROXY_USERNAME} Sets the username to be used for proxy authentication.
proxy_password={PROXY_PASSWORD} Sets the password to be used for proxy authentication.
virtual_device_path={VIRTUAL_DEVICE_PATH} Sets the path to the virtual device directory.
sdk_path={SDK_PATH} Sets the path to the custom Android SDK directory.
use_custom_sdk=on|off Activates or deactivates the use of the custom Android SDK.
screen_capture_path={SCREEN_CAPTURE_PATH} Sets the path to the screen capture directory.
shared_clipboard=on|off Anable/disable virtual devices clipboard sharing with OS.

# Admin

The admin command group allows you to administrate virtual devices.

Important

Only the list, start and stop commands from the admin group are available with Genymotion Desktop free version.

Commands available within this group are:

templates

Lists all online and offline available virtual device templates and their basic properties (name, screen size and Android version). Options available for this command are:

  • --full: displays all properties of the virtual device templates (name, UUID, description, Android version, API level, Genymotion Desktop version, screen width, height, density and DPI, number of CPUs, RAM, internal storage, telephony, Android navigation bar visibility, virtual keyboard).
  • -f|--force-refresh: forces a refresh of the template list from the server. By default, the template list is stored locally to avoid too many server requests.

create {TEMPLATE_NAME} | {TEMPLATE_UUID} {VIRTUAL_DEVICE_NAME}

Creates a virtual device from the specified template.

Warning

If some shared virtual devices have the same name as other templates, you must specify the template UUID instead of the template name. You can retrieve the UUID using gmtool admin templates --full

The default template configuration can be overridden by specifying optional arguments. Options available for this command are:

  • --density={SCREEN_DENSITY}: sets the screen density of the virtual device. The value must be the density in pixels per inch or the name of the corresponding bucket, as shown in the table below.

    Density bucket name Pixels per inch
    ldpi 120
    mdpi 160
    tvdpi 213
    hdpi 240
    xhdpi 320
    420dpi 420
    xxhdpi 480
    560dpi 560
    xxxhdpi 640
  • --width={SCREEN_WIDTH}: sets the screen width of the virtual device.

  • --height={SCREEN_HEIGHT}: 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={NUMBER_OF_CPUs}: sets the number of processors used by the virtual device.

  • --ram={RAM_IN_MB}: 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.

  • --bridged-if={BRIDGED_INTERFACE}: when network mode is bridge, sets the bridged interface for the virtual device.

  • --sysprop={PROPERTY:VALUE}: sets one build system property of the virtual device. Available properties are: MODEL, PRODUCT, MANUFACTURER, BOARD, BRAND, DEVICE, DISPLAY, SERIAL, TYPE, FINGERPRINT, TAGS. You can set multiple system properties. Values of each property are detailed in developer.android.com (opens new window).


edit {VIRTUAL_DEVICE_NAME}

Edits the specified virtual device with optional arguments. Options available for this command are:

  • --density={SCREEN_DENSITY}: sets the screen density of the virtual device. For more information about density values, please refer to table Density values Table in the create command details above.
  • --width={SCREEN_WIDTH}: sets the screen width of the virtual device.
  • --height={SCREEN_HEIGHT}: 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={NUMBER_OF_CPUs}: sets the number of processors used by the virtual device.
  • --ram={RAM_IN_MB}: 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.
  • --bridged-if={BRIDGED_INTERFACE}: when network mode is bridge, sets the bridged interface for the virtual device.
  • --sysprop={PROPERTY:VALUE}: sets one build system property of the virtual device. Available properties are: MODEL, PRODUCT, MANUFACTURER, BOARD, BRAND, DEVICE, DISPLAY, SERIAL, TYPE, FINGERPRINT, TAGS. You can set multiple system properties. Values of each property are detailed in developer.android.com (opens new window).

delete {VIRTUAL_DEVICE_NAME}

Deletes the specified virtual device.


clone {ORIGINAL_VIRTUAL_DEVICE_NAME} {NEW_VIRTUAL_DEVICE_NAME}

Duplicates the specified original virtual device to a new virtual device.


list

Lists all virtual devices. Options available for this command are:

  • --running: lists running virtual devices.
  • --off: lists turned off virtual devices.

details {VIRTUAL_DEVICE_NAME_1} {VIRTUAL_DEVICE_NAME_2}...

Returns the properties of one or more specified virtual devices. If no virtual device is specified, returns the properties of all virtual devices.


start {VIRTUAL_DEVICE_NAME}

Starts the specified virtual device.


stop {VIRTUAL_DEVICE_NAME}

Stops the specified virtual device.


stopall

Stops all virtual devices.


factoryreset {VIRTUAL_DEVICE_NAME}

Restores the specified virtual device to factory state.


logzip

Generates an archive of all Genymotion Desktop log files. Option -n|--name <VIRTUAL_DEVICE_NAME> [LOG_ARCHIVE_PATH] generates a log archive of the specified virtual device, at the defined location.

Important

If an archive file already exists, it will be overwritten.

# Device License required

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

Options available within this group are:

Option Result
-n|--name {VIRTUAL_DEVICE_NAME} 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:

Command Result
logcatdump {DESTINATION_FILE_PATH} 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_PATH} {DESTINATION_DIRECTORY_PATH} Sends a file or directory from the host computer to the virtual device.
If no destination directory is specified, the file or directory is stored by default in /sdcard/Downloads.
pull {SOURCE_PATH} {DESTINATION_DIRECTORY_PATH} Copies a file or directory from the virtual device to the host computer. If combined with option --all, destination directories are created for each running virtual device.
If a destination file already exists, it will be overwritten.
install {APK_FILE_PATH} Installs an application using its APK file on the virtual device.
flash {ARCHIVE_PATH} Installs the archive content 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.

# 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}.

# Requirements

To take advantage of shell completion, the gmtool binary and the vboxmanage binary (provided by VirtualBox) must be in your PATH.

  • For gmtool, make sure you add {GMTOOL_DIR} to $PATH.
  • For vboxmanage, 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

Note

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 compinit:

fpath=({COMPLETION_DIR}/zsh $fpath)