ipgeolocation CLI Documentation

The ipgeolocation CLI lets you interact with the ipgeolocation.io API directly from your terminal. It supports looking up IP information (single or bulk), configuring API keys, and formatting output in multiple styles.

Installation

1. Go install

To install ipgeolocation using go install, run:

go install github.com/IPGeolocation/cli/cmd/ipgeolocation@latest

Make sure $GOBIN or $GOPATH/bin is in your PATH, then run:

ipgeolocation --help

2. Download and build from source

git clone https://github.com/IPGeolocation/cli.git
cd cli
go build -o ipgeolocation ./cmd/ipgeolocation
./ipgeolocation --help

3. Download pre-built binaries

IPGeolocation CLI - Prebuilt Binaries Documentation

Overview

These are prebuilt binaries for the IPGeolocation CLI tool, version 1.0.0. Users can download these files directly from GitHub Releases without needing to build from source.

The CLI provides geolocation information, timezone, user-agent parsing, bulk IP lookups, and more.

Prebuilt Binaries

Platform	Architecture	File Name
Linux	amd64	ipgeolocation-1.0.0-linux-amd64.tar.gz
Linux	arm64	ipgeolocation-1.0.0-linux-arm64.tar.gz
macOS	amd64	ipgeolocation-1.0.0-darwin-amd64.tar.gz
macOS	arm64	ipgeolocation-1.0.0-darwin-arm64.tar.gz
Windows	amd64	ipgeolocation-1.0.0-windows-amd64.zip

Installation Instructions

1. Linux

Download the .tar.gz file for your architecture.
Extract it to a folder in your PATH, e.g., /usr/local/bin:

tar -xzf ipgeolocation-1.0.0-linux-amd64.tar.gz -C /usr/local/bin

Rename the binary for simplicity:

mv /usr/local/bin/ipgeolocation-1.0.0-linux-amd64 /usr/local/bin/ipgeolocation

Make the binary executable:

chmod +x /usr/local/bin/ipgeolocation

Verify installation:

ipgeolocation --help

2. macOS

Download the .tar.gz file for your architecture (amd64 or arm64).
Extract to a folder in your PATH, e.g., /usr/local/bin:

tar -xzf ipgeolocation-1.0.0-darwin-amd64.tar.gz -C /usr/local/bin

Rename the binary:

mv /usr/local/bin/ipgeolocation-1.0.0-darwin-amd64 /usr/local/bin/ipgeolocation

Make executable:

chmod +x /usr/local/bin/ipgeolocation

Verify installation:

ipgeolocation --help

3. Windows

Download the .zip file.
Extract the ipgeolocation-1.0.0-windows-amd64.exe to a folder included in your system PATH.
Rename the binary to ipgeolocation.exe for convenience.
Open Command Prompt and verify:

ipgeolocation --help

Notes

Ensure execution permissions on Linux/macOS.
Recommended folder for binaries: /usr/local/bin or any folder in your PATH.
Prebuilt binaries include version 1.0.0 in their filename. Rename them after extraction for easier usage.
For updates, check GitHub Releases.
Users can also install via Go if Go environment is set up:

go install github.com/IPGeolocation/cli/cmd/ipgeolocation@v1.0.0

Troubleshooting

Command not found: Ensure the binary is in a folder included in your PATH.
Execution permission error: Run chmod +x <binary> on Linux/macOS.
Wrong architecture: Download the binary matching your OS and CPU architecture.
Go install issues: Use GOPROXY=direct if Go module proxy caching creates issues.

Global Flags

These flags are available for all commands:

Flag	Description
`-h, --help`	Show help for the command.

You can also check the version for ipgeolocation using the --version flag:

ipgeolocation --version

Commands

1. `config`

Configure your API key for ipgeolocation.io.

Usage

ipgeolocation config --apikey=<your-key>

Flags

Flag	Type	Description
`--apikey`	string	Your API key from ipgeolocation.io.

2. `ipgeo`

Lookup geolocation information for a single IP address or domain using the ipgeolocation.io API.

Usage

ipgeolocation ipgeo [flags]

