-----------------------------

ANDROID TOOL COMMAND LINE

Version 1.7
Table of Contents
1. Introduction............................................................................................................................................................1
2. User Stories.............................................................................................................................................................1
3. Functional specification...........................................................................................................................................1
3.1 Android Build Tool Command Line..................................................................................................................1
3.2 General information........................................................................................................................................1
3.3 Supported commands.....................................................................................................................................1
3.3.1 Install command......................................................................................................................................1
3.3.2 Uninstall command..................................................................................................................................4
3.3.3 Start command........................................................................................................................................5
3.3.4 Help command........................................................................................................................................6

Revision History
Name Date Reason For Changes Version

Nghi Bui, Thuc 26-Aug-13 Add the integration command line tool that 1.0
Nguyen supports users to resign/install/uninstall
android applications.
Khai Tran – 1421 9-Sep-13 Review 1.1
Update structure
Add “start” command
Nghi Bui 20-Sep-13 Update “start” command rules 1.2
Nghi Bui 27-Sep-13 Update priority of error message 1.2
Nghi Bui 01-Oct-13 Update help command 1.3
Nghi Bui 03-Oct-13 Update swap argument in a command 1.4
Remove start program action
Nghi Bui 18-Oct-13 Add –f option to install command 1.5
Nghi Bui 22-Oct-13 Support force install on Android – 1.6
Instrumentation Applications
Nghi Bui 23-Oct-13 Update Swap All Argument (Included Child 1.7
Option)
 1. Introduction

This document describes rules of Android Build Tool Command Line and help users to use it.

2. User Stories

As a user, I want AndroidBuildTool.exe can run in command line mode to support user install/uninstall/start android
applications.

3. Functional specification

3.1 Android Build Tool Command Line

3.2 General information

Android support tool: ast.exe

The tool will output result (include: error message handling) to the command line screen. But if users want to store
this result to a file and don’t display on the command line screen, users can use [> “File Name”] option.

In case users want to run this command from action “start program”, they can use:

start program {INSTALL_DIR}\device\ast.exe

Supported commands:

- ast.exe install <”Path-To-Apk”> [-s <Unique ID of Target Device>]

- ast.exe uninstall <”Package Name”> [-s ”Unique ID of Target Device”] [Child Option]
- ast.exe start <”Package Name”> [-s ”Unique ID of Target Device”]

If users have more than one error, the tool will check the first error with error priority as below:

1. Cannot connect device

2. Cannot find file or package
3. All other error messages

Limitation:

- Only support devices that connect to user’s machine by cable.

- One line of command only contains “install”, “uninstall” or “start”.

Note: “ast.exe” can execute only one command on one line.

3.3 Supported commands

3.3.1 Install command

“Install” is used to install an Android application.

ast.exe install <”Path-To-Apk”> [-s <Unique ID of Target Device>] [Child Option]

Android Build Tool Command Line| Introduction 1

N Option Name
o
1 <”Path-To-Apk”>
2 -s <”Unique ID of Target Device”>
3 [“Child Option”]
-f: force to install Android application in cases:
Description
- Required parameter
- Full path to the file that users want to install to an android device
- Unique ID of Target Device: is a mac address of target device.
- Required parameter if users have multiple devices that connected
with their computer.
- Optional parameter if users have only one device that connected
with their computer.
- Unique ID of a device that users want to install this application on
- Optional argument
- The existed AUT/Data has same signature with Logigear’s
signature: remove and keep all data before install this android
app.
- Otherwise: remove and clear all data before install this this
android app.

Rule of “install”:

 Users can swap all arguments as below:

o install <”Path-To-Apk”>
o -s <Unique ID of Target Device>
o -f
 Users need to specify a file name that they want to install.
 One line of command only installs one Android application to one android device.
 If source file is not signed by Logigear, the source file will be signed and then the signed file will be installed
to device.
o If the source file is not TA Agent, an TA instrument agent for this app will be installed.
 The tool will automatically save a signed file at the same place with old file. And with a signed file have a
suffix “_signed” at the end of file name and before the file extension: <Source File>_signed.apk
 If the new file names have the same name with an existing file, the tool will overwrite this file.
 If the Android device that users want to install already has this application, the tool will uninstall and re-
