Docs /Command-Line Client

Scripting and Automation

The client is built to be used from scripts: results go to the standard output, messages to the error stream, and the exit status says whether everything worked.

Output

Command	Standard output
`import-dicom`	one line: `<patient-id> <event-id> <series-name>`
`import-dicom-batch`	one line per patient loaded: `<name> <patient-id> <event-id> <series-name>`
`create-project`	one line: `<project-id> <device-id> <version-id>`
`create-project-batch`	one line per project created: `<name> <project-id> <device-id> <version-id>`
`add-geometry`	one line: the new geometry’s ID
`patients`	one line per CT series: `<patient-id> <event-id> <series-id> <patient name>`
`segment`	one line per anatomy: `<anatomy> <group> created` or `existing`; with `--airways`, a last line `airways lungs created` or `existing`
`anatomies`	one line per anatomy: `<anatomy> <group> <name>` (`-` when it has no group)
`download-stl`	one line per file written: `<anatomy> <path> <triangles>`
`virtual-spirometry`	one line: `<run> <FEV1 L> <FVC L> <PEF L/s> [folder]`
`download-spirometry`	one line per run saved, like `virtual-spirometry`
`databases`	one database name per line

Progress, summaries and errors are written to the error stream, so they never mix with the result lines. Add --json to get JSON instead:

climed-client import-dicom --name "John Doe" --series /data/cts/john_doe --json

{"ID": "<patient-id>", "EID": "<event-id>", "AID": "CTscan", "SID": "PRE"}

With import-dicom-batch --json you get one such object per patient, each with the patient’s name and a status of ok.

Exit status

Command	0	1	2
`import-dicom`, `create-project`	created	error (and nothing left behind)	one with that name already exists
`import-dicom-batch`, `create-project-batch`	nothing failed (skipped ones do not count)	at least one failed, the input was invalid, or the run was interrupted	—
`add-geometry`	added	error	—
`segment`	done (groups already there count as done)	error, failure, or stopped waiting	—
`download-stl`	every file written or already there	at least one file failed, or the selection was invalid	—
`virtual-spirometry`, `download-spirometry`	done	error, failure, or stopped waiting	—

segment has one more: 3 when a group could not be segmented in this scan (the lungs on a scan too short for the chest); the other groups of the same command are done.

Examples

Load one patient and keep its identifiers:

read PATIENT EVENT SERIES < <(climed-client import-dicom --name "John Doe" --series /data/cts/john_doe)
echo "created $PATIENT"

Load a folder every night and keep a record (the sign-in comes from environment variables):

# CLIMED_EMAIL and CLIMED_PASSWORD are set in the environment of the job
climed-client login
climed-client import-dicom-batch --root /data/incoming -d demo_db > loaded.txt 2> loaded.log
echo "exit status: $?"

Segment the lungs of every CT series of a database, then save their STL files. patients puts the name last, so a name with spaces stays whole:

climed-client patients -d demo_db | while read PATIENT EVENT SERIES NAME; do
  climed-client segment --patient "$PATIENT" --series "$SERIES" --group lungs \
    && climed-client download-stl --patient "$PATIENT" --series "$SERIES" --group lungs \
                                  --out "stl/$NAME/$SERIES"
done

Run a virtual spirometry and keep FEV1, FVC and PEF in a table:

climed-client virtual-spirometry --patient "John Doe" --out spiro >> spirometry.txt

Stop on the first problem in a larger script:

set -e
climed-client import-dicom-batch --manifest patients.csv --dry-run -d demo_db
climed-client import-dicom-batch --manifest patients.csv -d demo_db

A long batch outlives the one-hour sign-in: it is renewed between patients, as long as the sign-in came from login. A token passed with --token is not renewed.

Troubleshooting

Message	What to do
`not logged in`	Run `climed-client login`
`no server: run climed-client login or pass --api-url`	You are not signed in and gave no address: sign in, or add `--api-url https://…`
`login refused`	Check email and password. After several wrong attempts the account is locked for 15 minutes
`this account must change its password`	Change it in the web app, then sign in again
`no instance is assigned to this account`	Ask your administrator to assign you an instance
`your instance is switched off`	Ask your administrator to start it
`plain http is refused`	Use an address that starts with `https://`
`pass -d <database>`	Your account has several databases: choose one with `-d`
`a patient named … already exists`, `a project named … already exists`	It is already there. The client skips it and changes nothing
`is not a STL or VTP file`	Projects and geometries accept `.stl` and `.vtp` only
`geometry not added (HTTP 403)`	The project is not yours (or not shared with you): check `--project`
`… contains no files`, `… does not exist`	Fix the path in the folder or list, then run again
`expected one series, the backend stored N`	A ZIP holds more than one series: split it, one series per patient
`the Segment and Reconstruct module (segmentation) is not enabled`, `the Respirology module (respirology) is not enabled`	Ask your administrator to enable the module on your account
`not enough credits: … needed, … available`	Buy credits in the web app, then run the command again
`the computing quota of your account is used up`	Too many runs at once, or the daily GPU time is used: wait the time shown, then run it again
`lungs not segmented: insufficient_thorax_coverage`	The scan does not cover enough of the chest for the lungs (exit status 3)
`segmentation failed: … OutOfMemoryError`	The server ran out of memory: try one group at a time, or ask your administrator
`the series has no lungs anatomies`	Run `climed-client segment --group lungs` first
`--airways goes with --group lungs`	Add `--group lungs`: the airways are searched inside the lobes
`no airways after … s`	The server may still be working: check later with `climed-client anatomies --group lungs`; if they never appear, ask your administrator
`missing --age, --height, --weight, --sex`	The patient record lacks them: pass them on the command line for a personalised breathing effort
`no report.pdf: install the PDF extra`	Install the client with `[pdf]` (see Virtual Spirometry)
`patient not created (HTTP 401)`, `project not created (HTTP 401)`	The sign-in expired (or a `--token` ran out): run `climed-client login` and run the same command again; patients already loaded are skipped