CommCare CLI

NOTE: This is documentation for an in-development feature that will change rapidly and may be out of date.

CommCare's CLI (Command Line Interface) is a tool that lets a user run a CommCare application on the command line without a mobile device or other platform.

It is helpful for replicating and debugging issues with application logic and/or getting more in-depth info as to what is going on behind-the-scenes when running an app.

Getting Started

The CLI is packaged as a java jar file that is built along side the mobile applications. You'll need (and you likely have) java installed on your local computer for it to work. If you don't just grab the latest version (Java 7 as of this writing) from Oracle.

You can fetch the latest CLI online a the jenkins build server. The current version is at https://jenkins.dimagi.com/job/commcare-android-artifacts/ but you can also find the CLI for specific builds/releases (starting with 2.23) by finding their build on Jenkins.

The jar located in the artifact outputs at build/libs/commcare-cli.jar

Note that for builds/releases from 2.23 through 2.28, navigate to https://jenkins.dimagi.com/job/commcare-mobile-2.2#/. Look under the "Last Successful Artifacts" for build/libs/commcare-cli.jar. If you do not find this, then look on the left under the Build History section, and click on the desired build/release from there (ex: CommCare 2.25.5). On the next page, you will find build/libs/commcare-cli.jar under the "Last Successful Artifacts" section.

For builds/releases from 2.29 onwards, navigate to https://jenkins.dimagi.com/job/commcare-core-2.2#/. Look under the "Last Successful Artifacts" for build/libs/commcare-cli.jar. If you do not find this, then look on the left under the Build History section, and click on the desired build/release from there. On the next page, you will find build/libs/commcare-cli.jar under the "Last Successful Artifacts" section.

You should download this jar and place it onto your computer.

You will also need an application build from CommCare HQ. You can either manually download the commcare.ccz file of the app you want to run or download it directly from CommCare via the CLI (instructions below).

Finally you'll need to make sure you can run Java from a terminal. Start a terminal and type

java -version

and make sure you get appropriate output. If the terminal says java isn't found, you should either download it or make sure it is on your PATH.

Running the CLI

With a terminal in the same working directory as the commcare-cli.jar file, the basic way to start up an app is

java -jar commcare-cli.jar play /path/or/url/to/commcare.ccz username password

The arguments being

play - run a commcare application interactively (only play is useful/supported currently)
/path/or/url/to/commcare.ccz - The file system path to a CommCare application package, or a link to the package on CommCare HQ. To use the current application build, use the following format: https://www.commcarehq.org/a/[domain]/apps/api/download_ccz/?app_id=[app_id]#hack=commcare.ccz
username - the username of a user to restore to the application. This is the same user you log into with on the mobile phone, and does not include the @domain.commcarehq.org suffix.
password - The user's password

The CLI will first start up the app provided, and will provide errors if the application files are not well structured.

It will then pull down the user data of the provided user from HQ (or whatever server is encoded in the commcare.ccz file). If network fails or the restore data is not structured correctly, the app will fail and provide the appropriate error.

If you have a user data restore file on your local machine you can restore based on that instead of providing a username and password with

java -jar commcare-cli.jar play /path/to/commcare.ccz -r /path/to/restore.xml

Working with the CLI

Once you startup the CLI you will be shown the root module list:

To select a module, type the associated number and hit enter. You will then either see a case list or more modules / forms.

Once you enter form entry, the CLI will display the current session state. This will include any modules or case IDs you've selected before entering the form.