Flags

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4, IPv6, or domain name (e.g. `8.8.8.8`, `google.com`).
`--include`	string[]	`[]`	Include extra fields (e.g. `security,timezone,currency`).
`--excludes`	string[]	`[]`	Exclude fields from output.
`--fields`	string[]	`[]`	Return only specific fields (e.g. `ip,organization`).
`--lang`	string	`""`	Response language.
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

Examples

Get info about your current IP:

ipgeolocation ipgeo

Lookup a specific IP:

ipgeolocation ipgeo --ip 8.8.8.8

Lookup a domain with extra fields:

ipgeolocation ipgeo --ip google.com --include security,timezone,currency

Get only specific fields in YAML:

ipgeolocation ipgeo --ip 1.1.1.1 --fields location --output yaml

Exclude unnecessary fields:

ipgeolocation ipgeo --ip 8.8.8.8 --excludes currency,time_zone

3. `bulk-ip-geo`

Lookup geolocation information for multiple IPs in one request.

Usage

ipgeolocation bulk-ip-geo [flags]

Flags

Flag	Type	Default	Description
`--ips`	string[]	`[]`	Comma-separated list of IPs. Example: `--ips 8.8.8.8,1.1.1.1`
`--file`	string	`""`	Path to a text file containing IPs (one per line).
`--include`	string[]	`[]`	Include extra fields (e.g. `location,time_zone`).
`--exclude`	string[]	`[]`	Exclude fields (e.g. `currency`).
`--fields`	string[]	`[]`	Return only specific fields (e.g. `location`).
`--lang`	string	`""`	Response language (if supported).
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.
`--output-file`	string	`""`	Save output to JSON file. Example: `--output-file results.json`

For further information, please visit IP Geolocation API Documentation.

Examples

Lookup 3 IP addresses:

ipgeolocation bulk-ip-geo --ips 8.8.8.8,1.1.1.1,192.30.253.112

Lookup from a file:

ipgeolocation bulk-ip-geo --file=ips.txt

Include location and timezone:

ipgeolocation bulk-ip-geo --file=ips.txt --include=location,time_zone

Output as YAML:

ipgeolocation bulk-ip-geo --ips=8.8.8.8 --output=yaml

Save results to JSON file:

ipgeolocation bulk-ip-geo --ips=8.8.8.8,1.1.1.1 --output-file=output.json

Output Formats

pretty (default): Human-readable formatted JSON.
raw: Raw API response.
table: Tabular display of common fields.
yaml: YAML-formatted output.
json file: If --output-file is provided, results are saved to a .json file.

4. `ip-security`

Lookup IP security information using the ipgeolocation.io API.

Usage

ipgeolocation ip-security [flags]

Flags

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4 or IPv6 address.
`--include`	string[]	`[]`	Include extra fields in output.
`--exclude`	string[]	`[]`	Exclude fields from output.
`--fields`	string[]	`[]`	Return only specific fields (e.g. `ip,organization`).
`--lang`	string	`""`	Response language.
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

Examples

Get info about your current IP:

ipgeolocation ip-security

Lookup a specific IP:

ipgeolocation ip-security --ip 8.8.8.8

Lookup security information for a specific IP with including additional fields:

ipgeolocation ip-security --ip 8.8.8.8 --include=location,time_zone

Output as YAML:

ipgeolocation ip-security --ip 8.8.8.8 --output=yaml

For further information, please visit IP Security API Documentation.

5. `bulk-ip-security`

Lookup IP security information for multiple IPs in one request.

Usage

ipgeolocation bulk-ip-security [flags]

Flags

Flag	Type	Default	Description
`--ips`	string[]	`[]`	Comma-separated list of IPs. Example: `--ips 8.8.8.8,1.1.1.1`
`--file`	string	`""`	Path to a text file containing IPs (one per line).
`--include`	string[]	`[]`	Include extra fields (e.g. `location,time_zone`).
`--exclude`	string[]	`[]`	Exclude fields (e.g. `currency`).
`--fields`	string[]	`[]`	Return only specific fields (e.g. `location`).
`--lang`	string	`""`	Response language (if supported).
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.
`--output-file`	string	`""`	Save output to JSON file. Example: `--output-file results.json`

