Command Line Interface Documentation

System Requirements Installation Executable Connect to GigaFox CLI Configuration File Commands

CLI Commands Application Commands Connection Commands Device Commands Viewer Commands User Commands Gateway Commands Time Commands Report Commands

GigaFox Command Line Interface

GigaFox’s Command Line Interface (CLI) can be used to perform most of the functions available through the web UI, including automated tests scripts, connecting to devices, and launching applications without user interaction.

Installation

The CLI file is available for download from the GigaFox UI. To download and install the CLI:

Launch GigaFox.
On the top right, click the user dropdown menu and select the appropriate CLI download link.
Options include: Windows, macOS, and Portable.
Extract and save the zip file. The file can be saved anywhere, but we recommend saving it in the following locations:
- macOS: /usr/local/deviceconnect/cli
- Windows: C:\Program Files (x86)\Mobile Labs\Cli

Executable

An executable is required to connect and run commands on the CLI. The GigaFox CLI has a specific executable for a macOS and Windows system:

macOS: ./dc-cli
Windows: dc-cli.exe

NOTE: The command examples on this document are specific to the CLI on a macOS. To connect or run a CLI command on a Windows system, substitute ./dc-cli for dc-cli.exe at the beginning of the command.

Connect to GigaFox CLI

Unless specified in the configuration file, the CLI requires user authentication prior to the command. Authenticate a command by using any of the following:


   > ./dc-cli <host> <username> <password> command

   > ./dc-cli <IP address or DNS> <username> <api token> command

   > ./dc-cli <username>:<password>@<IP address or DNS> command

   > ./dc-cli <username>:<api token>@<IP address or DNS> command

CLI configuration file

The GigaFox CLI configuration file stores user authentication information on the system, eliminating the need to authenticate before every command.

To authenticate with the CLI configuration file, create the file:

On Windows: %HOMEPATH%\dccli.ini.
On macOS: ~/.dcclirc.

The file must contain the following:


   [connection]
   server=<IP address or DNS>
   user=<username>
   token=<api token>

Commands

CLI command structure

All CLI commands follow the same structure:


   > ./dc-cli <IP address or DNS> <username> <password> command <required parameter> [optional parameter]

CLI Commands

-help

Displays a list of CLI commands and options. -help is the default output when a command is not provided.

To display help output:


   > ./dc-cli -help
   > ./dc-cli

-ping

Will test the reachability of the host. If the host is contacted, the command will return Ping succeeded to terminal. If the host could not be reached, the command will return Ping failed.

To test the reachability of the host:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -ping

-continue

Allows a command with an error to continue processing after displaying an error message from a previously failed command.

This command will continue to upload the application even though -deleteapp fails due to a typo in the application's name:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -continue -deleteapp MobilLabsApp -upload "C:\applications\MobileLabsApp.ipa"

-os [android|ios]

Adds an Android or iOS filter to application and device commands.

To display a list of enabled iOS devices and applications:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -os ios -dl -al

Connection Commands

-host

Allows a user to access a host other than the one called in the authentication parameter.

To display device lists from hosts 192.168.1.50 and 192.168.1.100:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -dl -host 192.168.1.100 -dl

Note: username and password must be the same for both hosts.

-username

Allows a user to change the username provided in the authentication parameter.

To return the device list with a different username/password:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -host 192.168.1.100 -username [email protected] -password yourPassword -dl

-password

Allows the user to change the password provided in the authentication parameter.

To return the application list with a different username/password:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -host 192.168.1.100 -username [email protected] -password yourPassword -al

-api

Allows the user to change the API token provided in the authentication parameter.

To return the device list with a different username/API token:


   > ./dc-cli 192.168.1.50 [email protected] ceba3df1-b9d1 -415f-a704-be29a3838899 -host 192.168.1.100 -username [email protected] -api apiToken -dl

Application Commands

-applist or -al [android|ios]

Returns a list of all the applications on GigaFox. The list details include, application name, version, minimum OS, upload date, and unique ID.

For a list of iOS and Android applications:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -applist

For a list of Android applications:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -al android

-deleteapp <application name|unique ID > [-version]

Deletes the application by name or unique ID. If there are multiple uploads of the same application, use the unique ID or version to delete the single instance. Without, the most recent upload will be deleted.

Use -version to delete a specific version of the application. If more than one application with the same version is found, the application will not be deleted and a message of "# applications start with that name." outputs to the terminal.

Note: When using -version with -deleteapp, the build and version numbers are required.

To delete the MobileLabsApp application:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -deleteapp MobileLabsApp

-version <version>

Specifies the application by version, build, or upload number. -version must be called before other application options.

To delete MobileLabsApp version 1.0:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -version 1.0 -deleteapp MobileLabsApp

To delete MobileLabsApp version 1.0 and 3#2:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -version "1.0/3#2" -deleteapp MobileLabsApp

-upload <filename>

Uploads an application to GigaFox.

