Commands

chap-devops [--json] [-C DIR] [--registry-url URL] [--offline] [--cache-dir DIR] <command>

The groups below are the shape of the tool. The Command reference is generated from the --help texts and lists every command, every flag and every default.

Running one model

See Running one model.

The everyday verbs

chap-devops up starts what is on disk, chap-devops update fetches newer versions, and chap-devops restart applies them to the services that are running. That is the whole distinction, and it is why up and update are both safe to run at any time. See Updating.

chap-devops jobs and chap-devops api are the two that talk to the API rather than to Docker. A job is one unit of slow work chap-core handed to its worker, and a failed one says why in chap-devops jobs logs <id> and nowhere else; chap-devops api is what starts a job from a terminal in the first place. See Jobs and the API.

chap-devops doctor is the one to run first on a machine you have not deployed on before, and first again when something is wrong: it asks in one pass what the other commands assume. It exits non-zero only when a check failed. See Doctor.

chap-devops down --volumes is the reset that takes the data with it (docker compose down -v --remove-orphans): it lists the volumes docker holds under this deployment’s name - with how much the OCS data volume holds next to it, when that can be measured - asks before removing them and ends with the ones that are gone, by name. -y (--yes) is how a script says it meant it, and is required where there is nothing to ask at - a stdin that is not a terminal, or --json - rather than the question being skipped. Compose removes the volumes its files still declare, so a volume left over from a disabled model survives; chap-devops doctor finds those, and chap-devops models disable <id> --purge removes them. There is no -v for this: -v is the global --verbose flag, so a -v that reaches the passthrough (chap-devops down -- -v) is refused and told to use --volumes, rather than being passed on to compose or quietly dropped.

Models

list, search and info read the catalogue and work outside a project. The rest need a project; of them, only test, configs list and configs export change nothing. Registration is a heartbeat, so chap-devops status and chap-devops doctor can be green while a model cannot predict at all - chap-devops models test is the check that settles it. See Testing a model. add is the only one that needs the network for something other than the catalogue: it reads GitHub and ghcr to resolve what it was given. See Models and the marketplace.

Components

A component is a service (or a small group) that chap-devops sync renders one compose file for: chap-core, which is Chap itself and is on unless you turn it off, ocs (Open Climate Service), s3 (the object store OCS will use) and dhis2 (a demo or development DHIS2 with its own database). The set lives in .chap-devops/components.yaml. chap-devops init --with ocs,s3, --without chap-core and --only ocs,s3 set it at creation time. chap-devops open NAME opens one of them in a browser, and o does the same from the browser’s components page. See Components, Reaching a component from a browser and DHIS2.

DHIS2

For a deployment with the dhis2 component, or with an external DHIS2 recorded by chap-devops dhis2 use. Apart from use, which records a DHIS2 in .chap-devops/components.yaml, and connect, which records when it ran in the same file, nothing here touches Docker or a file: every verb is requests to DHIS2’s own API.

Every one of them is idempotent: a second run repoints nothing, reinstalls nothing and says so. All of them take --user NAME and --wait SECONDS (how long to wait for DHIS2’s API: 20 minutes by default for the dhis2 component, because a first start takes minutes, and 60 seconds for an external DHIS2). The credential comes from DHIS2_API_TOKEN or DHIS2_ADMIN_USERNAME/DHIS2_ADMIN_PASSWORD in .env, else CHAP_DEVOPS_DHIS2_TOKEN or CHAP_DEVOPS_DHIS2_PASSWORD in the environment, else the seed password, else admin/district (only on a DHIS2 that chap-devops deployed). See The credentials. There is no --password flag, because a password on a command line is in the shell history. chap-devops up does none of this and the chapter says why - so chap-devops up and chap-devops status each end by naming chap-devops dhis2 connect until one has been recorded in .chap-devops/components.yaml. That record suppresses the hint and is never evidence that the route is right; chap-devops dhis2 show is what asks DHIS2. See Connecting the Modeling App to Chap and connected_at, and what it is not.

Authentication

All four touch only those two .env lines, and none of them restarts anything: chap-core and the models read .env when Compose creates them, so chap-devops up has to follow. chap-devops init --api-token does the same thing at creation time. See Authentication.

The chap CLI

You need no Python, uv or R for it. See The chap CLI.

Registry

Docker

The Docker plumbing you only reach for when you already know what Docker is doing lives under chap-devops docker, so the top-level list stays readable if you have never used Compose.

chap-devops docker config is what Docker actually reads after the -f list, the include: and the .env substitutions have been applied, which is the fastest way to find out why a setting is not taking effect.

Backup

See Backup and restore.

chap-devops itself

The two commands that are about the CLI rather than about a deployment. Both work anywhere, inside a deployment or not.

chap-devops update moves a deployment’s pins; chap-devops self update replaces the chap-devops binary. Nothing in the first touches the second. See Install for both of these and for the once-a-day notice that a newer release exists.

Global options

They are accepted before or after the subcommand, on every command, and the reference lists them with their defaults. The last three are the registry options. The help lists them under “Registry options” only for the commands that use them; Global options names those commands. On the other commands they change only the once-a-day notice that a newer release exists.

--json for scripts and tools

Under --json every command prints exactly one JSON document on stdout, and everything meant for a person - progress, notes, warnings - goes to stderr. A tool that drives chap-devops reads stdout and branches on one field:

• Success of a command that changes something (models enable, disable, add, remove, expose, unexpose, up, models test) carries "ok": true. The read-only commands (status, models list, models info) print their report as it is; status says how things are in its own exit code.

• Failure of any command is

  {"ok": false, "error": "...", "hint": "run `chap-devops ...`", "causes": []}
  

  hint is the way out: the message’s last clause when that clause names a command or a flag to use instead (pass \–id auto` … to add this one beside it), and nullwhen the message has no way out to give.erroris the message up to that clause, so the two never say the same thing; the terminal shows them together aftererror:. A message of several lines, for example the port check with more than one busy port, stays whole in error, with hint: null, because each line has its own way out. A usage error - an unknown flag, a missing argument - is the same document, with clap's message as errorand the command's–helpashint`, and exits 2.

• models enable and models add list what they enabled under models, one object per model with id, service_id, port, bind and url (the model’s own port, else chap-core’s proxy to it, else null), next to the full change report.

• up prints api_url, the compose services running and the ones this run started, every enabled model the same way, and under --wait what the wait found: wait.ready, wait.waited_s and each model’s state and url.

• models test prints {"ok": ..., "models": [...]}, one object per model with its result (pass, fail or skip), the summary and the detail that says why and what to do.

• models configs sync prints {"ok": ..., "models": [...]}, one object per model with id, service_id and its state: created (with the names in configured), already-configured, not-registered or failed (with the reason in error).

• models configs list prints {"models": [...]}, one object per model with id, service_id and configs. Each configured model has id, name, variant, archived, version, covariates, values and source.

• models configs add prints {"ok": true, "model": ..., "configured": [...]}, with the rows that chap-core created.

• models configs update prints model, changed, configured (the new row) and archived (the old row). If nothing changed, changed is false.

• models configs archive prints {"ok": true, "model": ..., "archived": ...}.

• models configs export prints model, configurations (the block, as JSON) and prediction_periods_from, which says where each prediction_periods comes from.

The exit code agrees with ok: 0 for true, non-zero for false. Two commands print "ok": false rather than an error and still exit non-zero: models test, when a model failed or every model was skipped, and models configs sync, when a model could not be configured.