The app follows a single CommCare session, IE: Home screen -> Form Entry. After a form is entered, its XML is printed into the terminal for inspection. The form is not, however, currently parsed (IE: case updates won't happen) or sent to the server, so you do not need to be concerned about mutating data on the server.

Commands

During usage you can invoke commands to inspect and learn more about the app and data. Commands always start with a colon, like :exit

These commands are changing frequently and in the future it will be possible to get the list and usage of each command documented directly in the app, and the command sets will be unified

The app is roughly divided into two sections with different command sets available in each. Optional flags are (in parens)

Pre-Form-Entry (menus, case lists, etc)

:exit / :quit - Terminate the session and close the CLI app
:update (-f) - Update the application live against the newest version on the server. -f optional flag to grab the newest build instead of the newest starred build
:home - Navigate to the home menu of the app
:lang <lang> - change the language to <lang> (e.g. :lang en)
:stack - Show the current session frame stack
:back - Move to the previous menu

While viewing a Case List (note - No Colon)

debug (item) - Provides a list of all of the expressions evaluated for row #(item)
debug list - Provides a trace of the xpath expression that was evaluated to filter the case list, and why all possible members of that list were included/excluded

During Form Entry

:next - Skip the current question and navigate to the next
:back - Move to the previous question
:quit - Exit form entry
:print (instanceref) - Print the XML of the data instance for the current form directly in the terminal. instanceref is an instance connector of an abstract instance to print instead, ie: print jr://instance/casedb
:eval (xpathexpression) - Evaluates an XPath expression and print out the resulting value. If xpathexpression is not provided, the terminal enters interactive mode which allows you to evaluate expressions by just typing them and pressing return.
:relevant - Prints the evaluation trace of the expression for the current question's display condition
:debug - Toggles debug mode off/on. When debug mode is enabled, the evaluation trace for any xpath expressions requested will be printed after the value is printed.
:entry-session - shows current form entry session. You can copy this string and restore to that spot in form entry using the ':replay' command.
:replay (form entry session string) - replays the form entry session provided, which should be acquired by the 'entry-session' command. Safest to run this command right when you open the form.

The :eval command is especially helpful. While in eval mode you can run arbitrary XPath expressions and perform introspection on form and case data

Eval in form entry

:eval
 
> 1 + 1
2


> print(instance("casedb")/casedb/case[@case_id = "42314d2d-43bc-403c-8c22-b896b5209ec5"])
<?xml version="1.0" encoding="UTF-8"?>
<case case_id="42314d2d-43bc-403c-8c22-b896b5209ec5" case_type="mother"
  owner_id="88ae5c75c608eeff1e29a3f13dc52481" status="open">
  <case_name>Jessica Smith</case_name>
  <date_opened>2016-10-06</date_opened>
  <last_modified>2016-10-06</last_modified>
  <dob>1980-05-25</dob>
  <paeds_program>no</paeds_program>
  <m2m_first_contact_date>2016-10-06</m2m_first_contact_date>
  <userid>88ae5c75c608eeff1e29a3f13dc52481</userid>
  <adolescent_program>no</adolescent_program>
  ...
</case>
 
> doc('selected')
--------------------
selected
--------------------
Behavior:  Checks to see if a value was selected from a multiselect question. You cannot just do /data/my_question = "my_value_1" - this will fail if both "my_value_1" and "my_value_2" were selected.
Return: True if that particular value was selected.  Otherwise false.
Arguments:  Two arguments, the multi-select question and the value to check.
Syntax: selected(my_question, value_to_check)
Example:  selected(/data/my_multi_select_question, "my_value_4").

If you find yourself needing to return to the same place in a form constantly or debug form linking then you might like the form replaying CLI feature.

To print out all the answers you've entered so far:

Getting the form entry session

:entry-session
((/data/anc[1]/anc1_questions[1]/anc1_visit_done[1]) (VALUE) (yes))

To replay those answers again once you reopen the form:

Replaying a form entry session

:replay ((/data/anc[1]/anc1_questions[1]/anc1_visit_done[1]) (VALUE) (yes))

And supposedly if you add a 'return' character in just the right place you between form entry sessions you can use this to debug form linking.

Tips and Tricks

App Bookmarklet

To make it easier to get the CCZ for a an app you can use the following javascript bookmarklet

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"); }})();

Drag/drop the text of the bookmarklet into your bookmark bar to create a shortcut. When you click on this shortcut from any page in HQ while you are viewing an specific app, it will pop up the URL to copy/paste in order to download the latest build of that app.

Note that if your app uses multimedia, you need to use an app id from a build (e.g., cut from one of the links on the deploy page) rather than the id for the app itself.

You can provide the .ccz link itself directly as an argument to the command line, meaning you won't have to download anything from HQ to test an app, so to test an app from an HQ page like

https://www.commcarehq.org/a/corpora/apps/view/cc3315e9bdb5719c7b57d6ee5b19e797/modules-0/forms-9/source/

just click the bookmarket, copy the app and paste it into the command line call directly, IE:

java -jar commcare-cli.jar play https://www.commcarehq.org/a/corpora/apps/api/download_ccz/?app_id=cc3315e9bdb5719c7b57d6ee5b19e797#hack=commcare.ccz myusername mypassword

Contributing to the CLI

The CLI is part of Dimagi's CommCare repository. To build it, set up a new Gradle build configuration that runs the task "cliJar". From the command line, that's

gradle cliJar -c standalone.settings.gradle

This will generate build/libs/commcare.cli.jar

To run Android Studio's debugger, set up a second, JAR-based, build configuration. Provide it with

"Before launch" > add "Run Another Configuration" > your cliJar build configuration
Path to JAR: the JAR built by the cliJar build configuration
Program arguments: e.g., "play profile.ccpr username password"
Working directory: relevant for the sake of the ccpr or ccz file provided in program arguments

Considerations and Limitations

The cli does not store any data to the file system, so it can be used even with real data.
The cli does not parse forms and update the data locally (this will be changed very soon)
The cli does not submit data to HQ. This will be true for a while and will eventually be a flag for whether it should happen or not
The cli does not support: Case Tiles, some question types in forms

Wish List

Tab auto-complete for commands and XPath expressions in eval mode
Support for normal command line text editing and input history (work on implementation is in progress)
Ability to set current date (work on implementation is in progress)
Add a helper XPath function that lists all available XPath functions

Content

Space Tools

Popular Help Content

Getting Started

Running the CLI

Working with the CLI

Commands

Tips and Tricks

App Bookmarklet

Contributing to the CLI

Considerations and Limitations

Wish List

Content

Space Tools

Popular Help Content

Breadcrumbs

CommCare CLI

Getting Started

Running the CLI

Working with the CLI

Commands

Tips and Tricks

App Bookmarklet

Contributing to the CLI

Considerations and Limitations

Wish List