{"id":50938146,"url":"https://github.com/dimagi/commcare-app-tools","last_synced_at":"2026-06-17T11:04:03.241Z","repository":{"id":338616239,"uuid":"1157555852","full_name":"dimagi/commcare-app-tools","owner":"dimagi","description":"CommCare CLI","archived":false,"fork":false,"pushed_at":"2026-02-17T02:42:56.000Z","size":177,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-05T04:43:50.026Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dimagi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-14T00:39:56.000Z","updated_at":"2026-02-17T02:43:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dimagi/commcare-app-tools","commit_stats":null,"previous_names":["dimagi/commcare-app-tools"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dimagi/commcare-app-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimagi%2Fcommcare-app-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimagi%2Fcommcare-app-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimagi%2Fcommcare-app-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimagi%2Fcommcare-app-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dimagi","download_url":"https://codeload.github.com/dimagi/commcare-app-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dimagi%2Fcommcare-app-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34445186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-17T11:04:02.297Z","updated_at":"2026-06-17T11:04:03.235Z","avatar_url":"https://github.com/dimagi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CommCare App Tools (`cc`)\n\n## What is this?\n\nCommCare App Tools is a proof of concept that makes it easier to work with CommCare from your computer. If you build apps on CommCare HQ, you normally do everything through the website -- looking up cases, checking mobile worker data, downloading apps, and so on. This project wraps all of those actions into a single command-line tool called `cc` so you can do them quickly from a terminal without clicking through the web interface.\n\nBeyond just talking to CommCare HQ, this tool also lets you **test your forms locally**. It uses a piece of CommCare's own code (the commcare-cli) to run your app on your machine, fill out a form with test data you define, and check that the result is what you expected. You write a simple YAML file that says \"open this form, answer these questions with these values\" and the tool does the rest -- downloading the app, grabbing the right user data, running the form, and telling you if it passed or failed.\n\nThere is also a **web UI** you can launch with `cc web start`. It gives you a visual way to browse your domains, pick an app and user, and set up test configurations without needing to know any command-line syntax. Think of it as a helper that walks you through the setup, then hands off to the CLI to do the actual work.\n\nThis project is intended to support Windows, Linux, and macOS but was initially developed and tested on windows.\n\n## Setup\n\n### 1. Install\n\n```bash\ngit clone https://github.com/dimagi/commcare-app-tools.git\ncd commcare-app-tools\ngit submodule update --init  # Required for local form testing\npython -m venv venv\n\n# Activate: Linux/macOS\nsource venv/bin/activate\n# Activate: Windows PowerShell\n.\\venv\\Scripts\\Activate.ps1\n\npip install -e \".[dev]\"\n```\n\n### 2. Authenticate\n\n```bash\ncc auth login   # Opens browser for OAuth\ncc auth status  # Verify authentication\n```\n\n### 3. Build CommCare CLI (for local form testing)\n\nRequires Java 17+. On Windows with Android Studio:\n```powershell\n$env:JAVA_HOME = \"C:\\Program Files\\Android\\Android Studio\\jbr\" #Example\n```\n\n```bash\ncc cli build    # Downloads Gradle, builds JAR (~1-2 min first time)\ncc cli status   # Verify build\n```\n\n## Usage\n\n### Web UI (Recommended for Test Config Creation)\n\n```bash\ncc web start    # Opens browser at http://localhost:8080\n```\n\nThe web UI provides:\n- Wizard to select domain/app/user/case for testing\n- Interactive terminal for running forms\n- Workspace management for downloaded artifacts\n\n### CLI Commands\n\n**API Access:**\n```bash\ncc domain list                              # List your domains\ncc --domain my-project app list             # List apps\ncc --domain my-project case list --limit 10 # List cases\ncc --domain my-project user list            # List mobile workers\ncc api get /a/my-project/api/case/v2/       # Raw API request\n```\n\n**User Restores:**\n```bash\ncc --domain my-project user restore worker1                    # Check restore access\ncc --domain my-project user restore worker1 --output-xml r.xml # Save restore XML\n```\n\n**Automated Form Testing:**\n```bash\ncc test init --output tests/my-test.yaml   # Generate a test template\ncc test run tests/my-test.yaml             # Run a test end-to-end\ncc test run tests/my-test.yaml --output-xml result.xml  # Save form output\n```\n\n**Local Form Testing (interactive):**\n```bash\ncc cli validate ./my-app.ccz               # Validate app\ncc cli play ./my-app.ccz --demo            # Run with demo user\ncc cli play ./my-app.ccz --restore data.xml # Run with restore file\n```\n\n**Workspace Management:**\n```bash\ncc workspace list                # List downloaded artifacts\ncc workspace stats               # Show disk usage\ncc workspace clean               # Remove all cached data\ncc workspace path my-domain app1 # Show path for debugging\n```\n\n**Environment Management:**\n```bash\ncc env list                      # List environments (* = active)\ncc env use staging               # Switch environment\ncc --env production domain list  # One-off environment override\n```\n\n### Output Formats\n\nAll commands support `--format` and `--output`:\n```bash\ncc --format table domain list              # Rich table\ncc --format csv --output cases.csv case list  # CSV file\n```\n\n## Commands Reference\n\n```\n# Authentication\ncc auth login|logout|status|whoami\n\n# Environments  \ncc env list|add|use|remove\n\n# Config\ncc config set|get|show\n\n# API Resources (use with --domain)\ncc domain list\ncc app list|get\ncc case list|get\ncc form list|get\ncc user list|get|restore\ncc lookup-table list|get|items\ncc report list|data\ncc api get|post\n\n# Automated Form Testing\ncc test init|run\n\n# Local Form Testing (interactive)\ncc cli build|status|clean|validate|play\n\n# Web UI\ncc web start|status\n\n# Workspace\ncc workspace list|stats|clean|path\n\n# FormPlayer Docker (advanced)\ncc formplayer start|stop|status|logs|restart|pull|destroy|connect|disconnect\n```\n\n### Global Options\n\n| Flag | Env Var | Description |\n|------|---------|-------------|\n| `--env` | `CC_ENV` | Override active environment |\n| `--domain` | `CC_DOMAIN` | CommCare domain (project space) |\n| `--format` | `CC_FORMAT` | Output format: json, table, csv |\n| `--output` | - | Write output to file |\n\n## File Locations\n\n| Path | Purpose |\n|------|---------|\n| `~/.commcare/config.json` | Environments, settings |\n| `~/.commcare/credentials.json` | OAuth tokens (per-environment) |\n| `~/.commcare/test-configs.json` | Saved test configurations |\n| `~/.commcare/workspaces/` | Downloaded apps, restores, session data |\n| `~/.commcare/cli/` | Cached commcare-cli.jar |\n\nOverride with `CC_CONFIG_DIR` environment variable.\n\n## Development\n\n```bash\npytest              # Run tests\nruff check src/     # Lint\nruff format src/    # Format\n\n# Run web UI in dev mode (hot reload)\ncc web start --reload\ncd src/commcare_app_tools/web/frontend \u0026\u0026 npm run dev  # React dev server\n```\n\n## License\n\nMIT - see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimagi%2Fcommcare-app-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdimagi%2Fcommcare-app-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdimagi%2Fcommcare-app-tools/lists"}