install it on the device.
 If users have only one device connected to this tool, the tool will automatically find this device and users can
use or not use [-s <”Unique ID of Target Device”>] option. Otherwise, users must have this option.

Support Android – Instrumentation Applications

 When users use “Android – Instrumentation Applications” to install android application, but this application
is existed or has different signature with LogiGear signature. TA will automatically show a message box as
below:

Android Build Tool Command Line| Introduction 2

 o Button “Yes”: force installs this application.
o Button “No”: close this message box.

Error Message Handling:

If there is more than one error, the tool only displays the first error message. After that, the tool will be terminated.

N Error Code Error Message Description

o
1 001 The file at location “<File Location>” Cannot find the apk file that is specified by users to
cannot be found. resign or install.
<File Location>: replace it with the name and full path of
the file that users want to sign/resign.
2 002 <File Name> is signed successfully. <File Name>: replace it with the file name and full path
of the file that users want to sign/resign when the file
that is resigned successfully.
3 003 <File Name> cannot be signed. <File Name>: replace it with the file name and full path
Detail: <Exception information> of the file that users want to sign/resign when the file
that is resigned unsuccessfully.
<Exception information>: display all exception
information details.
4 004 Cannot save the file after resigning. When the directory in which users want to save the file
after resigning is read-only.
5 005 Cannot connect to the device. The tool can find the device specified by users but
cannot connect to this device.
6 006 Cannot find the device. The tool cannot find the device specified by users.
7 007 <File Name> is installed successfully. When the file is installed successfully.
8 008 <File Name> cannot be installed. When the file is installed unsuccessfully.
Exception:…
9 009 Unknown error. Display when have other errors.
Detail: <Exception information> <Exception information>: display all exception
information details.
10 010 There are multiple Android devices When users have multiple Android devices connected to
connected to the tool. You must this tool but users don’t fill the “Unique ID of Target
specify the exact Unique ID of the Device” argument.
target device.
Sample:

Case 1:

- Apk file and AndroidBuildTool are stored in the same location.

Android Build Tool Command Line| Introduction 3

 - The “MyFile.apk” is an unsigned file.
- Users want to sign and install this file to an Android device.
- Unique ID of Android Device is “emulator-5554”.
- Only have one device connected to this tool.
- Option 1:

ast.exe install “MyFile.apk”

- Option 2:

ast.exe install “MyFile.apk” –s “emulator-5554”

Case 2:

- Apk file and AndroidBuildTool are stored in different locations.

- The “MyFile.apk” is an unsigned file.
- Users want to sign and install this file to an Android device.
- Unique ID of Android Device is “emulator-5554”.
- Users have two devices that connected with this tool.

ast.exe install “C:\UserFolder\MyFile.apk” -s “emulator-5554”

3.3.2 Uninstall command

“uninstall” is used to uninstall an Android application from an Android device. This command has two child options:

-k: keep the data and cache directories after removing the package
-c: delete all data associated with the package that is uninstalled by users.

ast.exe <uninstall <”Package Name”>> [-s ”Unique ID of Target Device”] [Child Option]

N Option Name Description

o
1 <”Package Name”> - Required parameter
- Package name that users want to uninstall
2 -s <”Unique ID of Target Device”> - Required parameter if users have multiple devices that connected
with their computer.
- Optional parameter if users have only one device that connected
with their computer.
- Unique ID of a device that users want to uninstall android application
3 [“Child Option”] - Optional argument
- Have two child options:
-k: keep the data and cache directories after removing the package
-c: delete all data associated with the package that is uninstalled by users.
And “-c” is a default option.

Rule of “uninstall”:

 Users can swap all arguments as below:

o uninstall <”Package Name”>
o -s ”Unique ID of Target Device”
Android Build Tool Command Line| Introduction 4
 o -k
o -c
 Users can only uninstall an Android application from one Android device per execution.
 If the Android application that users want to uninstall is already running, the tool will kill this application
process and uninstall it.
 By default, the tool will delete all data associated with the package.
 If users have only one device connected to this tool, the tool will automatically find this device and users can
use or not use [-s <”Unique ID of Target Device”>] option. Otherwise, users must have this option.

Error Message Handling:

If there is more than one error, the tool only displays the first error message. After that, the tool will be terminated.

