Command-line tool

Install

On macOS and Linux, install with one command:

curl -fsSL https://raw.githubusercontent.com/DemografixGenderize/demografix-cli/main/install.sh | sh

With Homebrew:

brew install demografixgenderize/tap/demografix

For other platforms, download a binary from the releases page.

Authentication

Every request needs an API key. Get one from your account dashboard. The same key works for gender, age, and nationality.

Log in once and the key is saved:

demografix login

The command prompts for the key without echoing it and stores it at ~/.config/demografix/config.toml.

For scripts and continuous integration, set DEMOGRAFIX_API_KEY instead. It takes precedence over the saved key:

export DEMOGRAFIX_API_KEY=your_api_key

Predict from names

Pass names as arguments:

demografix age peter lois meg

Scope predictions to a country with --country (an ISO 3166-1 alpha-2 code):

demografix age peter --country DK

Read one name per line from standard input to process a file of names in a single command:

demografix age < names.txt

The CLI groups names by country, batches them ten per request, and runs them concurrently, so a long list resolves in one command.

Output formats

Output is a table on a terminal and JSONL when the output is piped. Override the format with -o:

demografix age peter -o json

-o accepts table, json, jsonl, tsv, and csv. A table renders columns for reading:

name   age  count
peter  71   169145

The piped default is JSONL — one JSON object per line:

{"name":"peter","age":71,"count":169145}

Aggregate a list of names

To summarize the age distribution of a list, write predictions to a file and pivot the result:

demografix age < names.txt -o csv > predictions.csv

The output carries one row per name with the predicted age — an aggregate file ready to chart the distribution of a cohort. To enrich a spreadsheet in place instead, see Enrich spreadsheets .

Check your quota

demografix quota prints the remaining quota for your key:

demografix quota

Every prediction command also prints a one-line quota summary to standard error. Suppress it with -q.

Global flags

Exit codes

The CLI returns a distinct exit code per failure class, for scripting:

Use it for gender and nationality too

The same binary and key predict the other two services. Swap the command:

demografix gender peter
demografix nationality nguyen

Per-service docs: genderize.io/documentation/cli · agify.io/documentation/cli · nationalize.io/documentation/cli