README.md - platform/tools/acloud - Gitiles

 # **Acloud Manual**

 ## **Acloud**

 Acloud is a command line tool that assists users to create an Android Virtual
 Device (AVD).

 ## **Table of Contents**

 1. [Environment Setup](#Environment-Setup)
 2. [Basic Usage](#Basic-Usage)

 ### **Environment Setup**

 Add acloud to your $PATH by lunching your environment.

 * Source envsetup.sh from the root of the android source checkout

 ```
 $ source build/envsetup.sh
 ```

 * Run lunch for an AVD target

 ```
 $ lunch aosp_cf_x86_phone-userdebug
 ```


 You should now be able to call acloud from anywhere.

 ### **Basic Usage**

 Acloud commands take the following form:

 **acloud &lt;command&gt; &lt;optional arguments&gt;**

 Available commands:

 * [create](#create)
 * [list](#list)
 * [delete](#delete)
 * [reconnect](#reconnect)
 * [setup](#setup)
 * [pull](#pull)

 #### **create**

 Create is the main entry point in creating an AVD, supporting both remote
 instance (running on a virtual machine in the cloud) and local instance
 (running on your local host) use cases. You also have the option to use
 a locally built image or an image from the Android Build servers.

 Here's a quick cheat-sheet for the 4 use cases:

 * Remote instance using an Android Build image (LKGB (Last Known Good Build)
 for cuttlefish phone target in the branch of your repo, default aosp main (master)
 if we can't determine it)

 > $ acloud create

 * Remote instance using a locally built image (use `m` to build the image)

 > $ acloud create --local-image [optional local-image-path]

 * Local instance using an Android Build image (LKGB for cuttlefish phone
 target in the branch of your repo)

 > $ acloud create --local-instance

 * Local instance using a locally built image (use `m` to build the image)

 > $ acloud create --local-instance --local-image

 When specifying an Android Build image, you can specify the branch,
 target and/or build id (e.g. `--branch my_branch`). Acloud will assume the
 following if they're not specified:

 * `--branch`: The branch of the repo you're running the acloud command in, e.g.
 in an aosp repo on the master branch, acloud will infer the aosp-main (aosp-master) branch.

 * `--build-target`: Defaults to the phone target for cuttlefish (e.g.
 aosp\_cf\_x86\_phone-userdebug in aosp-main (aosp-master)).

 * `--build-id`: Default to the Last Known Good Build (LKGB) id for the branch and
 target set from above.

 Additional helpful create options are:

 * `--config`: This can be one of phone, auto, tablet, tv. This wil be used to configure different types of hardware properties and infer build target if not specified.

 * `--autoconnect`:&ensp;Cuttlefish AVD defaults to webrtc and acloud will automatically open the browser upon creation of a remote or local instance.
 Acloud will also create a ssh tunnel to enable adb and webrtc connection to the instance. Other AVD types(such as goldfish, cheeps...) still default to vnc.

     *   If you want to invoke vnc client, you can pass in `--autoconnect vnc`.
     *   If you don't want autoconnect, you can pass in `--no-autoconnect`.

 * `--hw-property`: This is a string where you can specify the different
 properties of the AVD. You can specify the cpu, resolution, dpi, memory,and/or
 disk in a key:value format like so:
 `cpu:2,resolution:1280x700,dpi:160,memory:2g,disk:2g`

 * `--reuse-gce`: 'cuttlefish only' This can help users use their own instance.
 Reusing specific gce instance if `--reuse-gce` [instance-name] is provided.
 Select one gce instance to reuse if `--reuse-gce` is provided.

 The full list of options are available via `--help`

 > $ acloud create --help

 #### **list**

 List will retrieve all the remote instances you've created in addition to
 any local instances created as well.

 Cheatsheet:

 * List will show device IP address, adb port and instance name.

 > $ acloud list

 * List -v will show more detail info on the list.

 > $ acloud list -v


 #### **delete**

 Delete will stop your remote and local instances. Acloud will find all
 instances created by you and stop them. If more than one instance is found
 (remote or local), you will be prompted to select which instance you would
 like to stop.

 Cheatsheet:

 * Delete sole instance or prompt user with list of instances to delete.

 > $ acloud delete

 * Delete all instances

 > $ acloud delete --all

 * Delete a specific instance

 > $ acloud delete --instance-names [instance-name]

 #### **reconnect**

 Reconnect will re-establish ssh tunnels for adb/webrtc/vnc port forwarding for all
 remote instance created by you. It will then look for any devices missing in
 `adb devices` and reconnect them to adb. Lastly it will restart webrtc/vnc for all
 devices that don't already have webrtc/vnc started for them.

 Cheatsheet:

 * Reconnect sole instance or prompt user with list of instances to reconnect.

 > $ acloud reconnect

 * Reconnect all instances

 > $ acloud reconnect --all

 * Reconnect a specific instance

 > $ acloud reconnect --instance-names [instance-name]


 ### **pull**

 Pull will provide all log files to download or show in screen. It is helpful
 to debug about AVD boot up fail or AVD has abnromal behaviors.

 Cheatsheet:

 * Pull logs from a sole instance or prompt user to choose one to pull if where
 are more than one active instances.

 > $ acloud pull

 * Pull logs from the specific instance.

 > $ acloud pull --instance-name "instance-name"

 * Pull a specific log file from a specific instance

 > $ acloud pull --instance-name "instance-name" --file-name "file-name"


 #### **setup**

 Setup will walk you through the steps needed to set up your local host to
 create a remote or local instance. It will automatically get invoked through
 the create command if we detect some necessary setup steps are required. This
 is a standalone command if the user wants to do setup separate from the create
 command.

 Cheatsheet:

 * Run setup for remote/local instances

 > $ acloud setup

 * Run setup for remote instances only

 > $ acloud setup --gcp-init

 * Run setup for local instances only

 > $ acloud setup --host

 * Force run setup

 > $ acloud setup --force

 * * *

 If you have any questions or feedback, contact [acloud@google.com](mailto:acloud@google.com).

 If you have any bugs or feature requests email them to [buganizer-system+419709@google.com](mailto:buganizer-system+419709@google.com)
	# Acloud Manual

	## Acloud

	Acloud is a command line tool that assists users to create an Android Virtual
	Device (AVD).

	## Table of Contents

	1. [Environment Setup](#Environment-Setup)
	2. [Basic Usage](#Basic-Usage)

	### Environment Setup

	Add acloud to your $PATH by lunching your environment.

	* Source envsetup.sh from the root of the android source checkout

	```
	$ source build/envsetup.sh
	```

	* Run lunch for an AVD target

	```
	$ lunch aosp_cf_x86_phone-userdebug
	```


	You should now be able to call acloud from anywhere.

	### Basic Usage

	Acloud commands take the following form:

	acloud <command> <optional arguments>

	Available commands:

	* [create](#create)
	* [list](#list)
	* [delete](#delete)
	* [reconnect](#reconnect)
	* [setup](#setup)
	* [pull](#pull)

	#### create

	Create is the main entry point in creating an AVD, supporting both remote
	instance (running on a virtual machine in the cloud) and local instance
	(running on your local host) use cases. You also have the option to use
	a locally built image or an image from the Android Build servers.

	Here's a quick cheat-sheet for the 4 use cases:

	* Remote instance using an Android Build image (LKGB (Last Known Good Build)
	for cuttlefish phone target in the branch of your repo, default aosp main (master)
	if we can't determine it)

	> $ acloud create

	* Remote instance using a locally built image (use `m` to build the image)

	> $ acloud create --local-image [optional local-image-path]

	* Local instance using an Android Build image (LKGB for cuttlefish phone
	target in the branch of your repo)

	> $ acloud create --local-instance

	* Local instance using a locally built image (use `m` to build the image)

	> $ acloud create --local-instance --local-image

	When specifying an Android Build image, you can specify the branch,
	target and/or build id (e.g. `--branch my_branch`). Acloud will assume the
	following if they're not specified:

	* `--branch`: The branch of the repo you're running the acloud command in, e.g.
	in an aosp repo on the master branch, acloud will infer the aosp-main (aosp-master) branch.

	* `--build-target`: Defaults to the phone target for cuttlefish (e.g.
	aosp\_cf\_x86\_phone-userdebug in aosp-main (aosp-master)).

	* `--build-id`: Default to the Last Known Good Build (LKGB) id for the branch and
	target set from above.

	Additional helpful create options are:

	* `--config`: This can be one of phone, auto, tablet, tv. This wil be used to configure different types of hardware properties and infer build target if not specified.

	* `--autoconnect`:&ensp;Cuttlefish AVD defaults to webrtc and acloud will automatically open the browser upon creation of a remote or local instance.
	Acloud will also create a ssh tunnel to enable adb and webrtc connection to the instance. Other AVD types(such as goldfish, cheeps...) still default to vnc.

	* If you want to invoke vnc client, you can pass in `--autoconnect vnc`.
	* If you don't want autoconnect, you can pass in `--no-autoconnect`.

	* `--hw-property`: This is a string where you can specify the different
	properties of the AVD. You can specify the cpu, resolution, dpi, memory,and/or
	disk in a key:value format like so:
	`cpu:2,resolution:1280x700,dpi:160,memory:2g,disk:2g`

	* `--reuse-gce`: 'cuttlefish only' This can help users use their own instance.
	Reusing specific gce instance if `--reuse-gce` [instance-name] is provided.
	Select one gce instance to reuse if `--reuse-gce` is provided.

	The full list of options are available via `--help`

	> $ acloud create --help

	#### list

	List will retrieve all the remote instances you've created in addition to
	any local instances created as well.

	Cheatsheet:

	* List will show device IP address, adb port and instance name.

	> $ acloud list

	* List -v will show more detail info on the list.

	> $ acloud list -v


	#### delete

	Delete will stop your remote and local instances. Acloud will find all
	instances created by you and stop them. If more than one instance is found
	(remote or local), you will be prompted to select which instance you would
	like to stop.

	Cheatsheet:

	* Delete sole instance or prompt user with list of instances to delete.

	> $ acloud delete

	* Delete all instances

	> $ acloud delete --all

	* Delete a specific instance

	> $ acloud delete --instance-names [instance-name]

	#### reconnect

	Reconnect will re-establish ssh tunnels for adb/webrtc/vnc port forwarding for all
	remote instance created by you. It will then look for any devices missing in
	`adb devices` and reconnect them to adb. Lastly it will restart webrtc/vnc for all
	devices that don't already have webrtc/vnc started for them.

	Cheatsheet:

	* Reconnect sole instance or prompt user with list of instances to reconnect.

	> $ acloud reconnect

	* Reconnect all instances

	> $ acloud reconnect --all

	* Reconnect a specific instance

	> $ acloud reconnect --instance-names [instance-name]


	### pull

	Pull will provide all log files to download or show in screen. It is helpful
	to debug about AVD boot up fail or AVD has abnromal behaviors.

	Cheatsheet:

	* Pull logs from a sole instance or prompt user to choose one to pull if where
	are more than one active instances.

	> $ acloud pull

	* Pull logs from the specific instance.

	> $ acloud pull --instance-name "instance-name"

	* Pull a specific log file from a specific instance

	> $ acloud pull --instance-name "instance-name" --file-name "file-name"


	#### setup

	Setup will walk you through the steps needed to set up your local host to
	create a remote or local instance. It will automatically get invoked through
	the create command if we detect some necessary setup steps are required. This
	is a standalone command if the user wants to do setup separate from the create
	command.

	Cheatsheet:

	* Run setup for remote/local instances

	> $ acloud setup

	* Run setup for remote instances only

	> $ acloud setup --gcp-init

	* Run setup for local instances only

	> $ acloud setup --host

	* Force run setup

	> $ acloud setup --force

	* * *

	If you have any questions or feedback, contact [acloud@google.com](mailto:acloud@google.com).

	If you have any bugs or feature requests email them to [buganizer-system+419709@google.com](mailto:buganizer-system+419709@google.com)