Examples

Lookup 3 IP addresses:

ipgeolocation bulk-ip-security --ips 8.8.8.8,1.1.1.1,192.30.253.112

Lookup from a file:

ipgeolocation bulk-ip-security --file=ips.txt

Include location and timezone:

ipgeolocation bulk-ip-security --file=ips.txt --include=location,time_zone

Output as YAML:

ipgeolocation bulk-ip-security --ips=8.8.8.8 --output=yaml

Save results to JSON file:

ipgeolocation bulk-ip-security --ips=8.8.8.8,1.1.1.1 --output-file=output.json

For further information, please visit Bulk IP Security API Documentation.

6. `asn`

Lookup ASN (Autonomous System Number) information using the ipgeolocation.io API.

Usage

ipgeolocation asn [flags]

Flags

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4 or IPv6 address.
`--include`	string[]	`[]`	Include extra fields in output.
`--exclude`	string[]	`[]`	Exclude fields from output.
`--fields`	string[]	`[]`	Return only specific fields (e.g. `ip,organization`).
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

Examples

Get ASN info about your current IP:

ipgeolocation asn

Lookup a specific ASN:

ipgeolocation asn --asn 12345

Lookup a specific IP with including additional fields:

ipgeolocation asn --ip 8.8.8.8 --include routes,peers,upstreams,downstreams,whois_response

Exclude unnecessary fields:

ipgeolocation asn --ip 8.8.8.8 --exclude asn.date_allocated,asn.allocation_status

Get only specific fields in table format:

ipgeolocation asn --ip 8.8.8.8 --fields asn.organization,asn.country,asn.downstreams --output table

Output as YAML:

ipgeolocation asn --ip 8.8.8.8 --output=yaml

For further information, please visit ASN API Documentation.

7. `abuse`

Lookup abuse information using the ipgeolocation.io API.

Usage

ipgeolocation abuse [flags]

Flags

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4 or IPv6 address.
`--exclude`	string[]	`[]`	Exclude fields from output.
`--fields`	string[]	`[]`	Return only specific fields (e.g. `ip,organization`).
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

Examples

Get abuse info about your current IP:

ipgeolocation abuse

Lookup a specific IP:

ipgeolocation abuse --ip 8.8.8.8

Exclude unnecessary fields:

ipgeolocation abuse --ip 8.8.8.8 --exclude abuse.handle,abuse.emails

Get only specific fields in table format:

ipgeolocation abuse --ip 8.8.8.8 --fields abuse.role,abuse.emails --output table

Output as YAML:

ipgeolocation abuse --ip 8.8.8.8 --output=yaml

For further information, please visit Abuse API Documentation.

8. `timezone`

Lookup timezone information using the ipgeolocation.io API.

Usage

ipgeolocation timezone [flags]

Flags

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4 or IPv6 address.
`--tz`	string	`""`	Timezone.
`--location`	string	`""`	Location name (e.g. New York)
`--latitude`	float64	`0`	Latitude (e.g. 37.7749).
`--longitude`	float64	`0`	Longitude (e.g. -122.4194).
`--lang`	string	`""`	Response language (if supported).
`--iata`	string	`""`	IATA code (e.g. DXB).
`--icao`	string	`""`	ICAO code (e.g. KATL).
`--lo`	string	`""`	LO code (e.g. DEBER).
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

Examples

Get timezone info about your current IP:

ipgeolocation timezone

Lookup a specific IP:

ipgeolocation timezone --ip 8.8.8.8

Lookup a specific timezone:

ipgeolocation timezone --tz America/New_York

Lookup a specific location:

ipgeolocation timezone --location New York

Lookup a specific latitude and longitude:

ipgeolocation timezone --latitude 37.7749 --longitude -122.4194

Lookup a specific IATA code:

ipgeolocation timezone --iata DXB

Lookup a specific ICAO code:

ipgeolocation timezone --icao KATL

Lookup a specific LO code:

ipgeolocation timezone --lo DEBER

Output as YAML:

ipgeolocation timezone --ip 8.8.8.8 --output=yaml

For further information, please visit Timezone API Documentation.

9. `time-conversion`

