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

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

demografix gender andrea --country IT

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

demografix gender < 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 gender peter -o json

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

name   gender  probability  count
peter  male    1.00         1346866

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

{"name":"peter","gender":"male","probability":1.0,"count":1346866}

Aggregate a list of names

To summarize the gender split of a list, write predictions to a file and pivot the result:

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

The output carries one row per name with the predicted gender — 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 age and nationality too

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

demografix age peter
demografix nationality nguyen

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