• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1page.title=Android Debug Bridge
2parent.title=Tools
3parent.link=index.html
4page.tags="adb"
5@jd:body
6
7<div id="qv-wrapper">
8<div id="qv">
9  <h2>In this document</h2>
10<ol>
11  <li><a href="#issuingcommands">Syntax</a></li>
12  <li><a href="#commandsummary">Commands</a></li>
13  <li><a href="#devicestatus">Querying for Emulator/Device Instances</a></li>
14  <li><a href="#directingcommands">Directing Commands to a Specific Emulator/Device Instance</a></li>
15  <li><a href="#move">Installing an Application</a></li>
16  <li><a href="#forwardports">Forwarding Ports</a></li>
17  <li><a href="#copyfiles">Copying Files to or from an Emulator/Device Instance</a></li>
18  <li><a href="#shellcommands">Issuing Shell Commands</a>
19    <ol>
20      <li><a href="#am">Using activity manager (am)</a></li>
21      <li><a href="#pm">Using package manager (pm)</a></li>
22      <li><a href="#sqlite">Examining sqlite3 databases from a remote shell</a></li>
23      <li><a href="#monkey">UI/Application Exerciser Monkey</a></li>
24      <li><a href="#othershellcommands">Other shell commands</a></li>
25    </ol>
26  </li>
27  <li><a href="#logcat">Enabling logcat logging</a></li>
28  <li><a href="#stopping">Stopping the adb server</a></li>
29</ol>
30
31</div>
32</div>
33
34<p>Android Debug Bridge (adb) is a versatile command line tool that lets you communicate with an
35emulator instance or connected Android-powered device. It is a client-server program that includes
36three components: </p>
37
38<ul>
39  <li>A client, which runs on your development machine. You can invoke a client from a shell
40by issuing an adb command. Other Android tools such as the ADT plugin and DDMS also create
41adb clients. </li>
42  <li>A server, which runs as a background process on your development machine. The server
43manages communication between the client and the adb daemon running on an emulator or device. </li>
44  <li>A daemon, which runs as a background process on each emulator or device instance. </li>
45</ul>
46
47<p>You can find the {@code adb} tool in {@code &lt;sdk&gt;/platform-tools/}.</p>
48
49<p>When you start an adb client, the client first checks whether there is an adb server
50process already running. If there isn't, it starts the server process. When the server starts,
51it binds to local TCP port 5037 and listens for commands sent from adb clients&mdash;all adb
52clients use port 5037 to communicate with the adb server. </p>
53
54<p>The server then sets up connections to all running emulator/device instances. It locates emulator/device instances by scanning odd-numbered ports in the range 5555 to 5585, the range used by emulators/devices. Where the server finds an adb daemon, it sets up a connection to that port. Note that each emulator/device instance acquires a pair of sequential ports &mdash; an even-numbered port for console connections and an odd-numbered port for adb connections. For example: </p>
55
56<p style="margin-left:2em">
57Emulator 1, console: 5554<br/>
58Emulator 1, adb: 5555<br>
59Emulator 2, console: 5556<br>
60Emulator 2, adb: 5557<br>
61and so on...
62</p>
63
64<p>As shown, the emulator instance connected to adb on port 5555 is the same as the instance
65whose console listens on port 5554. </p>
66
67<p>Once the server has set up connections to all emulator instances, you can use adb commands to
68access those instances. Because the server manages connections to emulator/device
69instances and handles commands from multiple adb clients, you can control any emulator/device
70instance from any client (or from a script).</p>
71
72
73<p class="note"><strong>Note:</strong> When you connect a device running Android 4.2.2 or higher
74to your computer, the system shows a dialog asking whether to accept an RSA key that allows
75debugging through this computer. This security mechanism protects user devices because it ensures
76that USB debugging and other adb commands cannot be executed unless you're able to unlock the
77device and acknowledge the dialog. This requires that you have adb version 1.0.31 (available with
78SDK Platform-tools r16.0.1 and higher) in order to debug on a device running Android 4.2.2 or
79higher.</p>
80
81
82<h2 id="issuingcommands">Syntax</h2>
83
84<p>You can issue adb commands from a command line on your development machine or from a script.
85The usage is: </p>
86
87<pre class="no-pretty-print">
88adb [-d|-e|-s &lt;serialNumber&gt;] &lt;command&gt;
89</pre>
90
91<p>If there's only one emulator running or only one device connected, the adb command is
92sent to that device by default. If multiple emulators are running and/or multiple devices are
93attached, you need to use the <code>-d</code>, <code>-e</code>, or <code>-s</code>
94option to specify the target device to which the command should be directed. </p>
95
96
97
98<h2 id="commandsummary">Commands</h2>
99
100<p>The table below lists all of the supported adb commands and explains their meaning and usage. </p>
101
102<p class="table-caption"><strong>Table 1.</strong> Available adb commands</p>
103<table>
104<tr>
105  <th>Category</th>
106  <th>Command</th>
107  <th>Description</th>
108  <th>Comments</th>
109</tr>
110
111<tr>
112<td rowspan="3">Target Device</td>
113<td><code>-d</code></td>
114<td>Direct an adb command to the only attached USB device.</td>
115<td>Returns an error if more than one USB device is attached.</td>
116</tr>
117
118<tr>
119<td><code>-e</code></td>
120<td>Direct an adb command to the only running emulator instance.</td>
121<td>Returns an error if more than one emulator instance is running. </td>
122</tr>
123
124<tr>
125<td><code>-s&nbsp;&lt;serialNumber&gt;</code></td>
126<td>Direct an adb command a specific emulator/device instance, referred to by its adb-assigned serial number (such as "emulator-5556").</td>
127<td>See <a href="#directingcommands">Directing
128Commands to a Specific Emulator/Device Instance</a>.</td>
129</tr>
130
131<tr>
132<td rowspan="3">General</td>
133<td><code>devices</code></td>
134<td>Prints a list of all attached emulator/device instances.</td>
135<td>See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information.</td>
136</tr>
137
138<tr>
139<td><code>help</code></td>
140<td>Prints a list of supported adb commands.</td>
141<td>&nbsp;</td>
142</tr>
143
144<tr>
145<td><code>version</code></td>
146<td>Prints the adb version number. </td>
147<td>&nbsp;</td>
148</tr>
149
150<tr>
151<td rowspan="3">Debug</td>
152<td ><code>logcat&nbsp;[option] [filter-specs]</code></td>
153<td>Prints log data to the screen. </td>
154<td>&nbsp;</td>
155</tr>
156
157<tr>
158<td><code>bugreport</code></td>
159<td>Prints <code>dumpsys</code>, <code>dumpstate</code>, and <code>logcat</code> data to the screen, for the purposes of bug reporting. </td>
160<td>&nbsp;</td>
161</tr>
162
163<tr>
164<td><code>jdwp</code></td>
165<td>Prints a list of available JDWP processes on a given device. </td>
166<td>You can use the <code>forward jdwp:&lt;pid&gt;</code> port-forwarding specification to connect to a specific JDWP process. For example: <br>
167    <code>adb forward tcp:8000 jdwp:472</code><br>
168    <code>jdb -attach localhost:8000</code></p>
169 </td>
170</tr>
171
172<tr>
173<td rowspan=3">Data</td>
174<td><code>install&nbsp;&lt;path-to-apk&gt;</code></td>
175<td>Pushes an Android application (specified as a full path to an .apk file) to an emulator/device. </td>
176<td>&nbsp;</td>
177</tr>
178
179<tr>
180<td><code>pull&nbsp;&lt;remote&gt;&nbsp;&lt;local&gt;</code></td>
181<td>Copies a specified file from an emulator/device instance to your development computer. </td>
182<td>&nbsp;</td>
183</tr>
184
185<tr>
186<td><code>push&nbsp;&lt;local&gt;&nbsp;&lt;remote&gt;</code></td>
187<td>Copies a specified file from your development computer to an emulator/device instance. </td>
188<td>&nbsp;</td>
189</tr>
190
191<tr>
192<td rowspan="2">Ports and Networking</td>
193<td><code>forward&nbsp;&lt;local&gt;&nbsp;&lt;remote&gt;</code></td>
194<td>Forwards socket connections from a specified local port to a specified remote port on the emulator/device instance. </td>
195<td>Port specifications can use these schemes:
196<ul><li><code>tcp:&lt;portnum&gt;</code></li>
197<li><code>local:&lt;UNIX domain socket name&gt;</code></li>
198<li><code>dev:&lt;character device name&gt;</code></li>
199<li><code>jdwp:&lt;pid&gt;</code></li></ul>
200</td>
201</tr>
202
203<tr>
204<td><code>ppp&nbsp;&lt;tty&gt;&nbsp;[parm]...</code></td>
205<td>Run PPP over USB.
206<ul>
207<li><code>&lt;tty&gt;</code> &mdash; the tty for PPP stream. For example <code>dev:/dev/omap_csmi_ttyl</code>. </li>
208<li><code>[parm]... </code> &mdash; zero or more PPP/PPPD options, such as <code>defaultroute</code>, <code>local</code>, <code>notty</code>, etc.</li></ul>
209
210<p>Note that you should not automatically start a PPP connection. </p></td>
211<td></td>
212</tr>
213
214<tr>
215<td rowspan="3">Scripting</td>
216<td><code>get-serialno</code></td>
217<td>Prints the adb instance serial number string.</td>
218<td rowspan="2">See <a href="#devicestatus">Querying for Emulator/Device Instances</a> for more information. </td>
219</tr>
220
221<tr>
222<td><code>get-state</code></td>
223<td>Prints the adb state of an emulator/device instance.</td>
224</td>
225</tr>
226
227<tr>
228<td><code>wait-for-device</code></td>
229<td>Blocks execution until the device is online &mdash; that is, until the instance state is <code>device</code>.</td>
230<td>You can prepend this command to other adb commands, in which case adb will wait until the emulator/device instance is connected before issuing the other commands. Here's an example:
231<pre class="no-pretty-print">adb wait-for-device shell getprop</pre>
232
233Note that this command does <em>not</em> cause adb to wait until the entire system is fully booted. For that reason, you should not prepend it to other commands that require a fully booted system. As an example, the <code>install</code> requires the Android package manager, which is available only after the system is fully booted. A command such as
234
235<pre class="no-pretty-print">adb wait-for-device install &lt;app&gt;.apk</pre>
236
237would issue the <code>install</code> command as soon as the emulator or device instance connected to the adb server, but before the Android system was fully booted, so it would result in an error. </td>
238</tr>
239
240
241
242<tr>
243<td rowspan="2">Server</td>
244<td><code>start-server</code></td>
245<td>Checks whether the adb server process is running and starts it, if not.</td>
246<td>&nbsp;</td>
247</tr>
248
249<tr>
250<td><code>kill-server</code></td>
251<td>Terminates the adb server process.</td>
252<td>&nbsp;</td>
253</tr>
254
255
256
257<tr>
258<td rowspan="2">Shell</td>
259<td><code>shell</code></td>
260<td>Starts a remote shell in the target emulator/device instance.</td>
261<td rowspan="2">See <a href="#shellcommands">Issuing Shell Commands</a> for more information. </td>
262</tr>
263
264<tr>
265<td><code>shell&nbsp;[shellCommand]</code></td>
266<td>Issues a shell command in the target emulator/device instance and then exits the remote shell.</td>
267</tr>
268
269</table>
270
271
272
273
274
275
276
277
278
279
280<h2 id="devicestatus">Querying for Emulator/Device Instances</h2>
281
282<p>Before issuing adb commands, it is helpful to know what emulator/device instances are connected to the adb server. You can generate a list of attached emulators/devices using the <code>devices</code> command: </p>
283
284  <pre class="no-pretty-print">adb devices</pre>
285
286<p>In response, adb prints this status information for each instance:</p>
287
288<ul>
289  <li>Serial number &mdash; A string created by adb to uniquely identify an emulator/device instance by its
290    console port number. The format of the serial number is <code>&lt;type&gt;-&lt;consolePort&gt;</code>.
291    Here's an example serial number: <code>emulator-5554</code></li>
292  <li>State &mdash; The connection state of the instance may be one of the following:
293    <ul>
294      <li><code>offline</code> &mdash; the instance is not connected to adb or is not responding.</li>
295      <li><code>device</code> &mdash; the instance is now connected to the adb server. Note that this state does not
296        imply that the Android system is fully booted and operational, since the instance connects to adb
297        while the system is still booting. However, after boot-up, this is the normal operational state of
298        an emulator/device instance.</li>
299      <li><code>no device</code> &mdash; there is no emulator/device connected.
300    </ul>
301  </li>
302</ul>
303
304<p>The output for each instance is formatted like this: </p>
305
306  <pre class="no-pretty-print">[serialNumber] [state]</pre>
307
308<p>Here's an example showing the <code>devices</code> command and its output:</p>
309
310  <pre class="no-pretty-print">adb devices
311List of devices attached
312emulator-5554&nbsp;&nbsp;device
313emulator-5556&nbsp;&nbsp;device
314emulator-5558&nbsp;&nbsp;device</pre>
315
316
317
318
319
320
321<h2 id="directingcommands">Directing Commands to a Specific Emulator/Device Instance</h2>
322
323<p>If multiple emulator/device instances are running, you must specify a target instance
324when issuing adb commands. To do so, use the <code>-s</code> option in the commands. The usage
325for the <code>-s</code> option is:</p>
326
327<pre class="no-pretty-print">adb -s &lt;serialNumber&gt; &lt;command&gt; </pre>
328
329<p>As shown, you specify the target instance for a command using its adb-assigned serial number.
330You can use the <code>devices</code> command to obtain the serial numbers of running
331emulator/device instances. For example: </p>
332
333<pre class="no-pretty-print">adb -s emulator-5556 install helloWorld.apk</pre>
334
335<p>Note that, if you issue a command without specifying a target emulator/device instance
336while multiple devices are available, adb generates an error.
337
338<p>If you have multiple devices available (hardware or emulated), but only one is an emulator,
339simply use the {@code -e} option to send commands to the emulator. Likewise if there's multiple
340devices but only one hardware device attached, use the {@code -d} option to send commands to
341the hardware device.
342
343
344
345
346<h2 id="move">Installing an Application</h2>
347<p>You can use adb to copy an application from your development computer and install it on an emulator/device instance. To do so, use the <code>install</code> command. With the command, you must specify the path to the .apk file that you want to install:</p>
348
349<pre class="no-pretty-print">adb install &lt;path_to_apk&gt;</pre>
350
351<p>For more information about how to create an .apk file that you can install on an emulator/device
352instance, see <a href="{@docRoot}tools/building/index.html">Building and Running</a></p>
353
354<p>Note that, if you are using the Eclipse IDE and have the ADT plugin installed, you do not need to use adb (or aapt) directly to install your application on the emulator/device. Instead, the ADT plugin handles the packaging and installation of the application for you. </p>
355
356
357
358
359
360
361<h2 id="forwardports">Forwarding Ports</h2>
362
363    <p>You can use the <code>forward</code> command to set up arbitrary port forwarding &mdash; forwarding of requests on a specific host port to a different port on an emulator/device instance. Here's how you would set up forwarding of host port 6100 to emulator/device port 7100:</p>
364<pre class="no-pretty-print">adb forward tcp:6100 tcp:7100</pre>
365    <p>You can also use adb to set up forwarding to named abstract UNIX domain sockets, as illustrated here:</p>
366<pre class="no-pretty-print">adb forward tcp:6100 local:logd </pre>
367
368
369
370
371
372<h2 id="copyfiles">Copying Files to or from an Emulator/Device Instance</h2>
373
374<p>You can use the adb commands <code>pull</code> and <code>push</code> to copy files to
375and from an emulator/device instance. Unlike the <code>install</code> command,
376which only copies an APK file to a specific location, the <code>pull</code> and <code>push</code>
377commands let you copy arbitrary directories and files to any location in an
378emulator/device instance. </p>
379
380<p>To copy a file or directory (and its sub-directories) <em>from</em> the emulator or device, use</p>
381<pre class="no-pretty-print">adb pull &lt;remote&gt; &lt;local&gt;</pre>
382
383<p>To copy a file or directory (and its sub-directories) <em>to</em> the emulator or device, use</p>
384    <pre class="no-pretty-print">adb push &lt;local&gt; &lt;remote&gt;</pre>
385
386<p>In the commands, <code>&lt;local&gt;</code> and <code>&lt;remote&gt;</code> refer to the
387paths to the target files/directory on your development machine (local) and on the
388emulator/device instance (remote). For example: </p>
389<pre class="no-pretty-print">adb push foo.txt /sdcard/foo.txt</pre>
390
391
392
393
394
395
396
397
398
399<h2 id="shellcommands">Issuing Shell Commands</h2>
400
401<p>Adb provides a Unix shell that you can use to run a variety of commands on an emulator
402or connected device. The command binaries are stored in the file system of the emulator or device,
403at <code>/system/bin/...</code>
404
405<p>Two of the most common command tools are <a href="#am">activity manager</a> ({@code am}) and
406<a href="#pm">package manager</a> ({@code pm}).</p>
407
408<p>You can use the <code>shell</code> command to issue commands, with or without entering
409the adb remote shell on the emulator/device. To issue a single command without entering a
410remote shell, use the <code>shell</code> command like this: </p>
411
412  <pre class="no-pretty-print">adb [-d|-e|-s &lt;serialNumber&gt;] shell &lt;shell_command&gt;</pre>
413
414<p>Or enter a remote shell on an emulator/device like this:</p>
415
416  <pre class="no-pretty-print">adb [-d|-e|-s &lt;serialNumber&gt;] shell</pre>
417
418<p>When you are ready to exit the remote shell, press CTRL+D or type
419<code>exit</code>. </p>
420
421
422
423
424
425<h3 id="am">Using activity manager (am)</h3>
426
427<p>Within an adb shell, you can issue commands with the activity manager ({@code am}) tool to
428perform various system actions, such as start an activity, force-stop a process,
429broadcast an intent, modify the device screen properties, and more. While in a shell,
430the syntax is:</p>
431<pre class="no-pretty-print">
432am &lt;command>
433</pre>
434
435<p>You can also issue an activity manager command directly from adb
436without entering a remote shell. For example:</p>
437<pre class="no-pretty-print">
438adb shell am start -a android.intent.action.VIEW
439</pre>
440
441
442<p class="table-caption"><strong>Table 2.</strong> Available activity manager commands</p>
443<table>
444<tr>
445  <th>Command</th>
446  <th>Description</th>
447</tr>
448
449<tr>
450<td><code>
451start [options] &lt;INTENT>
452</code></td>
453<td>Start an {@link android.app.Activity} specified by {@code &lt;INTENT>}. <p>See the
454<a href="#IntentSpec">Specification for &lt;INTENT> arguments</a>.
455<p>Options are:
456<ul>
457    <li>{@code -D}: Enable debugging.
458    <li>{@code -W}: Wait for launch to complete.
459    <li>{@code --start-profiler &lt;FILE>}: Start profiler and send results to {@code &lt;FILE>}.
460    <li>{@code -P &lt;FILE>}: Like <code>--start-profiler</code>,
461        but profiling stops when the app goes idle.
462    <li>{@code -R}: Repeat the activity launch {@code &lt;COUNT>} times.  Prior to each repeat,
463        the top activity will be finished.
464    <li>{@code -S}: Force stop the target app before starting the activity.
465    <li>{@code --opengl-trace}: Enable tracing of OpenGL functions.
466    <li>{@code --user &lt;USER_ID> | current}: Specify which user to run as; if not
467        specified, then run as the current user.
468</ul>
469</td>
470</tr>
471
472<tr>
473<td><code>
474startservice [options] &lt;INTENT>
475</code></td>
476<td>Start the {@link android.app.Service} specified by {@code &lt;INTENT>}. <p>See the
477<a href="#IntentSpec">Specification for &lt;INTENT> arguments</a>.
478<p>Options are:
479<ul>
480    <li>{@code --user &lt;USER_ID> | current}: Specify which user to run as; if not
481        specified, then run as the current user.
482</ul>
483</td>
484</tr>
485
486<tr>
487<td><code>
488force-stop &lt;PACKAGE>
489</code></td>
490<td>Force stop everything associated with {@code &lt;PACKAGE>} (the app's package name).
491</td>
492</tr>
493
494<tr>
495<td><code>
496kill  [options] &lt;PACKAGE>
497</code></td>
498<td> Kill all processes associated with {@code &lt;PACKAGE>}
499  (the app's package name).  This command kills only
500  processes that are safe to kill and that will not impact the user
501  experience.
502  <p>Options are:
503  <ul>
504      <li>{@code --user &lt;USER_ID> | all | current}: Specify user whose processes to kill;
505        all users if not specified.
506  </ul>
507</td>
508</tr>
509
510<tr>
511<td><code>
512kill-all
513</code></td>
514<td>Kill all background processes.
515</td>
516</tr>
517
518<tr>
519<td><code>
520broadcast [options] &lt;INTENT>
521</code></td>
522<td>Issue a broadcast intent. <p>See the
523<a href="#IntentSpec">Specification for &lt;INTENT> arguments</a>.
524<p>Options are:
525<ul>
526    <li>{@code [--user &lt;USER_ID> | all | current]}: Specify which user to send to; if not
527        specified then send to all users.
528</ul>
529</td>
530</tr>
531
532<tr>
533<td><code>
534instrument [options] &lt;COMPONENT>
535</code></td>
536<td>Start monitoring with an {@link android.app.Instrumentation} instance.
537  Typically the target {@code &lt;COMPONENT>}
538  is the form {@code &lt;TEST_PACKAGE>/&lt;RUNNER_CLASS>}.  <p>Options are:
539<ul>
540    <li>{@code -r}: Print raw results (otherwise decode
541        {@code &lt;REPORT_KEY_STREAMRESULT>}).  Use with
542        {@code [-e perf true]} to generate raw output for performance measurements.
543
544    <li>{@code -e &lt;NAME> &lt;VALUE>}: Set argument {@code &lt;NAME>} to {@code &lt;VALUE>}.
545        For test runners a common form is {@code
546        -e &lt;testrunner_flag> &lt;value>[,&lt;value>...]}.
547
548    <li>{@code -p &lt;FILE>}: Write profiling data to {@code &lt;FILE>}.
549
550    <li>{@code -w}: Wait for instrumentation to finish before returning.  Required for
551        test runners.
552
553    <li>{@code --no-window-animation}: Turn off window animations while running.
554    <li>{@code --user &lt;USER_ID> | current}: Specify which user instrumentation runs in;
555        current user if not specified.
556</ul>
557
558</td>
559</tr>
560
561<tr>
562<td><code>
563profile start &lt;PROCESS> &lt;FILE>
564</code></td>
565<td>Start profiler on {@code &lt;PROCESS>}, write results to {@code &lt;FILE>}.
566</td>
567</tr>
568
569<tr>
570<td><code>
571profile stop &lt;PROCESS>
572</code></td>
573<td>Stop profiler on {@code &lt;PROCESS>}.
574</td>
575</tr>
576
577<tr>
578<td style="white-space:nowrap"><code>
579dumpheap [options] &lt;PROCESS> &lt;FILE>
580</code></td>
581<td>Dump the heap of {@code &lt;PROCESS>}, write to {@code &lt;FILE>}. <p>Options are:
582<ul>
583    <li>{@code --user [&lt;USER_ID>|current]}: When supplying a process name,
584        specify user of process to dump; uses current user if not specified.
585    <li>{@code -n}: Dump native heap instead of managed heap.
586</ul>
587</td>
588</tr>
589
590<tr>
591<td><code>
592set-debug-app [options] &lt;PACKAGE>
593</code></td>
594<td>Set application {@code &lt;PACKAGE>} to debug.  <p>Options are:
595<ul>
596    <li>{@code -w}: Wait for debugger when application starts.
597    <li>{@code --persistent}: Retain this value.
598</ul>
599</td>
600</tr>
601
602<tr>
603<td><code>
604clear-debug-app
605</code></td>
606<td>Clear the package previous set for debugging with {@code set-debug-app}.
607</td>
608</tr>
609
610<tr>
611<td><code>
612monitor [options]
613</code></td>
614<td>Start monitoring for crashes or ANRs.  <p>Options are:
615<ul>
616    <li>{@code --gdb}: Start gdbserv on the given port at crash/ANR.
617</ul>
618</td>
619</tr>
620
621<tr>
622<td><code>
623screen-compat [on|off] &lt;PACKAGE>
624</code></td>
625<td>Control <a href="{@docRoot}guide/practices/screen-compat-mode.html">screen
626compatibility</a> mode of {@code &lt;PACKAGE>}.</p>
627</td>
628</tr>
629
630<tr>
631<td><code>
632display-size [reset|&lt;WxH>]
633</code></td>
634<td>Override emulator/device display size.
635This command is helpful for testing your app across different screen sizes by mimicking a small
636screen resolution using a device with a large screen, and vice versa.
637<p>Example:<br><code>am display-size 1280x800</code>
638</td>
639</tr>
640
641<tr>
642<td><code>
643display-density &lt;dpi>
644</code></td>
645<td>Override emulator/device display density.
646This command is helpful for testing your app across different screen densities on high-density
647screen environment using a low density screen, and vice versa.
648<p>Example:<br><code>am display-density 480</code>
649</td>
650</tr>
651
652<tr>
653<td><code>
654to-uri &lt;INTENT>
655</code></td>
656<td>Print the given intent specification as a URI. <p>See the
657<a href="#IntentSpec">Specification for &lt;INTENT> arguments</a>.
658</td>
659</tr>
660
661<tr>
662<td><code>
663to-intent-uri &lt;INTENT>
664</code></td>
665<td>Print the given intent specification as an {@code intent:} URI. <p>See the
666<a href="#IntentSpec">Specification for &lt;INTENT> arguments</a>.
667</td>
668</tr>
669</table>
670
671
672
673
674
675<h4 id="IntentSpec">
676  <a href="" class="expandable" onclick="toggleExpandable(this,'.intents');
677return false">Specification for &lt;INTENT> arguments</a></h4>
678
679<div class="intents" style="display:none">
680
681<p>For activity manager commands that take a {@code &lt;INTENT>} argument, you can
682specify the intent with the following options:</p>
683
684<dl>
685  <dt>{@code -a &lt;ACTION>}</dt>
686      <dd>Specify the intent action, such as "android.intent.action.VIEW".
687      You can declare this only once.
688
689  <dt>{@code -d &lt;DATA_URI>}</dt>
690      <dd>Specify the intent data URI, such as "content://contacts/people/1".
691      You can declare this only once.
692
693  <dt>{@code -t &lt;MIME_TYPE>}</dt>
694      <dd>Specify the intent MIME type, such as "image/png".
695      You can declare this only once.
696
697  <dt>{@code -c &lt;CATEGORY>}</dt>
698      <dd>Specify an intent category, such as "android.intent.category.APP_CONTACTS".
699
700  <dt>{@code -n &lt;COMPONENT>}</dt>
701      <dd>Specify the component name with package name prefix to create an explicit intent, such
702      as "com.example.app/.ExampleActivity".
703
704  <dt>{@code -f &lt;FLAGS>}</dt>
705      <dd>Add flags to the intent, as supported by {@link
706        android.content.Intent#setFlags setFlags()}.
707
708  <dt>{@code --esn &lt;EXTRA_KEY>}</dt>
709      <dd>Add a null extra. This option is not supported for URI intents.
710
711  <dt>{@code -e|--es &lt;EXTRA_KEY> &lt;EXTRA_STRING_VALUE>}</dt>
712      <dd>Add string data as a key-value pair.
713
714  <dt>{@code --ez &lt;EXTRA_KEY> &lt;EXTRA_BOOLEAN_VALUE>}</dt>
715      <dd>Add boolean data as a key-value pair.
716
717  <dt>{@code --ei &lt;EXTRA_KEY> &lt;EXTRA_INT_VALUE>}</dt>
718      <dd>Add integer data as a key-value pair.
719
720  <dt>{@code --el &lt;EXTRA_KEY> &lt;EXTRA_LONG_VALUE>}</dt>
721      <dd>Add long data as a key-value pair.
722
723  <dt>{@code --ef &lt;EXTRA_KEY> &lt;EXTRA_FLOAT_VALUE>}</dt>
724      <dd>Add float data as a key-value pair.
725
726  <dt>{@code --eu &lt;EXTRA_KEY> &lt;EXTRA_URI_VALUE>}</dt>
727      <dd>Add URI data as a key-value pair.
728
729  <dt>{@code --ecn &lt;EXTRA_KEY> &lt;EXTRA_COMPONENT_NAME_VALUE>}</dt>
730      <dd>Add a component name, which is converted and passed as
731      a {@link android.content.ComponentName} object.
732
733  <dt>{@code --eia &lt;EXTRA_KEY> &lt;EXTRA_INT_VALUE>[,&lt;EXTRA_INT_VALUE...]}</dt>
734      <dd>Add an array of integers.
735
736  <dt>{@code --ela &lt;EXTRA_KEY> &lt;EXTRA_LONG_VALUE>[,&lt;EXTRA_LONG_VALUE...]}</dt>
737      <dd>Add an array of longs.
738
739  <dt>{@code --efa &lt;EXTRA_KEY> &lt;EXTRA_FLOAT_VALUE>[,&lt;EXTRA_FLOAT_VALUE...]}</dt>
740      <dd>Add an array of floats.
741
742  <dt>{@code --grant-read-uri-permission}</dt>
743      <dd>Include the flag {@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION}.
744
745  <dt>{@code --grant-write-uri-permission}</dt>
746      <dd>Include the flag {@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION}.
747
748  <dt>{@code --debug-log-resolution}</dt>
749      <dd>Include the flag {@link android.content.Intent#FLAG_DEBUG_LOG_RESOLUTION}.
750
751  <dt>{@code --exclude-stopped-packages}</dt>
752      <dd>Include the flag {@link android.content.Intent#FLAG_EXCLUDE_STOPPED_PACKAGES}.
753
754  <dt>{@code --include-stopped-packages}</dt>
755      <dd>Include the flag {@link android.content.Intent#FLAG_INCLUDE_STOPPED_PACKAGES}.
756
757  <dt>{@code --activity-brought-to-front}</dt>
758      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_BROUGHT_TO_FRONT}.
759
760  <dt>{@code --activity-clear-top}</dt>
761      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}.
762
763  <dt>{@code --activity-clear-when-task-reset}</dt>
764      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET}.
765
766  <dt>{@code --activity-exclude-from-recents}</dt>
767      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS}.
768
769  <dt>{@code --activity-launched-from-history}</dt>
770      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_LAUNCHED_FROM_HISTORY}.
771
772  <dt>{@code --activity-multiple-task}</dt>
773      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_MULTIPLE_TASK}.
774
775  <dt>{@code --activity-no-animation}</dt>
776      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_NO_ANIMATION}.
777
778  <dt>{@code --activity-no-history}</dt>
779      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_NO_HISTORY}.
780
781  <dt>{@code --activity-no-user-action}</dt>
782      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_NO_USER_ACTION}.
783
784  <dt>{@code --activity-previous-is-top}</dt>
785      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_PREVIOUS_IS_TOP}.
786
787  <dt>{@code --activity-reorder-to-front}</dt>
788      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_REORDER_TO_FRONT}.
789
790  <dt>{@code --activity-reset-task-if-needed}</dt>
791      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_RESET_TASK_IF_NEEDED}.
792
793  <dt>{@code --activity-single-top}</dt>
794      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_SINGLE_TOP}.
795
796  <dt>{@code --activity-clear-task}</dt>
797      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TASK}.
798
799  <dt>{@code --activity-task-on-home}</dt>
800      <dd>Include the flag {@link android.content.Intent#FLAG_ACTIVITY_TASK_ON_HOME}.
801
802  <dt>{@code --receiver-registered-only}</dt>
803      <dd>Include the flag {@link android.content.Intent#FLAG_RECEIVER_REGISTERED_ONLY}.
804
805  <dt>{@code --receiver-replace-pending}</dt>
806      <dd>Include the flag {@link android.content.Intent#FLAG_RECEIVER_REPLACE_PENDING}.
807
808  <dt>{@code --selector}</dt>
809      <dd>Requires the use of {@code -d} and {@code -t} options to set the intent data and type.
810
811  <dt>{@code &lt;URI> &lt;COMPONENT> &lt;PACKAGE>}</dt>
812      <dd>You can directly specify a URI, package name, and component name when not qualified
813      by one of the above options. When an argument is unqualified, the tool assumes the argument
814      is a URI if it contains a ":" (colon); it assumes the argument is a component name if it
815      contains a "/" (forward-slash); otherwise it assumes the argument is a package name.
816
817</dl>
818</div><!-- end 'intents' -->
819<script>
820  $(window).hashchange( function(){
821    if ((location.hash == "#IntentSpec") && !($("#IntentSpec a").hasClass("expanded"))) {
822      $("#IntentSpec a").click();
823    }
824  });
825</script>
826
827
828
829<h3 id="pm">Using package manager (pm)</h3>
830
831<p>Within an adb shell, you can issue commands with the package manager ({@code pm}) tool to
832perform actions and queries on application packages installed on the device. While in a shell,
833the syntax is:</p>
834<pre class="no-pretty-print">
835pm &lt;command>
836</pre>
837
838<p>You can also issue a package manager command directly from adb
839without entering a remote shell. For example:</p>
840<pre class="no-pretty-print">
841adb shell pm uninstall com.example.MyApp
842</pre>
843
844<p class="table-caption"><strong>Table 3.</strong> Available package manager commands.</p>
845<table>
846<tr>
847  <th>Command</th>
848  <th>Description</th>
849</tr>
850
851<tr>
852<td><code>
853list packages [options] &lt;FILTER>
854</code></td>
855<td>Prints all packages, optionally only
856  those whose package name contains the text in {@code &lt;FILTER>}.  <p>Options:
857<ul>
858    <li>{@code -f}: See their associated file.
859    <li>{@code -d}: Filter to only show disabled packages.
860    <li>{@code -e}: Filter to only show enabled packages.
861    <li>{@code -s}: Filter to only show system packages.
862    <li>{@code -3}: Filter to only show third party packages.
863    <li>{@code -i}: See the installer for the packages.
864    <li>{@code -u}: Also include uninstalled packages.
865    <li>{@code --user &lt;USER_ID>}: The user space to query.
866</ul>
867</td>
868</tr>
869
870<tr>
871<td><code>
872list permission-groups
873</code></td>
874<td>Prints all known permission groups.
875</td>
876</tr>
877
878<tr>
879<td><code>
880list permissions [options] &lt;GROUP>
881</code></td>
882<td>Prints all known permissions, optionally only
883  those in {@code &lt;GROUP>}.  <p>Options:
884<ul>
885    <li>{@code -g}: Organize by group.
886    <li>{@code -f}: Print all information.
887    <li>{@code -s}: Short summary.
888    <li>{@code -d}: Only list dangerous permissions.
889    <li>{@code -u}: List only the permissions users will see.
890</ul>
891</td>
892</tr>
893
894<tr>
895<td><code>
896list instrumentation
897</code></td>
898<td>List all test packages.  <p>Options:
899  <ul>
900    <li>{@code -f}: List the APK file for the test package.
901    <li>{@code &lt;TARGET_PACKAGE>}: List test packages for only this app.
902  </ul>
903</td>
904</tr>
905
906<tr>
907<td><code>
908list features
909</code></td>
910<td>Prints all features of the system.
911</td>
912</tr>
913
914<tr>
915<td><code>
916list libraries
917</code></td>
918<td>Prints all the libraries supported by the current device.
919</td>
920</tr>
921
922<tr>
923<td><code>
924list users
925</code></td>
926<td>Prints all users on the system.
927</td>
928</tr>
929
930<tr>
931<td><code>
932path &lt;PACKAGE>
933</code></td>
934<td>Print the path to the APK of the given {@code &lt;PACKAGE>}.
935</td>
936</tr>
937
938<tr>
939<td><code>
940install [options]  &lt;PATH>
941</code></td>
942<td>Installs a package (specified by {@code &lt;PATH>}) to the system.  <p>Options:
943  <ul>
944    <li>{@code -l}: Install the package with forward lock.
945    <li>{@code -r}: Reinstall an exisiting app, keeping its data.
946    <li>{@code -t}: Allow test APKs to be installed.
947    <li>{@code -i &lt;INSTALLER_PACKAGE_NAME>}: Specify the installer package name.
948    <li>{@code -s}: Install package on the shared mass storage (such as sdcard).
949    <li>{@code -f}: Install package on the internal system memory.
950    <li>{@code -d}: Allow version code downgrade.
951  </ul>
952</td>
953</tr>
954
955<tr>
956<td><code>
957uninstall [options] &lt;PACKAGE>
958</code></td>
959<td>Removes a package from the system. <p>Options:
960  <ul>
961    <li>{@code -k}: Keep the data and cache directories around after package removal.
962  </ul>
963</td>
964</tr>
965
966<tr>
967<td><code>
968clear &lt;PACKAGE>
969</code></td>
970<td>Deletes all data associated with a package.
971</td>
972</tr>
973
974<tr>
975<td><code>
976enable &lt;PACKAGE_OR_COMPONENT>
977</code></td>
978<td>Enable the given package or component (written as "package/class").
979</td>
980</tr>
981
982<tr>
983<td><code>
984disable &lt;PACKAGE_OR_COMPONENT>
985</code></td>
986<td>Disable the given package or component (written as "package/class").
987</td>
988</tr>
989
990<tr>
991<td style="white-space:nowrap"><code>
992disable-user [options] &lt;PACKAGE_OR_COMPONENT>
993</code></td>
994<td><p>Options:
995  <ul>
996    <li>{@code --user &lt;USER_ID>}: The user to disable.
997  </ul>
998</td>
999</tr>
1000
1001<tr>
1002<td><code>
1003grant &lt;PACKAGE_PERMISSION>
1004</code></td>
1005<td>Grant permissions
1006  to applications.  Only optional permissions the application has
1007  declared can be granted.
1008</td>
1009</tr>
1010
1011<tr>
1012<td><code>
1013revoke &lt;PACKAGE_PERMISSION>
1014</code></td>
1015<td>Revoke permissions
1016  to applications.  Only optional permissions the application has
1017  declared can be revoked.
1018</td>
1019</tr>
1020
1021<tr>
1022<td><code>
1023set-install-location &lt;LOCATION>
1024</code></td>
1025<td>Changes the default install location. Location values:
1026<ul>
1027    <li>{@code 0}: Auto&mdash;Let system decide the best location.
1028    <li>{@code 1}: Internal&mdash;install on internal device storage.
1029    <li>{@code 2}: External&mdash;install on external media.
1030</ul>
1031<p class="note"><strong>Note:</strong> This is only intended for debugging; using this can cause
1032  applications to break and other undesireable behavior.</p>
1033</td>
1034</tr>
1035
1036<tr>
1037<td><code>
1038get-install-location
1039</code></td>
1040<td>Returns the current install location. Return values:
1041<ul>
1042  <li>{@code 0 [auto]}: Lets system decide the best location
1043  <li>{@code 1 [internal]}: Installs on internal device storage
1044  <li>{@code 2 [external]}: Installs on external media
1045</ul>
1046</td>
1047</tr>
1048
1049<tr>
1050<td><code>
1051set-permission-enforced &lt;PERMISSION> [true|false]
1052</code></td>
1053<td>Specifies whether the given permission should be enforced.
1054</td>
1055</tr>
1056
1057<tr>
1058<td><code>
1059trim-caches &lt;DESIRED_FREE_SPACE>
1060</code></td>
1061<td>Trim cache files to reach the given free space.
1062</td>
1063</tr>
1064
1065<tr>
1066<td><code>
1067create-user &lt;USER_NAME>
1068</code></td>
1069<td>Create a new user with the given {@code &lt;USER_NAME>},
1070  printing the new user identifier of the user.
1071</td>
1072</tr>
1073
1074<tr>
1075<td><code>
1076remove-user &lt;USER_ID>
1077</code></td>
1078<td>Remove the user with the given {@code &lt;USER_IDENTIFIER>},
1079  deleting all data associated with that user
1080</td>
1081</tr>
1082
1083<tr>
1084<td><code>
1085get-max-users
1086</code></td>
1087<td>Prints the maximum number of users supported by the device.
1088</td>
1089</tr>
1090
1091</table>
1092
1093
1094
1095
1096
1097
1098
1099<h3 id="sqlite">Examining sqlite3 databases from a remote shell</h3>
1100
1101<p>From an adb remote shell, you can use the
1102<a href="http://www.sqlite.org/sqlite.html">sqlite3</a> command-line program to
1103manage SQLite databases created by Android applications. The
1104<code>sqlite3</code> tool includes many useful commands, such as
1105<code>.dump</code> to print out the contents of a table and
1106<code>.schema</code> to print the SQL CREATE statement for an existing table.
1107The tool also gives you the ability to execute SQLite commands on the fly.</p>
1108
1109<p>To use <code>sqlite3</code>, enter a remote shell on the emulator instance, as described above, then invoke the tool using the <code>sqlite3</code> command. Optionally, when invoking <code>sqlite3</code> you can specify the full path to the database you want to explore. Emulator/device instances store SQLite3 databases in the folder <code><span chatdir="1"><span chatindex="259474B4B070F261">/data/data/<em>&lt;package_name&gt;</em>/databases</span></span>/</code>. </p>
1110
1111<p>Here's an example: </p>
1112
1113<pre class="no-pretty-print">adb -s emulator-5554 shell
1114# sqlite3 /data/data/com.example.google.rss.rssexample/databases/rssitems.db
1115SQLite version 3.3.12
1116Enter &quot;.help&quot; for instructions
1117<em>.... enter commands, then quit...</em>
1118sqlite&gt; .exit </pre>
1119
1120<p>Once you've invoked <code>sqlite3</code>, you can issue <code>sqlite3</code> commands in the shell. To exit and return to the adb remote shell, use <code>exit</code> or <code>CTRL+D</code>.
1121
1122
1123
1124
1125
1126
1127<h3 id="monkey">UI/Application Exerciser Monkey</h3>
1128
1129<p>The Monkey is a program that runs on your emulator or device and generates pseudo-random
1130streams of user events such as clicks, touches, or gestures, as well as a number of system-level
1131events.  You can use the Monkey to stress-test applications that you are developing,
1132in a random yet repeatable manner.</p>
1133
1134<p>The simplest way to use the monkey is with the following command, which launches your
1135application and sends 500 pseudo-random events to it.</p>
1136
1137<pre class="no-pretty-print">adb shell monkey -v -p your.package.name 500</pre>
1138
1139<p>For more information about command options for Monkey, see the complete
1140<a href="{@docRoot}tools/help/monkey.html" title="monkey">UI/Application Exerciser Monkey</a> documentation page.</p>
1141
1142
1143
1144
1145
1146<h3 id="othershellcommands">Other shell commands</h3>
1147
1148<p>For a list of all the available shell programs, use the following command:</p>
1149
1150<pre class="no-pretty-print">adb shell ls /system/bin</pre>
1151
1152<p>Help is available for most of the commands. </p>
1153
1154<p>Table 4 lists some of the more common adb shell commands.</p>
1155
1156<p class="table-caption"><strong>Table 4.</strong> Some other adb shell commands</p>
1157<table>
1158<tr>
1159  <th>Shell Command</th>
1160  <th>Description</th>
1161  <th>Comments</th>
1162</tr>
1163
1164<tr>
1165<td><code>dumpsys</code></td>
1166<td>Dumps system data to the screen.</td>
1167<td rowspan=4">The <a href="{@docRoot}tools/debugging/ddms.html">Dalvik Debug Monitor Server</a>
1168(DDMS) tool offers integrated debug environment that you may find easier to use.</td>
1169</tr>
1170
1171<tr>
1172<td><code>dumpstate</code></td>
1173<td>Dumps state to a file.</td>
1174</tr>
1175
1176<tr>
1177<td><code>logcat&nbsp;[option]...&nbsp;[filter-spec]...</code></td>
1178<td>Enables system and app logging and prints output to the screen. </td>
1179</tr>
1180
1181<tr>
1182<td><code>dmesg</code></td>
1183<td>Prints kernel debugging messages to the screen. </td>
1184</tr>
1185
1186<tr>
1187<td><code>start</code></td>
1188<td>Starts (restarts) an emulator/device instance.</td>
1189<td>&nbsp;</td>
1190</tr>
1191
1192<tr>
1193<td><code>stop</code></td>
1194<td>Stops execution of an emulator/device instance.</td>
1195<td>&nbsp;</td>
1196</tr>
1197
1198</table>
1199
1200
1201
1202
1203
1204
1205
1206<a name="stdout"></a>
1207<a name="usinglogcat"></a>
1208<a name="outputformat"></a>
1209<a name="filteringoutput"></a>
1210<a name="stdout"></a>
1211<a name="logcatoptions"></a>
1212
1213<h2 id="logcat">Enabling logcat logging</h2>
1214
1215<p>The Android logging system provides a mechanism for collecting and viewing system debug output. Logs from various applications and portions of the system are collected in a series of circular buffers, which then can be viewed and filtered by the <code>logcat</code> command.</p>
1216
1217<p>You can use the <code>logcat</code> command to view and follow the contents of the system's log buffers. The general usage is:</p>
1218
1219<pre class="no-pretty-print">[adb] logcat [option] ... [filter-spec] ...</pre>
1220
1221<p>You can use the <code>logcat</code> command from your development computer  or from a remote adb shell in an emulator/device instance. To view log output in your development computer, you use</p>
1222
1223<pre class="no-pretty-print">adb logcat</pre>
1224
1225<p>and from a remote adb shell you use</p>
1226
1227<pre class="no-pretty-print">logcat</pre>
1228
1229<p>See <a href="{@docRoot}tools/debugging/debugging-log.html">Reading and Writing Logs</a> for complete information about logcat commend options and filter specifications.</p>
1230
1231
1232
1233
1234
1235<h2 id="stopping">Stopping the adb server</h2>
1236
1237<p>In some cases, you might need to terminate the adb server process and then restart it. For example, if adb does not respond to a command, you can terminate the server and restart it and that may resolve the problem. </p>
1238
1239<p>To stop the adb server, use the <code>kill-server</code> command.
1240You can then restart the server by issuing any other adb command. </p>
1241
1242
1243