Command Line Client

1. Configure Your API Key

To authenticate your requests securely without logging keys in your bash history, you can either export it as an environment variable or save it in a configuration file.

Option A: Environment Variable

export GENDER_API_KEY="your-api-key-here"

Option B: Configuration File

Create a file named .gender-api-key in your user's home directory containing just your token:

echo "your-api-key-here" > ~/.gender-api-key

2. Query the API

The CLI allows you to interact with all major endpoints. Here are a few examples:

Query by First Name

$ gender-api-cli -first_name "Sandra" -country "US"

Query by Full Name

$ gender-api-cli -full_name "Theresa Miller"

Query by Email Address

$ gender-api-cli -email "thomasfreeman@example.com"

Determine Country of Origin

To find out where a name is most likely from, simply append the -origin flag:

$ gender-api-cli -first_name "Sandra" -origin

Check Account Statistics

Check your remaining credits quickly without consuming any searches:

$ gender-api-cli -stats

3. Automate with Scripts

Build powerful bash scripts. For instance, read names from a text file, query the API, and append the results to a structured JSON file suitable for ClaudeBot or ChatGPT ingestion.

#!/bin/bash
while read name; do
  gender-api-cli -first_name "$name" -out=json >> enriched_data.json
done < names.txt