README
¶
demografix CLI
demografix tells you the likely gender, age, and nationality of a
person from their name, right from your terminal. Predict a single name, pipe in
a list of them, or enrich a whole spreadsheet in place.
It is a single static binary, built on the genderize.io, agify.io, and nationalize.io APIs.
Install
One line (Linux, macOS):
curl -fsSL https://raw.githubusercontent.com/DemografixGenderize/demografix-cli/main/install.sh | sh
Homebrew:
brew install demografixgenderize/tap/demografix
Or download a binary for your OS/arch from the releases.
Authentication
Every request needs an API key. Create a free account at genderize.io to get one — the free tier includes 2,500 names per month, and the same key works across all three services.
Log in once and it is remembered:
demografix login # prompts for your key (no echo), verifies it, saves it
The key is stored at ~/.config/demografix/config.toml, readable only by you.
For scripts and CI, set DEMOGRAFIX_API_KEY instead — it takes precedence over
the saved key.
Usage
# Predictions take names as arguments or one per line on stdin.
# Quote full names so the shell treats each one as a single name.
demografix gender "Peter Griffin" "Lois Griffin" "Meg Griffin"
demografix gender "Andrea Rossi" --country IT
printf 'Peter Griffin\nLois Griffin\n' | demografix gender
demografix age "Peter Griffin"
demografix nationality "Kim Nguyen"
# Output is a table on a terminal and JSONL when piped; override with -o.
demografix gender "Peter Griffin" -o json
demografix nationality "Kim Nguyen" -o jsonl
# Remaining quota for your key.
demografix quota
Spreadsheet enrichment
enrich reads a CSV/TSV/JSONL/JSON/XLSX file, predicts for each row, and appends
the prediction columns while preserving every other column.
demografix enrich people.csv -o out.csv \
--gender --age --nationality \
--name-col full_name \ # or --first-name-col / --last-name-col
--country-col country \ # or --country US (gender/age only)
--top-n 3 \ # nationality candidate columns
--prefix pred_ \ # avoid output-column collisions
--resume \ # only fill rows missing predictions
--dry-run # validate and print cost, make no calls
Output formats
-o table|json|jsonl|tsv|csv. The default is table on a terminal and jsonl
when the output is piped.
Exit codes
0 ok · 2 usage · 3 auth · 4 subscription · 5 validation · 6 rate
limit · 7 transport.
Documentation
¶
Overview ¶
Command demografix is the command-line client for the Demografix APIs (genderize.io, agify.io, nationalize.io).
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
api
Package api is the demografix CLI's standalone HTTP client for the three Demografix services (genderize.io, agify.io, nationalize.io).
|
Package api is the demografix CLI's standalone HTTP client for the three Demografix services (genderize.io, agify.io, nationalize.io). |
|
batch
Package batch groups names by country and chunks them to the API's 100-per-request cap, then runs the requests with bounded concurrency while preserving input order.
|
Package batch groups names by country and chunks them to the API's 100-per-request cap, then runs the requests with bounded concurrency while preserving input order. |
|
cli
Package cli wires the demografix command tree and owns process exit codes and user-facing error rendering.
|
Package cli wires the demografix command tree and owns process exit codes and user-facing error rendering. |
|
config
Package config resolves the API key and reads/writes the CLI config file.
|
Package config resolves the API key and reads/writes the CLI config file. |
|
enrich
Package enrich enriches a spreadsheet with gender/age/nationality predictions from the public API, joining results back onto the original rows.
|
Package enrich enriches a spreadsheet with gender/age/nationality predictions from the public API, joining results back onto the original rows. |
|
output
Package output renders predictions and quota to the terminal (table), or to json/jsonl/tsv/csv for machine consumers.
|
Package output renders predictions and quota to the terminal (table), or to json/jsonl/tsv/csv for machine consumers. |
|
sheet
Package sheet is the CLI's canonical spreadsheet model plus parsers and emitters for CSV, TSV, JSON, JSONL and XLSX.
|
Package sheet is the CLI's canonical spreadsheet model plus parsers and emitters for CSV, TSV, JSON, JSONL and XLSX. |
|
version
Package version holds the CLI version string.
|
Package version holds the CLI version string. |