CLI reference¶

Every command and flag the clincalc binary supports, in one place. There are no per-calculator flags - the same surface drives all 53 active calculators and 10 proprietary/unavailable stubs.

clincalc [COMMAND]

Commands¶

clincalc <name> remains supported as shorthand for clincalc calc <name>, so existing scripts continue to work. Common aliases such as bmr, rmr, ree, and tdee resolve to energy_requirement; ckd-epi / ckdepi resolve to egfr. clincalc list shows aliases, and unknown calculator names include a small "did you mean" hint when there is a close match. Computing always requires an explicit --input, so template mode never blocks waiting on stdin.

Options¶

--input <JSON|FILE|->¶

Source of the input JSON. The argument is resolved in this order:

1. - reads the whole of standard input.
2. An existing file path is read from disk.
3. Anything else is treated as an inline JSON string.

clincalc calc news2 --input -                    # stdin
clincalc calc news2 --input examples/news2.json  # file
clincalc calc news2 --input '{"respiratory_rate":21, ...}'  # inline

Invalid JSON is rejected with a clear message and a non-zero exit; the reminder points you at clincalc calc <name> to see the expected shape.

--activity <sedentary|light|moderate|very-active|extra-active>¶

Convenience input for energy_requirement and its aliases (bmr, rmr, ree, tdee). The preset injects the standard activity factor before calculation: sedentary 1.2, light 1.375, moderate 1.55, very-active 1.725, extra-active 1.9. Do not combine it with an explicit activity_factor in the JSON input.

clincalc calc tdee --activity moderate --input '{"equation":"mifflin_st_jeor","sex":"male","age":30,"weight_kg":70,"height_cm":175}'

The selected preset is echoed in the Working block as activity_preset; the numeric factor remains visible as activity_factor.

Energy target helpers can derive calorie_adjustment_kcal_day from a goal and rate using roughly 7700 kcal/kg. For Cunningham, --body-fat-pct can derive lean_body_mass_kg from weight_kg.

clincalc calc tdee --equation mifflin_st_jeor --sex male --age 30 --weight-kg 70 --height-cm 175 --activity moderate --goal lose --rate 0.5 --target-weight 65
clincalc calc bmr --equation cunningham --weight-kg 80 --body-fat-pct 25

These helpers echo their derived values in the Working block (energy_goal, weight_change_rate_kg_week, estimated_weeks_to_target, body_fat_pct, derived_lean_body_mass_kg).

Human field flags and --interactive¶

For quick hand use, common scalar input fields can be supplied as flags instead of writing JSON: --equation, --sex, --age, --weight-kg, --height-cm, --lean-body-mass-kg, --creatinine, --creatinine-unit, and --calorie-adjustment-kcal-day. These flags build the same JSON object that --input would have supplied, so calculator validation and output remain unchanged.

clincalc calc tdee --equation mifflin_st_jeor --sex male --age 30 --weight-kg 70 --height-cm 175 --activity moderate
clincalc calc egfr --age 60 --sex female --creatinine 80 --creatinine-unit umol/L

You can combine these flags with --input to add missing fields, but a flag cannot overwrite a field that is already present in the JSON. For guided entry, use --interactive; prompts are written to stderr and the result remains on stdout.

clincalc calc egfr --interactive

--profile and --from-record <FILE>¶

--profile fills missing fields from ~/.config/clincalc/profile.json (or $XDG_CONFIG_HOME/clincalc/profile.json). --from-record <FILE> does the same from a specified JSON file. Only keys present in the selected calculator's schema are copied; matching keys can live at the top level, under subject, or under profile.

{
  "subject": {
    "age": 60,
    "sex": "female",
    "weight_kg": 70,
    "height_cm": 165
  }
}

Explicit --input values and human field flags win; profile/record data only fills gaps.

clincalc calc egfr --from-record patient.json --creatinine 80 --creatinine-unit umol/L

--schema¶