To upload the application MobileLabsApp.ipa:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -upload "C:\applications\MobileLabsApp.ipa"

-name <Display Name>

When uploading an application, -name assigns the Display Name of the application during the upload process. Must be used with the -upload command.

To upload the MobileLabsApp.apk application and assign it "MyApp Ver2.0" as its Display Name:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -upload "C:\MobileLabsApp.apk" -name "MyApp Ver2.0"

Device Commands

Displays a list of devices in GigaFox. Device details include name, model, platform, operating system, serial number, and username (if retained).

To display a list of devices:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -devicelist

To display the names, without details, of online iOS devices:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -devicelist online, ios, simple

-d or -device [name|serial number|prefix]

Specifies which device to use when executing a command. If there is more than one device with the same specified name, the first device to match against the database will be used. If a device is not specified, the first available online device is used.

To display the logs for device Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -log

   > ./dc-cli 192.168.1.50 [email protected] myPassword -device Blue iPhone -log

-install <application>

Installs an application to a device.

To install the MobileLabsApp application on the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -install MobileLabsApp

-launch <application name|unique ID>

When used with -device, this will launch the application on the specified device. Prior to running this command, the application must be installed and the device retained.

To launch MobileLabsApp on the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -retain -launch MobileLabsApp

-uninstall <application name|unique ID>

Uninstalls an application.

To uninstall MobileLabsApp on the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -uninstall MobileLabsApp

-preserve

Allows data to be preserved if an application is uninstalled. Must be called before the -uninstall.

Note: -preserve is only compatible with Android devices.

To preserve application data prior to uninstalling MobileLabsApp on the ML Nexus 4 device:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "ML Nexus 4" -preserve -uninstall MobileLabsApp

-retain

Retains the device and displays it as in use.

To retain the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -retain

-release

Releases the device and display it as available.

To release the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -release

-reboot

Reboots the device.

To reboot the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -reboot

-renamedevice <new name>

This will give the device a new name.

To rename the Blue iPhone to Red iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -renamedevice "Red iPhone"

-log

Returns device logs.

To view the Blue iPhone's device logs:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -log

To save the Blue iPhone's device logs to a .txt file:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -log > C:\DeviceLogs\BlueiPhoneLog.txt

-enable <device name>

Will enable a device, adding it to the list of available licensed devices.

To enable the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -enable "Blue iPhone"


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -enable

-disable

Removes device from the licensed device list, allowing another device to use the license.

To disable the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -disable "Blue iPhone"


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -disable

-reset [-uninstallAll] [-reboot]

Resets the state of a device. -uninstallAll and -reboot use systemwide preferences unless specified.

To reset and uninstall all applications on the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -reset -uninstallAll

To reset, uninstall all applications, and reboot the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -reset -uninstallAll -reboot

Viewer Commands

Note: only available on Windows machines in which deviceViewer is installed

-connect <application name|unique ID>

Connects to an application.

To install and connect to the MobileLabsApp on the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -retain -install "MobileLabsApp" -connect "MobileLabsApp"

-autoconnect <application name or ID>

Immediately connects upon launching the viewer, but the specified application must already be installed on the device.

Note: Because both -launch and -autoconnect will launch the application, we recommend using one command or the other.

To retain Blue iPhone and immediately connect to MobileLabsApp on Trust:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -retain -install "MobileLabsApp" -autoconnect "MobileLabsApp"

-run or -r < application name|unique ID>

Shortcut for -retain, -install, and -autoconnect.

To run MobileLabsApp on the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -r "MobileLabsApp"

   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -run "MobileLabsApp"

-scale <%>

Sets the device's viewer window scale by percentage. Values are integers, for example, 25 for 25%.

Must be placed before -run, -connect, and -autoconnect commands.

To set the viewer window scale to 50% on the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -scale 50 -r "MobileLabsApp"

-orientation

Sets the device's orientation to Portrait (default), LandscapeLeft, LandscapeRight, or UpsideDown.

Must be placed before -run, -connect, and -autoconnect commands.

To set the Blue iPhone's orientation to LandscapeLeft and run MobileLabsApp:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -orientation LandscapeLeft -r "MobileLabsApp"

-client [web|desktop|https]

Specifies the client connection for GigaFox. Defaults to desktop on Windows and web elsewhere. The https option will only work on HTTPS enabled GEMs.

To use the Blue iPhone on the web and run MobileLabsApp:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -client web -r "MobileLabsApp"

To use the Blue iPhone on the desktop, set the orientation and run MobileLabsApp:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -orientation LandscapeLeft -client desktop -r "MobileLabsApp"

-nativeautomation

Used to activate native automation.


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device -"Blue iPhone" -nativeautomation -r "MobileLabsApp"

-viewonly <name>

When enabled, grants access to an already launched testing session on a view-only deviceViewer. The view-only deviceViewer removes access to the capabilites usually found on the viewer.

To launch a shared, view-only session for the Blue iPhone:


   > .dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -viewonly

User Commands

