virtualUSB command-line interface (CLI)

 

The virtualUSB command-line interface (CLI) is a set of commands used to perform the core virtualUSB features, such as: login, logout, connect devices, disconnect devices, etc. It is designed to speed up virtualUSB usage, as well as enable automation through scripting.

Using virtualUSB CLI requires the installation of the virtualUSB application. Refer to the virtualUSB installation guide for Windows and MacOS for instructions.

Determine how you will connect to virtualUSB CLI

Once installed, virtualUSB resides in the following directories:

• for Windows: C:\Program Files\virtualUSB
• for macOS: /Applications/virtualUSB.app/Contents/Resources

To start using virtualUSB CLI, determine how you will access it from the following options:

• Open a terminal on the user workstation and cd to the directory as follows:
  • for Windows: cd "C:\Program Files\virtualUSB"
  • for macOS: cd /Applications/virtualUSB.app/Contents/Resources
• Use the complete path to the virtualUSB command when invoking it.
  • Windows example: "c:\Program Files/virtualUSB/vusb.exe" login --username MyName --password MySecretPassword
  • macOS example:/Applications/virtualUSB.app/Contents/Resources/vusb login --username MyName --password MySecretPassword
• Add the directory to the search PATH used by the shell

Log into virtualUSB

Before using virtualUSB CLI, you must first login by entering the following command:

vusb login

Enter the username/email and the password/API key to login.

Alternatively, you can specify the username/email and password/API key directly in the login command:

vusb login --username <username> --password <password>

For customers using Standalone or Cloud deployments with custom URLs, add 2 more options in the login command in virtualUSB v4.6 and above:

vusb login --username <username> --password <password> --apibaseurl <API Base URL> --grpcbaseurl <GRPC Base URL> 

For how to obtain the value of <API Base URL> and <GRPC Base URL>, refer to the installation guide for Windows and MacOS.

Note: When specifying --password in the command, the password displays in plain text, so make sure to keep the password secure while using.

View virtualUSB help

To see a list of commands supported by virtualUSB, use the following command:

vusb --help

To get more information about a particular command, use the following where <command> is the name of the command:

vusb help <command>

Connect to a device

To connect to a device via virtualUSB, enter the following command where <udid> is the UDID of the device to be connected. Only one UDID can be specified here. Make sure the device you want to connect to is available to your Kobiton account.

vusb connect --udid <udid>

Disconnect from a device

To disconnect from a device, enter the following command where <udid> is the UDID of the device to be disconnected. Only one UDID can be specified here.

vusb disconnect --udid <udid>

View connected device’s status

To check the status of a currently connected device, enter this command:

vusb status

If there are devices connected, the command output will be similar to the below:

{
  "servers": [
    {
      "connectionStatus": "Connected", //Host connection status
      "host": "virtualusb.example.com:10002", //URL of the virtualUSB host
      "linkedDevices": [
        {
          "connectionStatus": "Connected", //Connection status of the device
          "id": "0709C8D4-DD63-E500-8832", //ID of the device
          "name": "Galaxy A11", //Name of the device
          "os": "Android", //Operating system of the device
          "osVersion": "12", // OS version of the device
          "statusDescription": "Connected", //Description of the connection status
          "vendorUniqueIdentifier": "R9JN615AACA" //UDID of the device
        },
        {
          "connectionStatus": "Connected",
          "id": "6A2266BE-F655-57A2-349C",
          "name": "Galaxy Tab A",
          "os": "Android",
          "osVersion": "9",
          "statusDescription": "Connected",
          "vendorUniqueIdentifier": "R52N501VDSA"
        }
      ],
      "name": "virtualusb.example.com:10002",
      "statusDescription": "Connected"
    }
  ],
  "version": "4.0.10924.1230.KOB-31816-vucli@1cb4dae" //virtualUSB version
}

Export logs

To export logs of virtualUSB usage, enter the following command where:

• <out> is the path to save the log file. If not specified, the file will be downloaded to the default location.

• <days> is the number of days from the current day to retrieve the log. If not specified, the default value is 1.

vusb export-logs --out <out> --days <days>

When executed, a zip archive containing all the logs in the selected period will be downloaded. The file’s download location will be mentioned in the output as in the following example:

Please wait...
Exported to /Users/john/Downloads/vulogs.zip

Log out

To log out, enter this command

vusb logout

Set up iOS devices (Windows only)

On Windows machines, extra configuration steps need to be performed to set up iOS devices. To do this, enter the following command in a terminal with administrator privileges:

vusb setup-ios

Set up adb (Windows only)

On Windows machines, extra configuration steps need to be performed to set up adb (Android Debug Bridge). To do this, enter the following command in a terminal with administrator privileges:

vusb setup-adb

Limitations

• The first time you run a vusb connect or vusb disconnect command on a macOS machine, make sure you run it on the physical machine or remote to it with full UI access to allow virtualUSB to install the daemon. The visual prompt to allow this permission does not appear if the command runs via ssh. This step is only required one time.

• Within the zip file exported using the command vusb export-logs, the created and modified date time of some of the files and folders are displayed incorrectly as January 1, 1980 at 12:00 AM.