Print the calculator's JSON Schema to stdout. This is the formal input contract - field names, types, ranges, enumerations - and is the same schema served to LLMs by the MCP surface when clincalc is embedded in a host.

clincalc calc gad7 --schema

--license¶

Print the algorithm's distribution licence (an SPDX identifier where one applies, otherwise a short description) plus a reverifiable URL, as a small JSON object:

clincalc calc qrisk3 --license

This is separate from the code licence (AGPL-3.0-or-later for the whole project) - it records the basis on which the clinical algorithm itself is being shipped.

--format <text|json>¶

Output format for computed results, list, tags, and version.

• text (default) - a clinician-facing block: result, interpretation, working, reference. Designed for the clipboard. Calculators may provide a more helpful headline label than their machine name, for example BMR/RMR, TDEE, or Target intake for energy_requirement.
• json - the CalculationResponse structure as machine-readable JSON. The same shape every surface (CLI, MCP, GUI) produces.

clincalc list --format json
clincalc tags --format json
clincalc version --format json
clincalc calc feverpain --input examples/feverpain.json --format json

--help, --version, -V, -v, -version¶

--help describes commands and flags. clincalc version is the documented version command and supports --format json; the conventional quick-check flags --version / -V also work, and lone -v / -version are accepted as helpful aliases.

MCP server¶

clincalc mcp starts the local stdio Model Context Protocol server when the binary is compiled with the optional mcp feature:

cargo install clincalc --features mcp
clincalc mcp

The MCP server exposes every calculator from clincalc::all() as a tool named clincalc_<name>. Each tool's input schema is the calculator's own JSON Schema, and calls return the same structured CalculationResponse as clincalc calc <name> --input ... --format json.

A binary compiled without the mcp feature reserves the command and prints a targeted reinstall hint instead of treating mcp as an unknown calculator. See MCP server for host configuration and safety notes.

Shell completions¶

Install completions for your current shell:

clincalc completions install

For package managers or custom locations, generate or write a specific shell's completion script:

clincalc completions bash
clincalc completions --dir ~/.local/share/bash-completion/completions bash
clincalc completions --dir ~/.zfunc zsh
clincalc completions --dir ~/.config/fish/completions fish
clincalc completions --dir ~/.config/powershell/completions powershell

The installer detects $SHELL, creates the completion directory, writes the correctly named file, and prints any one-time shell configuration still needed.

The CalculationResponse shape¶

Every computed result, regardless of calculator, has the same JSON shape:

{
  "calculator": "feverpain",
  "result": 3,
  "interpretation": "A score of 3 is associated with 34–40% isolation of streptococcus. ...",
  "working": {
    "score": 3,
    "level": "delayed",
    "...": "..."
  },
  "reference": "Little P, Stuart B, Hobbs FDR, et al. Lancet Infect Dis. 2014. ..."
}

• calculator - the machine name (matches the CLI subcommand and the MCP tool name).
• result - the primary computed value. A number for most scores, a short string for categorical results.
• interpretation - the clinician-facing summary line(s).
• working - every intermediate value the score depends on, so the result is auditable without re-running.
• reference - the primary citation.

Exit codes¶

Conventions¶

• Template / schema / compute output is on stdout as pure JSON or pure text - safe to redirect or pipe.
• Reminders and usage hints go to stderr so they never corrupt a stream.
• The CLI never reads stdin unless you ask for it (--input -).
• All output is deterministic - no timestamps, no random ids - so it diffs cleanly in tests and audits.

Embedding in a host CLI¶

The same library that drives the clincalc binary is reusable as clincalc::cli::run, so a host CLI repeats nothing:

#[derive(clap::Subcommand)]
enum Commands {
    // ...
    /// Clinical calculators
    Calc(clincalc::cli::CalcCommand),
}

// dispatch:
Commands::Calc(cmd) => clincalc::cli::run(cmd)?,

GitEHR's gitehr calc subcommand is implemented exactly this way. See How it works for the wider architecture.