Convert between timezones using the ipgeolocation.io API.

Usage

ipgeolocation time-conversion [flags]

Flags

Flag	Type	Default	Description
`--tz_from`	string	`""`	Timezone to convert from.
`--tz_to`	string	`""`	Timezone to convert to.
`--location_from`	string	`""`	Location to convert from.
`--location_to`	string	`""`	Location to convert to.
`--lat_from`	float64	`0`	Latitude to convert from.
`--long_from`	float64	`0`	Longitude to convert from.
`--lat_to`	float64	`0`	Latitude to convert to.
`--long_to`	float64	`0`	Longitude to convert to.
`--iata_from`	string	`""`	IATA code to convert from.
`--iata_to`	string	`""`	IATA code to convert to.
`--icao_from`	string	`""`	ICAO code to convert from.
`--icao_to`	string	`""`	ICAO code to convert to.
`--lo_from`	string	`""`	LO code to convert from.
`--lo_to`	string	`""`	LO code to convert to.
`--time`	string	`""`	Time to convert.
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

Examples

Convert from one timezone to another:

ipgeolocation time-conversion --tz_from America/New_York --tz_to Europe/London

Convert from one location to another:

ipgeolocation time-conversion --location_from New York --location_to London

Convert from one latitude and longitude to another:

ipgeolocation time-conversion --lat_from 37.7749 --long_from -122.4194 --lat_to 51.509865 --long_to -0.118092

Convert from one IATA code to another:

ipgeolocation time-conversion --iata_from DXB --iata_to JFK

Convert from one ICAO code to another:

ipgeolocation time-conversion --icao_from KATL --icao_to EWR

Convert from one LO code to another:

ipgeolocation time-conversion --lo_from DEBER --lo_to JFK

Output as YAML:

ipgeolocation time-conversion --tz_from America/New_York --tz_to Europe/London --output=yaml

For further information, please visit Time Conversion API Documentation.

10. `astronomy`

The astronomy command uses the ipgeolocation.io Astronomy API to fetch astronomy-related data such as:

Sunrise and sunset
Solar noon
Moonrise and moonset
Moon phase
Day length
Timezone-based or coordinate-based location support

You can specify the location using IP, city name, coordinates, or timezone.

API Reference: https://ipgeolocation.io/astronomy-api.html

Usage

ipgeolocation astronomy [flags]

Flags

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4 or IPv6 address.
`--location`	string	`""`	City name.
`--latitude`	float64	`0`	Latitude.
`--longitude`	float64	`0`	Longitude.
`--lang`	string	`""`	Response language (if supported).
`--tz`	string	`""`	Timezone.
`--elevation`	float64	`0`	Elevation.
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

Examples

Get astronomy info about your current IP:

ipgeolocation astronomy

Get astronomy info about a specific location:

ipgeolocation astronomy --location "New York"

Get astronomy info about a specific timezone:

ipgeolocation astronomy --tz "America/New_York"

Get astronomy info about a specific latitude and longitude:

ipgeolocation astronomy --latitude 37.7749 --longitude -122.4194

Output as raw:

ipgeolocation astronomy --ip 8.8.8.8 --output=raw

For further information, please visit Astronomy API Documentation.

11. `astronomy-timeseries`

The astronomy-timeseries command uses the ipgeolocation.io Astronomy API to fetch astronomy-related data such as:

Sunrise and sunset
Solar noon
Moonrise and moonset
Moon phase
Day length
Timezone-based or coordinate-based location support

Usage

ipgeolocation astronomy-timeseries [flags]

Flags

Flag	Type	Default	Description
`--ip`	string	`""`	IPv4 or IPv6 address.
`--location`	string	`""`	City name.
`--latitude`	float64	`0`	Latitude.
`--longitude`	float64	`0`	Longitude.
`--lang`	string	`""`	Response language (if supported).
`--start-date`	string	`""`	Start date (e.g. 2023-01-01) Only YYYY-MM-DD.
`--end-date`	string	`""`	End date (e.g. 2023-12-31) Only YYYY-MM-DD
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

Note:

The start-date and end-date flags are required.
The start-date and end-date should be in YYYY-MM-DD format.
The start-date and end-date should be less than 90 days.

