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 nationality peter lois meg

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

demografix nationality < names.txt

The CLI batches names 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 nationality peter -o json

-o accepts table, json, jsonl, tsv, and csv. Nationality returns an array of country candidates ordered by descending probability, plus a count. The piped default is JSONL — one JSON object per line:

{"name":"peter","country":[{"country_id":"NG","probability":0.078},{"country_id":"KE","probability":0.046},{"country_id":"UG","probability":0.043}],"count":121222}

On a terminal, the table lists the ranked candidates and their probabilities per name.

Aggregate a list of names

To summarize the leading nationalities of a list, write predictions to a file and pivot the result:

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

The output carries each name's ranked country candidates — 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 age too

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

demografix gender peter
demografix age peter

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