@humanform/cli

Humanform CLI

Command-line interface for the Humanform anthropometric prediction API. Run predictions, percentile ranges, country comparisons, and measurement search from your terminal or CI pipelines.

Setup

• Install globally, or use npx without installing:

npm install -g @humanform/cli

npx @humanform/cli --help

• Authenticate with an API key from the Humanform dashboard:

humanform login

This stores your key in ~/.humanform/config.json (file mode 600). To remove it:

humanform logout

For CI and scripting, set HUMANFORM_API_KEY instead of using login. The environment variable takes precedence over the stored config.

Optional: override the API base URL (defaults to https://api.humanform.app):

export HUMANFORM_API_URL="https://api.humanform.app"

Commands

Command	API	Description
predict	POST /v1/predict	Forward lookup: percentile → measurement value
range	POST /v1/predict/range	Multiple percentiles for one measurement
compare	POST /v1/predict/compare	One percentile across multiple countries
measurements search	GET /v1/measurements/search	Fuzzy search measurement names (no API key required)
percentile-lookup	POST /v1/percentile-lookup	Reverse lookup: measured value → percentile

predict

humanform predict \
  --measurement Stature \
  --gender Female \
  --age 34 \
  --percentile 50 \
  --country US \
  --unit cm

range

humanform range \
  --measurement PoplitealHeight \
  --gender Female \
  --age 34 \
  --country US \
  --percentiles 5,50,95 \
  --unit cm

compare

humanform compare \
  --measurement PoplitealHeight \
  --gender Female \
  --age 34 \
  --percentile 50 \
  --countries US,UK,JP \
  --unit cm

measurements search

humanform measurements search grip

percentile-lookup

humanform percentile-lookup \
  --measurement PoplitealHeight \
  --gender Female \
  --age 34 \
  --country US \
  --unit cm \
  --value 43.1

Scripting with --json

Add --json to any command for machine-readable output suitable for piping into jq or other tools:

humanform predict \
  --measurement Stature \
  --gender Male \
  --age 30 \
  --percentile 50 \
  --country US \
  --unit cm \
  --json

In CI, pass the API key via environment variable:

HUMANFORM_API_KEY="hf_live_..." humanform predict --measurement Stature ...

API errors (401, 402, 404, 422, 429, etc.) are printed to stderr with non-zero exit codes for scripting.

Local development

For contributors working in the humanform-api monorepo:

pnpm --filter @humanform/api-client build
pnpm --filter @humanform/cli build
pnpm --filter @humanform/cli test:smoke

Run against a local build:

pnpm --filter @humanform/cli build
node apps/cli/dist/index.js predict --measurement Stature --gender Male --age 30 --percentile 50 --country US --unit cm

Or during development:

pnpm dev:cli