N Error Code Error Message Description

o
1 011 <Package Name> is uninstalled When the package is installed successfully.
successfully.
2 012 <Package Name> cannot be When the package is uninstalled unsuccessfully.
uninstalled.
3 005 Refer to Error Code 005 for more
details.
4 006 Refer to Error Code 006 for more
details.
5 009 Refer to Error Code 009 for more
details.
6 010 Refer to Error Code 010 for more
details.
7 014 <Package Name> cannot be found. When the package cannot be found on the Android
device.

Sample:

Case 1:

- Users want to uninstall an Android application with package name “com.example.MyApp”.

- Unique ID of Android Device is “emulator-5554”.
- Users want to delete all data associated with this package.

ast.exe uninstall “com.example.MyApp” –s “emulator-5554”

Case 2:

- Users want to uninstall an Android application with package name “com.example.MyApp”.

- Unique ID of Android Device is “emulator-5554”.
- Only have one Android Device connected to this tool.
- Users want to delete all data associated with this package.

ast.exe uninstall “com.example.MyApp”

Android Build Tool Command Line| Introduction 5

 Case 3:

- Users want to uninstall an Android application with package name “com.example.MyApp”.

- Unique ID of Android Device is “emulator-5554”.
- Users want to keep the data and cache directories after removing the package.

ast.exe uninstall “com.example.MyApp” -s “emulator-5554” –k

3.3.3 Start command

“start” is used to start an Android application from an Android device.

ast.exe <start <”Package Name”>> [-s ”Unique ID of Target Device”]

No Option Name Description

1 <”Package Name”>
2 -s <”Unique ID of Target Device”>
- Required parameter
- App package name
- Required parameter if users have multiple devices that
connected with their computer.
- Optional parameter if users have only one device that
connected with their computer.
- Unique ID of a device that users want to uninstall android
application

Rule of “start” options:

 Users can only start an Android application from one Android device per execution.
 Users can swap all arguments as below:
o start <”Package Name”>
o -s <”Unique ID of Target Device”>

The rules of “start” option will same with the rules of “Start selected AUT on device” on “Android – Instrumentation
Application” dialog.Error Message Handling:

If there is more than one error, the tool only displays the first error message. After that, the tool will be terminated.

N Error Code Error Message Description

o
1 011 App <Package Name> is started
successfully.
3 005 Refer to Error Code 005 for more details.
4 006 Refer to Error Code 006 for more details.
5 009 Refer to Error Code 009 for more details.
6 010 Refer to Error Code 010 for more details.
7 013 App <Package Name> cannot be started.
Detail: <Exception information>
8 014 Refer to Error Code 014 for more details.

Android Build Tool Command Line| Introduction 6

3.3.4 Help command
“help” is used to show Android command line help for users

ast.exe, ast.exe help

Rule of “help” options:

 Show help when users use help command or users enter wrong Android tool command line syntax.

Help content will be shown as below:

Android Command Line Tool version 1.0

Android Command Line Tool helps users to install/uninstall/start Android applications.

Install command: is used to install an Android application.

ast install <Path-To-Apk> [-s <Unique ID of Target Device>] - Install an Android application

(-s <Unique ID of Target Device>]: Required

parameter if users have multiple devices
that connected with their computer.)

(-f: remove Android application before

install. If Android application has different
signature with LogiGear signature, TA will
automatically clear all data. Otherwise, TA
will keep all data.)

Uninstall command: is used to uninstall an Android application from an Android device

ast uninstall <Package Name> [-s <Unique ID of Target Device>] [-k|-c] - Uninstall an Android application from an
Android Device

(-s <Unique ID of Target Device>]: Required

parameter if users have multiple devices
that connected with their computer.)

(-k: keep the data and cache directories

after removing the package)

(-c: delete all data associated with the

package that is uninstalled by users. And “-
c” is a default option.)

Start command: is used to start an Android application from an Android device.

ast start <Package Name> [-s <Unique ID of Target Device>] - Start an Android application

(-s <Unique ID of Target Device>]: Required

parameter if users have multiple devices
that connected with their computer.)

Help command: is used to show Android Command Line Tool help.

Android Build Tool Command Line| Introduction 7
ast help - Show this help message

Android Build Tool Command Line| Introduction 8