README.md
1# **Acloud Manual**
2
3## **Acloud**
4
5Acloud is a command line tool that assists users to create an Android Virtual
6Device (AVD).
7
8## **Table of Contents**
9
101. [Environment Setup](#Environment-Setup)
112. [Basic Usage](#Basic-Usage)
12
13### **Environment Setup**
14
15Add acloud to your $PATH by lunching your environment.
16
17* Source envsetup.sh from the root of the android source checkout
18
19```
20$ source build/envsetup.sh
21```
22
23* Run lunch for an AVD target
24
25```
26$ lunch aosp_cf_x86_phone-userdebug
27```
28
29
30You should now be able to call acloud from anywhere.
31
32> If you're a googler, please check https://goto.google.com/acloud-googler-setup
33> to ensure a smooth setup experience.
34
35### **Basic Usage**
36
37Acloud commands take the following form:
38
39**acloud <command> <optional arguments>**
40
41Available commands:
42
43* [create](#create)
44* [list](#list)
45* [delete](#delete)
46* [reconnect](#reconnect)
47* [setup](#setup)
48
49#### **create**
50
51Create is the main entry point in creating an AVD, supporting both remote
52instance (running on a virtual machine in the cloud) and local instance
53(running on your local host) use cases. You also have the option to use
54a locally built image or an image from the Android Build servers.
55
56**Disclaimer: Creation of a cuttlefish local instance is not formally supported, please use at your own risk.**
57
58Here's a quick cheat-sheet for the 4 use cases:
59
60* Remote instance using an Android Build image (LKGB (Last Known Good Build)
61for cuttlefish phone target in the branch of your repo)
62
63> $ acloud create
64
65* Remote instance using a locally built image (use `m dist` to build the image)
66
67> $ acloud create --local-image [local-image-path]
68
69* Local instance using an Android Build image (LKGB for cuttlefish phone
70target in the branch of your repo)
71
72> $ acloud create --local-instance
73
74* Local instance using a locally built image (use `m dist` to build the image)
75
76> $ acloud create --local-instance --local-image
77
78When specifying an Android Build image, you can specify the branch,
79target and/or build id (e.g. `--branch my_branch`). Acloud will assume the
80following if they're not specified:
81
82* `--branch`: The branch of the repo you're running the acloud command in, e.g.
83in an aosp repo on the master branch, acloud will infer the aosp-master branch.
84
85* `--build-target`: Defaults to the phone target for cuttlefish (e.g.
86aosp\_cf\_x86\_phone-userdebug in aosp-master).
87
88* `--build-id`: Default to the Last Known Good Build (LKGB) id for the branch and
89target set from above.
90
91Additional helpful create options are:
92
93* `--flavor`: This can be one of phone, auto, wear, tv, iot, tablet and 3g.
94This will be used to choose the default hw properties and infer build target
95if not specified.
96
97* `--autoconnect`: This defaults to true and upon creation of a remote instance,
98creates a ssh tunnel to enable adb and vnc connection to the instance. For the
99local instance, acloud will just invoke the vnc client. If you don't want
100autoconnect, you can pass in `--no-autoconnect`
101
102* `--hw-property`: This is a string where you can specify the different
103properties of the AVD. You can specify the cpu, resolution, dpi, memory,and/or
104disk in a key:value format like so:
105`cpu:2,resolution:1280x700,dpi:160,memory:2g,disk:2g`
106
107The full list of options are available via `--help`
108
109> $ acloud create --help
110
111#### **list**
112
113List will retrieve all the remote instances you've created in addition to
114any local instances created as well.
115
116Cheatsheet:
117
118* List will show device IP address, adb port and instance name.
119
120> $ acloud list
121
122* List -v will show more detail info on the list.
123
124> $ acloud list -v
125
126
127#### **delete**
128
129Delete will stop your remote and local instances. Acloud will find all
130instances created by you and stop them. If more than one instance is found
131(remote or local), you will be prompted to select which instance you would
132like to stop.
133
134Cheatsheet:
135
136* Delete sole instance or prompt user with list of instances to delete.
137
138> $ acloud delete
139
140* Delete all instances
141
142> $ acloud delete --all
143
144* Delete a specific instance
145
146> $ acloud delete --instance-names [instance-name]
147
148#### **reconnect**
149
150Reconnect will re-establish ssh tunnels for adb/vnc port forwarding for all
151remote instance created by you. It will then look for any devices missing in
152`adb devices` and reconnect them to adb. Lastly it will restart vnc for all
153devices that don't already have vnc started for them.
154
155Cheatsheet:
156
157* Reconnect sole instance or prompt user with list of instances to reconnect.
158
159> $ acloud reconnect
160
161* Reconnect all instances
162
163> $ acloud reconnect --all
164
165* Reconnect a specific instance
166
167> $ acloud reconnect --instance-names [instance-name]
168
169
170#### **setup**
171
172Setup will walk you through the steps needed to set up your local host to
173create a remote or local instance. It will automatically get invoked through
174the create command if we detect some necessary setup steps are required. This
175is a standalone command if the user wants to do setup separate from the create
176command.
177
178Cheatsheet:
179
180* Run setup for remote/local instances
181
182> $ acloud setup
183
184* Run setup for remote instances only
185
186> $ acloud setup --gcp-init
187
188* Run setup for local instances only
189
190> $ acloud setup --host
191
192* Force run setup
193
194> $ acloud setup --force
195
196* * *
197
198If you have any questions or feedback, contact [acloud@google.com](mailto:acloud@google.com).
199
200If you have any bugs or feature requests, [go/acloud-bug](http://go/acloud-bug).
201