Android - Sending data from shell to applications using am tool

If you're a relatively experienced Android developer, for sure you've heard about Intents before. What you might not know is that you can send Intents from the shell using the am (Activity Manager) tool. This is an extremely useful feature to control our app through the shell.

To be able to receive Intents (from shell or from anywhere else), we first need a BroadcastReceiver. Here's a simple example of an Activity and a BroadcastReceiver:

public class MyActivity extends Activity {

    private static final String TAG = MyActivity.class.getSimpleName();

    public static final String INTENT_FILTER = "com.example.myapp.TEST";
    public static final String EXTRA_KEY = "new_text";

    private class MyIntentReceiver extends BroadcastReceiver {
        @Override
        public void onReceive(final Context context, final Intent intent) {
            final String newText = intent.getExtras().getString(EXTRA_KEY);
            Log.d(TAG, "Received new text: " + newText);
        }
    }


    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
        registerReceiver(new MyIntentReceiver(), new IntentFilter(INTENT_FILTER));
    }
}

(For R.layout.main, any layout will do)

So if we now run our app and open a shell in the device (adb shell) we can indeed send data to the app using am as I said above, as follows:

am broadcast -a com.example.myapp.TEST -e "new_text" "New text"

You see that it will execute whatever we coded in the onReceive() method; in this case logging the data to logcat.

06-01 20:37:48.657  2306-2306/com.example.myapp D/MyActivity﹕ Received new text: Some new text

Besides this simple example, am offers a lot of different options to build your intent:

<INTENT> specifications include these flags and arguments:
    [-a <ACTION>] [-d <DATA_URI>] [-t <MIME_TYPE>]
    [-c <CATEGORY> [-c <CATEGORY>] ...]
    [-e|--es <EXTRA_KEY> <EXTRA_STRING_VALUE> ...]
    [--esn <EXTRA_KEY> ...]
    [--ez <EXTRA_KEY> <EXTRA_BOOLEAN_VALUE> ...]
    [--ei <EXTRA_KEY> <EXTRA_INT_VALUE> ...]
    [--el <EXTRA_KEY> <EXTRA_LONG_VALUE> ...]
    [--ef <EXTRA_KEY> <EXTRA_FLOAT_VALUE> ...]
    [--eu <EXTRA_KEY> <EXTRA_URI_VALUE> ...]
    [--ecn <EXTRA_KEY> <EXTRA_COMPONENT_NAME_VALUE>]
    [--eia <EXTRA_KEY> <EXTRA_INT_VALUE>[,<EXTRA_INT_VALUE...]]
    [--ela <EXTRA_KEY> <EXTRA_LONG_VALUE>[,<EXTRA_LONG_VALUE...]]
    [--efa <EXTRA_KEY> <EXTRA_FLOAT_VALUE>[,<EXTRA_FLOAT_VALUE...]]
    [-n <COMPONENT>] [-f <FLAGS>]
    [--grant-read-uri-permission] [--grant-write-uri-permission]
    [--debug-log-resolution] [--exclude-stopped-packages]
    [--include-stopped-packages]
    [--activity-brought-to-front] [--activity-clear-top]
    [--activity-clear-when-task-reset] [--activity-exclude-from-recents]
    [--activity-launched-from-history] [--activity-multiple-task]
    [--activity-no-animation] [--activity-no-history]
    [--activity-no-user-action] [--activity-previous-is-top]
    [--activity-reorder-to-front] [--activity-reset-task-if-needed]
    [--activity-single-top] [--activity-clear-task]
    [--activity-task-on-home]
    [--receiver-registered-only] [--receiver-replace-pending]
    [--selector]
    [<URI> | <PACKAGE> | <COMPONENT>]

I think it is easy to see how this can be very useful for testing, IPC, dynamic behavior, and so on.