gh-ip2location is a GitHub CLI extension that retrieves IPv4 and IPv6 geolocation, network, and available security intelligence using the IP2Location.io API. Look up your public IP address or a list of IPs directly from the terminal, with human-readable, JSON, or CSV output.
An API key is not required to get started. Add a key when you need a higher query allowance or additional fields available with your plan.
Quick links: Get an API key · API documentation · GitHub CLI · Report an issue
- IPv4 and IPv6 lookups: Find a country's code and name, region, city, coordinates, time zone, ASN, and other available information.
- Automatic public IP lookup: Run the command without an IP address to inspect the caller's public IP.
- Multiple IP addresses: Look up several addresses in one command.
- Three output formats: Use readable tables for interactive work, JSON for scripts, or CSV for exports.
- Field selection: Return only the fields you need, including nested properties using dot notation.
- API key management: Supply a key using a flag, environment variable, or saved configuration.
- Translated place names: Request supported translations with
--langon eligible API plans. - Script-friendly errors: Diagnostic messages go to stderr, with exit codes for automation.
Data availability: The fields returned depend on the IP address and API subscription. IP-based locations are approximate and must not be treated as GPS-level locations.
- GitHub CLI (
gh) installed and available in your terminal. - Internet access to the IP2Location.io API.
- An API key is optional for initial IP geolocation lookups.
Install the extension using GitHub CLI:
gh extension install ip2location/gh-ip2locationVerify that it is available:
gh ip2location --helpTo upgrade an existing installation:
gh extension upgrade ip2locationLook up an IPv4 address:
gh ip2location 8.8.8.8Example table output (illustrative; results can change):
IP Address 8.8.8.8
Country Code US
Country United States of America
Region California
City Mountain View
Latitude 37.38605
Longitude -122.08385
ZIP Code 94043
Time Zone -07:00
ASN 15169
AS Google LLC
Is Proxy false
To look up your own public IP address, omit the address:
gh ip2locationgh ip2location [<ip>...] [flags]
# IPv4 address
gh ip2location 8.8.8.8
# IPv6 address
gh ip2location 2001:4860:4860::8888
# Your own public IP address
gh ip2location
# Multiple addresses
gh ip2location 8.8.8.8 1.1.1.1
# Selected fields only
gh ip2location 8.8.8.8 --fields ip,country_code,city_name
# Translated location names (eligible plans)
gh ip2location 8.8.8.8 --lang ko| Format | Option | Best for |
|---|---|---|
| Table (default) | --format table |
Reading a lookup in the terminal |
| JSON | --json or --format json |
Processing results in scripts and tools |
| CSV | --csv or --format csv |
Exporting multiple lookups for analysis |
JSON example:
gh ip2location 8.8.8.8 --jsonA single successful lookup produces a JSON object; several successful lookups produce an array. JSON preserves the returned fields, except when --fields is used to select a subset.
CSV example:
gh ip2location 8.8.8.8 1.1.1.1 --csvCSV includes a header row and one row per successful address. Nested fields are flattened with dots, such as country.currency.code. For multiple responses, the column set includes fields found across the responses.
Use --fields with comma-separated API field names:
gh ip2location 8.8.8.8 --json --fields ip,country_code,city_nameNested values can be selected using dot notation:
gh ip2location 8.8.8.8 --csv --fields ip,country.currency.codeNot all fields are available on every plan. Consult the API documentation for field details.
The extension supports keyless IP geolocation requests for trying the service without signing up. Keyless access provides up to 1,000 queries per day. You can create an IP2Location.io account for a free API key, with published free-plan allowances of 50,000 IP geolocation queries per month. Paid plans provide other quotas and available data fields; check the pricing page for up-to-date details.
Keyless and free-plan use may require attribution. Review the provider's current terms and pricing information before publishing or redistributing results.
The extension resolves the API key in this order:
--key <key>command-line optionIP2LOCATION_API_KEYenvironment variable- Saved extension configuration
Recommended: use an environment variable rather than placing credentials in scripts or shell history.
Linux / macOS:
export IP2LOCATION_API_KEY='YOUR_API_KEY'
gh ip2location 8.8.8.8Windows PowerShell:
$env:IP2LOCATION_API_KEY = 'YOUR_API_KEY'
gh ip2location 8.8.8.8You can optionally save or remove a key in the extension's user configuration:
gh ip2location --set-key YOUR_API_KEY
gh ip2location --unset-keyThe saved configuration file is gh-ip2location/config.json beneath your operating system's user configuration directory (typically %AppData% on Windows or ~/.config on Linux). Avoid using a shared configuration directory for sensitive credentials.
gh ip2location 8.8.8.8 --json --fields ip,country_code | jq -r '.country_code'Requires jq, installed separately.
gh ip2location 8.8.8.8 1.1.1.1 --csv \
--fields ip,country_code,region_name,city_name,asn > locations.csvFor Windows PowerShell, enter the command on one line instead of using the Bash \ line continuation.
if gh ip2location 8.8.8.8 --json > result.json; then
echo 'Lookup completed'
else
echo 'Lookup failed' >&2
figh ip2location 8.8.8.8 1.1.1.1 9.9.9.9 --jsonAddresses are looked up sequentially. If a lookup fails, the extension reports the error on stderr and continues with the remaining addresses. Successful results are still printed, but the overall exit code is 1 when any lookup fails.
| Flag | Description |
|---|---|
-k, --key <key> |
API key for this invocation |
-f, --format <fmt> |
Output format: table (default), json, or csv |
--json |
Short for --format json |
--csv |
Short for --format csv |
--fields <list> |
Comma-separated fields; supports nested names with dots |
--lang <code> |
Request available translated names (eligible plans) |
--set-key <key> |
Save an API key to the local extension configuration |
--unset-key |
Clear the saved API key |
-v, --version |
Print the extension version |
-h, --help |
Display help |
The keyless endpoint can return core information, including ip, country_code, country_name, region_name, city_name, latitude, longitude, zip_code, time_zone, asn, as, and is_proxy.
Depending on your API plan, additional fields can include ISP and network attributes, district, mobile-network metadata, usage type, IAB category, structured geographic objects, and security indicators such as fraud score and proxy details. Some optional fields may be unavailable or null for an individual IP address.
For the complete field definitions and plan requirements, see the IP2Location.io API documentation.
| Exit code | Meaning |
|---|---|
0 |
All requested lookups succeeded |
1 |
A lookup, API request, or output operation failed |
2 |
Invalid command-line arguments |
Errors and API notices are written to stderr. Data output is written to stdout, making the command suitable for pipelines and file redirection.
Common troubleshooting checks:
- Invalid IP: Confirm the input is a valid IPv4 or IPv6 address.
- API key error: Check the key set through your flag, environment, or saved configuration.
- Quota exceeded: Review your remaining allowance or plan limits.
- Unexpectedly missing fields: Check your plan and whether the API provides those fields for that IP.
- Command not found: Ensure GitHub CLI is installed and the extension installation succeeded.
Building this repository requires Go 1.23 or newer.
git clone https://github.com/ip2location/gh-ip2location.git
cd gh-ip2location
go test ./...
go build
gh extension install .IP geolocation is not GPS. Results estimate the geographic location associated with an IP address and may differ from the user's actual physical location. VPNs, proxies, mobile networks, carrier routing, and shared infrastructure can affect accuracy. Do not treat IP-based location or proxy indicators as conclusive proof of an individual's identity, precise location, or fraudulent behavior.
For bugs, feature requests, or documentation improvements, open an issue. Contributions are welcome through GitHub pull requests. When reporting issues, include the extension version, operating system, command syntax, and relevant error message; redact API keys and other sensitive data.
This project is licensed under the MIT License.