Examples

Get astronomy info about your current IP:

ipgeolocation astronomy-timeseries --start-date 2023-01-01 --end-date 2023-01-02

Get astronomy info about a specific location:

ipgeolocation astronomy-timeseries --location "New York" --start-date 2023-01-01 --end-date 2023-01-02

Get astronomy info about a specific latitude and longitude:

ipgeolocation astronomy-timeseries --latitude 37.7749 --longitude -122.4194 --start-date 2023-01-01 --end-date 2023-01-02

Output as raw:

ipgeolocation astronomy-timeseries --ip 8.8.8.8 --start-date 2023-01-01 --end-date 2023-01-02 --output=raw

For further information, please visit Astronomy Timeseries API Documentation.

12. `parse-user-agent`

The parse-user-agent command uses the ipgeolocation.io User Agent Parser API to parse user agent strings and extract relevant information such as:

Device type
Operating system
Browser
Browser version
Device vendor
Device model

Usage

ipgeolocation parse-user-agent [flags]

Flags

Flag	Type	Default	Description
`--user-agent`	string	`""`	User agent string.
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

Examples

Parse a user agent string:

ipgeolocation parse-user-agent --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36"

Output as raw:

ipgeolocation parse-user-agent --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36" --output=raw

For further information, please visit User Agent Parser API Documentation.

13. `parse-bulk-user-agents`

The parse-bulk-user-agents command uses the ipgeolocation.io Bulk User-Agent Parser API to parse multiple user agent strings and extract relevant information such as:

Device type
Operating system
Browser
Browser version
Device vendor
Device model

Usage

ipgeolocation parse-bulk-user-agents [flags]

Flags

Flag	Type	Default	Description
`--user-agents`	string[]	`[]`	User agent strings.
`--output`	string	`pretty`	Output format: `pretty`, `raw`, `table`, `yaml`.

Note:

The user-agents flag is required.
The user-agents flag should be an array of user agent strings.

Examples

Parse multiple user agent strings:

ipgeolocation parse-bulk-user-agents --user-agents "Mozilla/5.0 (Windows NT 10.0; Win64; x64)","curl/7.64.1"

Output as raw:

ipgeolocation parse-bulk-user-agents --user-agents "Mozilla/5.0 (Windows NT 10.0; Win64; x64)","curl/7.64.1" --output=raw

For further information, please visit Bulk User Agent Parser API Documentation.

License

This project is released under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
ascii		ascii
cmd		cmd
internal		internal
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
build-release.sh		build-release.sh
go.mod		go.mod
go.sum		go.sum

Uh oh!

License

Uh oh!

IPGeolocation/cli

Folders and files

Latest commit

History

Repository files navigation

ipgeolocation CLI Documentation

Table of Contents

Installation

1. Go install

2. Download and build from source

3. Download pre-built binaries

IPGeolocation CLI - Prebuilt Binaries Documentation

Overview

Prebuilt Binaries

Installation Instructions

1. Linux

2. macOS

3. Windows

Notes

Troubleshooting

Global Flags

Commands

1. config

Usage

Flags

2. ipgeo

Usage

Flags

Examples

3. bulk-ip-geo

Usage

Flags

Examples

Output Formats

4. ip-security

Usage

Flags

Examples

5. bulk-ip-security

Usage

Flags

Examples

6. asn

Usage

Flags

Examples

7. abuse

Usage

Flags

Examples

8. timezone

Usage

Flags

Examples

9. time-conversion

Usage

Flags

Examples

10. astronomy

Usage

Flags

Examples

11. astronomy-timeseries

Usage

Flags

Note:

Examples

12. parse-user-agent

Usage

Flags

Examples

13. parse-bulk-user-agents

Usage

Flags

Note:

Examples

License

1. `config`

2. `ipgeo`

3. `bulk-ip-geo`

4. `ip-security`

5. `bulk-ip-security`

6. `asn`

7. `abuse`

8. `timezone`

9. `time-conversion`

10. `astronomy`

11. `astronomy-timeseries`

12. `parse-user-agent`

13. `parse-bulk-user-agents`

Packages