gmsaas Command Line Interface

gmsaas is a command line interface to rule all your virtual devices hosted in Genymotion SaaS without opening an Internet browser.

It allows to:

• Manage Android instances (create, list, start, save, stop etc)
• Securely connect instances to Android Debug Bridge

It is a lightweight binary. It is easy to install. It is easy to update.

Requirements

• Python 3.10+ (pip 21.2.3+)
• Android SDK (platform-tools)

Supported operating system

• Windows 11 x86_64
• macOS 11 (Big Sur) or higher
• Linux x86/x86_64: Ubuntu 20.04 or higher
• Linux arm64: Ubuntu 24.04 or higher

Linux x86

Most x86/x86_64 Linux distributions having GLIBC 2.31 or above will work.

Tested on:

• Ubuntu 20.04 / 22.04 / 24.04
• Fedora 40 / 42
• Debian 12 / 13

Linux arm64

Most arm64 Linux distributions having GLIBC 2.39 or above will work.

Tested on:

• Ubuntu 24.04
• Fedora 40 / 42
• Debian 13

Installation

pip3 install [--user] gmsaas

> Warning: Versions prior to 1.14.1 have been yanked > gmsaas versions older than 1.14.1 are no longer available on PyPI. > The oldest installable version is 1.14.1.

If you get the error error: externally-managed-environment, it means you are using a Python interpreter managed by your system. This type of environment restrict direct install using pip3 to protect the system's dependencies.

To resolve this issue, you can use the following options: 1. Use a virtual Python environment (recommended). Follow this tutorial. 2. Use pip3 install [--user] gmsaas --break-system-packages if you are aware of the consequences (not recommanded). 3. Use pip3 with elevated privileges (strongly discouraged).

Upgrade

pip3 install [--user] --upgrade gmsaas

> Warning: Python 3.8 and 3.9 are no longer supported as of gmsaas 1.16.0. > Please upgrade to Python 3.10 or above.

> Info: To benefit from ARM64 images, you need to use gmsaas 1.12.0 or above.

> Info: If you are using Python 3.12, you need to use gmsaas 1.11.0 or above.

Uninstallation

Python package

pip3 uninstall gmsaas

Local files

Remove the following directories to purge gmsaas:

• Windows: %LOCALAPPDATA%\Genymobile\gmsaas
• Linux: ~/.Genymobile/gmsaas and ~/gmsaas.tmp
• macOS: ~/.Genymobile/gmsaas

Get notified when a new version is out

You can add the RSS feed https://pypi.org/rss/project/gmsaas/releases.xml to your favorite RSS feed reader. You can also add the RSS feed to your corporate communication solution (Slack, Microsoft Teams, Discord and so on). There is no other communication than new gmsaas releases.

Configuration

Prerequisites

Two steps are required to use gmsaas properly: 1. Configure the path to your Android SDK. <sdk_path> should point to the Android SDK installation directory. The directory is similar to the ANDROID_SDK_ROOT environment variable. The directory is also similar to the deprecated ANDROID_HOME environment variable. 2. Authenticate. Or store the API Token in the environment variable GENYMOTION_API_TOKEN.

> Warning: Using credentials to authenticate gmsaas has been deprecated since version 1.10.0. > If you have existing automated tests, please consider using an API Token instead of the tuple email / password for security reasons. > gmsaas auth token should be used in place of gmsaas auth command. > gmsaas auth reset should be used in place of gmsaas auth command. > While these deprecated commands are still working with gmsaas 1.10.0, they are subject to removal in future releases.

1. Create an API Token here and copy it to your clipboard. 2. Then, to use it with gmsaas, you can either run the following command in a terminal: gmsaas auth token <token> Or store the API Token in the environment variable GENYMOTION_API_TOKEN.

You can check if gmsaas is well configured by using the command gmsaas doctor. Exit code will be 0 in case of success. Exit code will be 1 otherwise.

Example:

gmsaas doctor

• Check up finished:
• Authentication OK.
• Android SDK OK.

Output format

gmsaas exposes a global --format (text|json|compactjson) option for all commands.

Available formats are:

• text: Plain text output (default).
• json: JSON-formatted output.

While each command has specific data printed, it always contains exit_code information.

• compactjson: Same thing as json format but one-lined.

You can set a default output format to use in configuration with: gmsaas config set output-format json

Examples:

Successful command in JSON format:

gmsaas --format json logzip

• "archive_path": "/home/me/projects/myapp/gmsaas-logs-20200605-092516.zip"
• exit_code": 0
• "exit_code_desc": "NO_ERROR"

Error in JSON format:

gmsaas --format json instances list

• "error":
• "message": "Error: unable to use the proxy"
• "details": "Failed to establish a new connection: [Errno 113] No route to host"
• exit_code": 15
• "exit_code_desc": "REQUEST_ERROR"

Proxy

If you are behind a corporate proxy, gmsaas may not be able to access the Internet with its default settings.

> Info: SOCKS5 proxy is supported only from gmsaas 1.4.0 onward.

Proxy settings can be configured via the gmsaas config command.

For gmsaas 1.3.0 and below: gmsaas config set proxy http[s] socks5://:host:port

For gmsaas 1.4.0 onward: gmsaas config set proxy http[s] socks5://host:port

For an authenticated proxy, credentials can be passed in the URL: gmsaas config set proxy http[s] socks5://user:password@host:port

Alternatively, to avoid having the proxy credentials stored in gmsaas configuration file, you can set the credentials using environment variables:

• GMSAAS_PROXY_USERNAME: the username used to connect to the proxy
• GMSAAS_PROXY_PASSWORD: the password of given user

Bash/Zsh auto-completion

gmsaas supports Bash and Zsh auto-completion. To activate it, you need to inform your shell that completion is available.

For Bash, add this to your .bashrc: eval "$(_GMSAAS_COMPLETE=source gmsaas)"

For Zsh, add this to your .zshrc: eval "$(_GMSAAS_COMPLETE=source_zsh gmsaas)"

> Warning: You must type at least one dash to complete command-line options.