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:

Windows (default)LinuxmacOS

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:

	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:

	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:

	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¶

	Options	Description
`start <device>`	`--coldboot`	Starts the specified virtual device. `--coldboot`: forces a complete boot cycle
`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

	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 . `--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 `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:

	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:

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

LinuxmacOS

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

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

fpath=({COMPLETION_DIR}/zsh $fpath)