Displays user details. Only authorized users will be able to access the details of users other than themselves.

-user <ID|email> [-details],[-usage], [-history],[-password]

Specifies the GigaFox user to return data for.

To return the usage data for [email protected]:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -user [email protected] -usage

-details [-format csv|json|list][-o file]

Outputs user details to the terminal.

To output the details of user [email protected]:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -user [email protected] -details

To save user [email protected]'s details to a CSV file:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -user [email protected] -details -format csv -o "C:\DeviceConnect\Users\details.csv"

JSON format will return two additional user details, "Id" and "CreatedDate":


   > ./dc-cli 192.168.1.50 [email protected] myPassword -user admin -details -format json

"CreatedDate" will only display the date of newly created users, the return value for existing users will be "null."

-password <new password>

Used with -user to assigns a new password. -password will not change passwords for LDAP users.

To change the password for the user tester1:


   > ./dc-cli 192.168.1.50 [email protected] password -user tester1 -password newpassword

-userimport </path/to/csv/file.csv>

Allows authorized users to import user information (username and password) into GigaFox from a CSV file. If the password field information is unavailable, PasswordHash and PasswordSalt will be transferred.

To import user information from import.csv file:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -userimport "C:\DeviceConnect\Users\import.csv"

Tip: Use-userexport for an example of a CSV user details template.

-userexport < /path/to/csv/fileName> [-format csv|json]

Allows authorized users to export and save GigaFox user information to a CSV (default) or JSON file.

To save user information to a CSV file:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -userexport "C:\DeviceConnect\Users\export.csv"

To save user information to a JSON file:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -userexport "C:\DeviceConnect\Users\export.json" -format json

Note: A JSON file cannot be used for user import.

Gateway Commands

-gateways [-format csv|json|list] [-o file]

Displays the USB Hub port status for the attached device gateways.

To view the USB Hub port status:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -gateways

To save the USB Hub port status to a CSV file:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -gateways -format csv -o "C:\DeviceConnect\GatewayDetails\GatewayDetails.csv"

-usbhubportmode <|data|charge|off> [-usbhub<usb hub serial>] [-usbhubport<usb hub port number>]

Used to change a device’s port mode to data, charge, or off. Can be changed by specifying the device or by the USB Hub serial and port numbers.

To set port mode to data for the device with id 7e3a6b6b-ad5b-40e2-9fd7-0d18dd46832a:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -d "7e3a6b6b-ad5b-40e2-9fd7-0d18dd46832a" -usbhubportmode data

To set port mode to off on USB hub DJ008SQD port number five:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -usbhubportmode off -usbhub DJ008SQD -usbhubport 5

-usbhubreboot <usb hub serial number>

Reboots the USB Hub.

To reboot USB Hub DJ008SQD:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -usbhubreboot DJ008SQD

Time Commands

-timezones

Lists timezones by Olson database location.


   > ./dc-cli 192.168.1.50 [email protected] myPassword -timezones

Report Commands

Report commands include device history and usage. By default, the data outputs to terminal but can be saved to a CSV file.

-history [arguments]

Returns device history.

To return the history of all GigaFox devices:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -history

To return the history of the Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -history

-usage [arguments]

Returns the usage data.

To return usage data for all GigaFox devices:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -usage

To return usage data for Blue iPhone:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -device "Blue iPhone" -usage

Report Arguments

-from <YYYY-MM-DD>

Defines the report's start date.

To view GigaFox usage from January 1, 2017 to present day:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -usage -from 2017-01-01

-to <YYYY-MM-DD>

Defines the report's end date.

To view GigaFox history from January 1, 2017 - January 5, 2017:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -history -from 2017-01-01 -to 2017-05-01

-days <N>

Defines the number of previous days to included in the report.

To view GigaFox's history for the past seven days:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -history -days 7

-timezone <locations>

Returns additional timezone data from locations on the Olson timezone database. Multiple locations require the argument to be enclosed in quotes.

Note: CSV files will include additional columns. JSON format will return the data inside the singular object.

To output a system's usage for the past seven days with local time:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -history -days 7 -timezone local

To output a system's usage for the past seven days with New York, Calcutta, and the local time:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -usage -days 7 -timezone "America/New_York Asia/Calcutta local"

-format <csv|json|list>

Defines data format. Arguments include CSV (default), JSON, or list. All arguments are case sensitive.


   > ./dc-cli 192.168.1.50 [email protected] myPassword -history -days 7 -format json "C:\DeviceConnect\History\Previous7Days.csv"

-o <filename>

Specifies the path for a CSV output file. Without this option, the data outputs to the terminal.

To save the last seven days of a device's history to a CSV file:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -history -days 7 -o "C:/DeviceConnect/History/Previous7Days.csv"

To save the last seven days of a device's usage to a CSV file:


   > ./dc-cli 192.168.1.50 [email protected] myPassword -usage -days 7 -o "C:/DeviceConnect/Usage/Previous7Days.csv"