Scripting
Use the ip2geo CLI in scripts and CI: JSON, NDJSON and CSV output, single fields, exit codes, retries, configuration and shell completion.
The CLI writes its results to stdout and every message to stderr, so its output is safe to pipe and to redirect into a file.
Output formats
Every command takes --json, or --output (-o) with pretty, json, ndjson or csv. ip2geo config set output json makes a format the default.
ip2geo 8.8.8.8 --json | jq .continent.country.code
cat ips.txt | ip2geo -o csv > locations.csv
ip2geo conversions list --all -o ndjson | gzip > conversions.ndjson.gzOne address prints its data object, as the SDK returns it. Several addresses print an array of ip, status and conversion, in the order they were given. Lists stream as they arrive, and JSON stays one valid array even when a run stops halfway.
For a single field, --fields prints the bare value:
country=$(ip2geo 8.8.8.8 --fields country_code)
ip2geo convert --file ips.txt --fields country_code,asn.name -o csvFields take the names ip2geo fields lists, in any case, or their paths, like continent.country.code.
Exit codes
| Code | Meaning |
|---|---|
0 | Done |
1 | Failed: an API error, or some values were not addresses or could not be located |
2 | Wrong usage: an unknown command or option, or a bad value |
3 | Not signed in, or the key, the session or your role was refused |
4 | Not found |
5 | A limit was reached: your plan’s conversions, the most keys, projects or members a project can have, or too many sign-in codes |
6 | Network failure, timeout or maintenance |
130 | Canceled with Ctrl+C |
Pass --skip-invalid to drop values that are not IP addresses instead of exiting 1.
Retries and limits
Reads are retried on timeouts, dropped connections and server errors. Conversions and changes to your account are only retried when the request never left your machine, so nothing is ever converted or changed twice. --timeout <seconds> sets how long a request may take.
Bulk input is sent 5,000 addresses at a time with a secret key, or 50 at a time through a login. If your plan’s limit is reached halfway, the CLI keeps everything already converted, stops, and exits 5.
Configuration
ip2geo config lists the settings, their values and where each comes from. They live in ~/.config/ip2geo/config.json (%APPDATA%\ip2geo on Windows), which only your user can read, together with the sign-in.
| Variable | Use |
|---|---|
IP2GEO_API_KEY | The secret key to convert with, ahead of the config |
IP2GEO_PROJECT | The project commands act on, by id or name; conversions on it go through your login |
IP2GEO_API_URL | Another API address, like a local one |
IP2GEO_CONFIG_DIR, IP2GEO_CACHE_DIR | Where the config and the cache live |
IP2GEO_NO_UPDATE_CHECK | Never check for a newer version |
NO_COLOR, FORCE_COLOR | Turn colors off, or on everywhere |
--key and --project override the variables for a single command. Destructive commands ask for confirmation; --yes confirms them in scripts, and without a terminal they refuse to run unconfirmed.
Shell completion
source <(ip2geo completion zsh)
source <(ip2geo completion bash)
ip2geo completion fish > ~/.config/fish/completions/ip2geo.fishAdd the line for your shell to its startup file to keep completion on.