Get Started

Requirements

Python 3.8+
pip3 20.9+
Android SDK

Supported operating system

Windows 10/11 x86 64 bits
macOS 11 (Big Sur) or above (Intel or Apple Silicon)
Linux x86/x86_64: Ubuntu 20.04 or above
Linux arm64: Ubuntu 24.04 or above
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 32 / 42
Debian 11 / 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

Wait, I get 'error: externally-managed-environment'

It means you're 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, you have several options:

Use a virtual Python environment (recommended), you can follow this tutorial.
Use

pip3 install [--user] gmsaas --break-system-packages

if you're aware of the consequences (not recommanded).

Using

pip3 with elevated privileges (strongly discouraged).


## Upgrade

pip3 install [--user] --upgrade gmsaas

To benefit from ARM64 images, you need to use
gmsaas 1.12.0 or above.
If you're 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 or 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:

gmsaas config set android-sdk-path <sdk_path>

<sdk_path> should point to the Android SDK installation directory, similar to the
ANDROID_SDK_ROOT or deprecated ANDROID_HOME environment variables.

2. Authenticate:
Create an API Token here and copy it to your clipboard.

Then, to use it with
gmsaas, you can either run the following command in a terminal:

gmsaas auth token <token>

or you can store the API Token in the environment variable
GENYMOTION_API_TOKEN.

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.

You can check if gmsaas is well configured by using the command

gmsaas doctor

Exit code will be

in case of success,

otherwise. For example:

gmsaas

doctor

Check

finished:

Authentication

OK.

Android

SDK

OK.

Output format

1.5.0

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

1.3.0

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

SOCKS5 proxy is supported only from gmsaas 1.4.0 onward.

Proxy settings can be configured via

gmsaas config command.

1.4.0 1.3.0

gmsaas config set proxy (http|socks5)://host:port

For an authenticated proxy, credentials can be passed in the URL:

gmsaas config set proxy (http|socks5)://user:password@host:port

gmsaas config set proxy http://host:port

For an authenticated proxy, credentials can be passed in the URL:

gmsaas config set proxy http://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

or you can set the credentials using environment variables in the gmsaas configuration file, you can set the credentials using:

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)"

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

---