Skip to content

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:

C:\Program Files\Genymobile\Genymotion\
$HOME/genymotion/

or

opt/genymotion/

/Applications/Genymotion.app/Contents/MacOS/

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:

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

Example

$ ./gmtool admin -h
Usage: ./gmtool [options] admin <action>
admin

This command provides a set of actions to create, delete or manage a device.

Each action can be called with --help for further details.

Actions:
create                  Lists all virtual devices.
start                   Starts the specified virtual device
stop                    Stops the specified virtual device
stopall                 Stops all virtual devices
delete                  Delete a device using the device name or the device
                        uuid
details                 Returns the properties of one or more specified
                        virtual devices
clone                   Clone a device using a target device name or uuid
templates               <deprecated> Lists all online and offline available
                        virtual device templates
                        This command is deprecated. Please use admin
                        hwprofiles or admin osimages
hwprofiles              List all available hardware profiles
osimages                List all available Os images
edit                    Edit the properties of a device
factoryreset            Restores default settings
logzip                  Create an archive of one or all current devices


Options:
-t, --timeout <0-3600>  Timeout duration in seconds
-v, --verbose           Verbose mode
-h, --help              Displays help on commandline options

Arguments:
admin                   Admin argument: Set of commands to manage devices
action                  Available actions: create, delete, clone, start,
                        stop, stopall, details, edit, list, templates,
                        osimages, hwprofiles, factoryreset, logzip

gmtool license

Paying

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

Command Description
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

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

gmtool config

Paying

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 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 you to administrate virtual devices.

Basic commands

Command Options Description
start <device> --coldboot Starts the specified virtual device. --coldboot: forces a complete boot cycle instead of using the default resume state.
stop <device> Stops the specified virtual device.
list --running --off Lists all virtual devices.
--running: lists running virtual devices only.
--off: lists turned off virtual devices only.

Example

Start the virtual device named "My Phone":

gmtool admin start "My Phone"

List all the running virtual devices:

gmtool admin list --running

Advanced commands

Paying

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.
stopall Stops all virtual devices.
factoryreset <device> Restores the specified virtual device to factory state.
delete <device> Deletes the specified virtual device.
clone <device> <new_device> Duplicates the specified virtual device to a new virtual device.
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 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
    • TAGS
    Values for each property are detailed at developer.android.com .
    edit <device> Edits the specified virtual device settings. See 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

    Paying

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

    Options available for each subcommands within this group are:

    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 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 Description
    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> Sends 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> Flash 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 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 gmsaas binary path, {GMTOOL_DIR}, to $PATH.

    Note

    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
    

    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)
    
    Back to top