Setting up the CLI from the Build Environment

To more easily test and debug the core logic, it's possible to set up the standard Android Studio dev environment to run the interactive CLI directly. This setup fully supports breakpoints and makes it significantly faster to iterate on certain changes, especially for developers without access to physical android devices.

This guide assumes that you have a build environment configured which will produce CommCare APK builds successfully in Android Studio. To assist with those steps, please follow the repository README.

Setup

Setting up a build configuration

In Android Studio, navigate to the menu Run -> Edit Configurations.

Using the "+" Menu, create a new JAR Application configuraton

Under the "Before Launch" section, add a "Run Gradle Task" step, which runs this task: :commcare-core:cliJar. This will generate the commcare-cli.jar file as a build output.

Identifying the JAR Path

Under the "Path to Jar" section, enter the absolute file path on your machine for the following folder (where commcare-core is a peer directory to the commcare-android directory as is configured in the setup instructions):

commcare-core/build/libs/commcare-cli.jar

So if your workspace for the current project (containing commcare-core and `commcare-android) was, for instance

/home/myuser/workspace/

the path to jar would be

/home/myuser/workspace/commcare-core/build/libs/commcare-cli.jar

or on a Windows machine if your workspace was in

C:\Users\myuser\workspaces\

the path to jar would be

C:\Users\myuser\workspaces\commcare-core\build\libs\commcare-cli.jar

Note: Until you've run the build once you will see a warning that the JAR file doesn't exist.

Setting program arguments

Any parameter that could be passed over the command line can be used in the Program arguments setting. The most common example is as follows:

The basic "Program Arguments" for the build require three inputs

1. [app_path] - A URL or local filepath to a CCZ image
2. [username] - The mobile username for a user to run the app as. Will be restored over network as if it was typed into a real device
3. [password] - The password for the mobile username. Will be restored over network as if it was typed into a real device.

With those arguments available, the program arguments to run a CCZ file as a specific user are

play "[app_path]" [username] [password]

For example

play "/home/myuser/testapp.ccz" ada 1k2r23R3234

Acquiring an app path

There are two basic ways to set up an app path, the most straightforward is to use a locally downloaded ccz portable app image.

Alternatively you can pass a url to a .ccz file, but note that it must be a direct, statically available file.

To obtain a ccz image for an app hosted on an installation of CommCare HQ, you can use the following Bookmarklet while you are in the App Builder for the app you want to download.

javascript:(function(){ var url = window.location.href;var re = /(^[^\/]*\/\/[^\/]*\/)a\/([^\/]*)\/.*view\/([^\/]+)[\/]*.*$/ig;var pieces = re.exec(url);if(pieces != null) { window.prompt("Copy/Paste the URL below", pieces[1] + "a/" + pieces[2] + "/apps/api/download_ccz/?app_id=" + pieces[3] + "#hack=commcare.ccz"); }})();

This will produce a URL which can be used to grab the latest saved copy of the application.