hrbrmstr.dev / geolocus-cli
CLI tool to work with ONYPHE's Geolocus mmdb
fork atom
TypeScript 100.0%
3 1 0

Clone this repository

https://tangled.org/hrbrmstr.dev/geolocus-cli https://tangled.org/did:plc:hgyzg2hn6zxpqokmp5c2xrdo/geolocus-cli
git@knot.hrbrmstr.app:hrbrmstr.dev/geolocus-cli git@knot.hrbrmstr.app:did:plc:hgyzg2hn6zxpqokmp5c2xrdo/geolocus-cli

For self-hosted knots, clone URLs may differ based on your setup.

Download tar.gz
README.md

Geolocus CLI#

A command-line tool for IP geolocation enrichment using the Geolocus database.

Features#

  • Download and cache the latest Geolocus database
  • Process IP addresses from files or stdin
  • Output results in multiple formats (JSON, JSONL, CSV)
  • Efficient caching of IP lookups during a session
  • Cross-platform compatibility

Installation#

Use one of the pre-built binaries in the releases or:

# Clone the repository
git clone https://codeberg.org/hrbrmstr/geolocus-cli.git
cd geolocus-cli

# Compile for your current platform
deno task compile

# Or compile for all platforms
deno task compile:all

Usage#

# Download the latest Geolocus database
geolocus-cli download

# Look up IPs from a file
geolocus-cli lookup -i ips.txt -o results.json

# Process IPs from stdin and output to stdout
cat ips.txt | geolocus-cli lookup

# Output in CSV format
geolocus-cli lookup -i ips.txt -f csv -o results.csv

# Output in JSONL format (one JSON object per line)
geolocus-cli lookup -i ips.txt -f jsonl -o results.jsonl

# Disable session caching
geolocus-cli lookup -i ips.txt --no-cache

Command-line Options#

Commands:
  download    Download a fresh copy of the geolocus.mmdb database
  lookup      Lookup and enrich IP addresses from a file or stdin

Options:
  -h, --help              Show help information
  -i, --input <file>      Input file containing IP addresses (one per line)
  -o, --output <file>     Output file for results (defaults to stdout)
  -f, --format <format>   Output format: json, csv, or jsonl (default: json)
  --no-cache              Disable IP caching for the current session

Examples:#

JSON#

./geolocus-cli lookup -i example-ips.txt

[
  {
    "ip": "8.8.8.8",
    "abuse": [
      "arin-contact@google.com",
      "network-abuse@google.com"
    ],
    "asn": "AS15169",
    "continent": "NA",
    "continentname": "North America",
    "country": "US",
    "countryname": "United States",
    "domain": [
      "google.com"
    ],
    "isineu": false,
    "latitude": "37.09024",
    "location": "37.09024,-95.712891",
    "longitude": "-95.712891",
    "netname": "GOGL",
    "organization": "Google LLC",
    "physical_asn": "AS15169",
    "physical_continent": "EU",
    "physical_continentname": "Europe",
    "physical_country": "DE",
    "physical_countryname": "Germany",
    "physical_isineu": true,
    "physical_latitude": "51.165691",
    "physical_location": "51.165691,10.451526",
    "physical_longitude": "10.451526",
    "physical_organization": "Google LLC",
    "physical_subnet": "8.8.8.0/31",
    "physical_timezone": "Europe/Berlin",
    "subnet": "8.8.8.0/24",
    "timezone": "America/Chicago",
    "cached": false
  },
  {
    "ip": "1.1.1.1",
    "abuse": [
      "helpdesk@apnic.net",
      "research@apnic.net",
      "resolver-abuse@cloudflare.com"
    ],
    "asn": "AS13335",
    "continent": "OC",
    "continentname": "Oceania",
    "country": "AU",
    "countryname": "Australia",
    "domain": [
      "apnic.net",
      "cloudflare.com",
      "one.one"
    ],
    "isineu": false,
    "latitude": "-25.274398",
    "location": "-25.274398,133.775136",
    "longitude": "133.775136",
    "netname": "APNIC-LABS",
    "organization": "APNIC Research and Development",
    "physical_asn": "AS13335",
    "physical_continent": "OC",
    "physical_continentname": "Oceania",
    "physical_country": "AU",
    "physical_countryname": "Australia",
    "physical_isineu": false,
    "physical_latitude": "-25.274398",
    "physical_location": "-25.274398,133.775136",
    "physical_longitude": "133.775136",
    "physical_organization": "Cloudflare, Inc.",
    "physical_subnet": "1.1.1.0/24",
    "physical_timezone": "Australia/Perth",
    "subnet": "1.1.1.0/24",
    "timezone": "Australia/Perth",
    "cached": false
  },
  {
    "ip": "192.168.1.1",
    "cached": false
  },
  {
    "ip": "172.217.14.206",
    "abuse": [
      "arin-contact@google.com",
      "network-abuse@google.com"
    ],
    "asn": "AS15169",
    "continent": "NA",
    "continentname": "North America",
    "country": "US",
    "countryname": "United States",
    "domain": [
      "1e100.net",
      "google.com"
    ],
    "isineu": false,
    "latitude": "37.09024",
    "location": "37.09024,-95.712891",
    "longitude": "-95.712891",
    "netname": "GOOGLE",
    "organization": "Google LLC",
    "physical_asn": "AS15169",
    "physical_continent": "NA",
    "physical_continentname": "North America",
    "physical_country": "US",
    "physical_countryname": "United States",
    "physical_isineu": false,
    "physical_latitude": "37.09024",
    "physical_location": "37.09024,-95.712891",
    "physical_longitude": "-95.712891",
    "physical_organization": "Google LLC",
    "physical_subnet": "172.217.0.0/24",
    "physical_timezone": "America/Chicago",
    "subnet": "172.217.0.0/16",
    "timezone": "America/Chicago",
    "cached": false
  },
  {
    "ip": "13.107.21.200",
    "abuse": [
      "abuse@microsoft.com",
      "averykim@microsoft.com",
      "dabedard@microsoft.com",
      "ioc@microsoft.com",
      "iphostmaster@microsoft.com",
      "msndcc@microsoft.com",
      "pracsin@microsoft.com",
      "secure@microsoft.com",
      "someshch@microsoft.com"
    ],
    "asn": "AS8075",
    "continent": "NA",
    "continentname": "North America",
    "country": "US",
    "countryname": "United States",
    "domain": [
      "microsoft.com"
    ],
    "isineu": false,
    "latitude": "37.09024",
    "location": "37.09024,-95.712891",
    "longitude": "-95.712891",
    "netname": "MSFT",
    "organization": "Microsoft Corporation",
    "physical_asn": "AS8075",
    "physical_continent": "AS",
    "physical_continentname": "Asia",
    "physical_country": "JP",
    "physical_countryname": "Japan",
    "physical_isineu": false,
    "physical_latitude": "36.204824",
    "physical_location": "36.204824,138.252924",
    "physical_longitude": "138.252924",
    "physical_organization": "Microsoft Corporation",
    "physical_subnet": "13.104.0.0/24",
    "physical_timezone": "Asia/Tokyo",
    "subnet": "13.104.0.0/14",
    "timezone": "America/Chicago",
    "cached": false
  }
]

JSONL/NDJSON#

./geolocus-cli lookup -i example-ips.txt --format jsonl | pbcopy

{"ip":"8.8.8.8","abuse":["arin-contact@google.com","network-abuse@google.com"],"asn":"AS15169","continent":"NA","continentname":"North America","country":"US","countryname":"United States","domain":["google.com"],"isineu":false,"latitude":"37.09024","location":"37.09024,-95.712891","longitude":"-95.712891","netname":"GOGL","organization":"Google LLC","physical_asn":"AS15169","physical_continent":"EU","physical_continentname":"Europe","physical_country":"DE","physical_countryname":"Germany","physical_isineu":true,"physical_latitude":"51.165691","physical_location":"51.165691,10.451526","physical_longitude":"10.451526","physical_organization":"Google LLC","physical_subnet":"8.8.8.0/31","physical_timezone":"Europe/Berlin","subnet":"8.8.8.0/24","timezone":"America/Chicago","cached":false}
{"ip":"1.1.1.1","abuse":["helpdesk@apnic.net","research@apnic.net","resolver-abuse@cloudflare.com"],"asn":"AS13335","continent":"OC","continentname":"Oceania","country":"AU","countryname":"Australia","domain":["apnic.net","cloudflare.com","one.one"],"isineu":false,"latitude":"-25.274398","location":"-25.274398,133.775136","longitude":"133.775136","netname":"APNIC-LABS","organization":"APNIC Research and Development","physical_asn":"AS13335","physical_continent":"OC","physical_continentname":"Oceania","physical_country":"AU","physical_countryname":"Australia","physical_isineu":false,"physical_latitude":"-25.274398","physical_location":"-25.274398,133.775136","physical_longitude":"133.775136","physical_organization":"Cloudflare, Inc.","physical_subnet":"1.1.1.0/24","physical_timezone":"Australia/Perth","subnet":"1.1.1.0/24","timezone":"Australia/Perth","cached":false}
{"ip":"192.168.1.1","cached":false}
{"ip":"172.217.14.206","abuse":["arin-contact@google.com","network-abuse@google.com"],"asn":"AS15169","continent":"NA","continentname":"North America","country":"US","countryname":"United States","domain":["1e100.net","google.com"],"isineu":false,"latitude":"37.09024","location":"37.09024,-95.712891","longitude":"-95.712891","netname":"GOOGLE","organization":"Google LLC","physical_asn":"AS15169","physical_continent":"NA","physical_continentname":"North America","physical_country":"US","physical_countryname":"United States","physical_isineu":false,"physical_latitude":"37.09024","physical_location":"37.09024,-95.712891","physical_longitude":"-95.712891","physical_organization":"Google LLC","physical_subnet":"172.217.0.0/24","physical_timezone":"America/Chicago","subnet":"172.217.0.0/16","timezone":"America/Chicago","cached":false}
{"ip":"13.107.21.200","abuse":["abuse@microsoft.com","averykim@microsoft.com","dabedard@microsoft.com","ioc@microsoft.com","iphostmaster@microsoft.com","msndcc@microsoft.com","pracsin@microsoft.com","secure@microsoft.com","someshch@microsoft.com"],"asn":"AS8075","continent":"NA","continentname":"North America","country":"US","countryname":"United States","domain":["microsoft.com"],"isineu":false,"latitude":"37.09024","location":"37.09024,-95.712891","longitude":"-95.712891","netname":"MSFT","organization":"Microsoft Corporation","physical_asn":"AS8075","physical_continent":"AS","physical_continentname":"Asia","physical_country":"JP","physical_countryname":"Japan","physical_isineu":false,"physical_latitude":"36.204824","physical_location":"36.204824,138.252924","physical_longitude":"138.252924","physical_organization":"Microsoft Corporation","physical_subnet":"13.104.0.0/24","physical_timezone":"Asia/Tokyo","subnet":"13.104.0.0/14","timezone":"America/Chicago","cached":false}

CSV#

./geolocus-cli lookup -i example-ips.txt --format csv | pbcopy

ip,abuse,asn,continent,continentname,country,countryname,domain,isineu,latitude,location,longitude,netname,organization,physical_asn,physical_continent,physical_continentname,physical_country,physical_countryname,physical_isineu,physical_latitude,physical_location,physical_longitude,physical_organization,physical_subnet,physical_timezone,subnet,timezone,cached
8.8.8.8,"arin-contact@google.com,network-abuse@google.com",AS15169,NA,North America,US,United States,google.com,false,37.09024,"37.09024,-95.712891",-95.712891,GOGL,Google LLC,AS15169,EU,Europe,DE,Germany,true,51.165691,"51.165691,10.451526",10.451526,Google LLC,8.8.8.0/31,Europe/Berlin,8.8.8.0/24,America/Chicago,false
1.1.1.1,"helpdesk@apnic.net,research@apnic.net,resolver-abuse@cloudflare.com",AS13335,OC,Oceania,AU,Australia,"apnic.net,cloudflare.com,one.one",false,-25.274398,"-25.274398,133.775136",133.775136,APNIC-LABS,APNIC Research and Development,AS13335,OC,Oceania,AU,Australia,false,-25.274398,"-25.274398,133.775136",133.775136,"Cloudflare, Inc.",1.1.1.0/24,Australia/Perth,1.1.1.0/24,Australia/Perth,false
192.168.1.1,,,,,,,,,,,,,,,,,,,,,,,,,,,,false
172.217.14.206,"arin-contact@google.com,network-abuse@google.com",AS15169,NA,North America,US,United States,"1e100.net,google.com",false,37.09024,"37.09024,-95.712891",-95.712891,GOOGLE,Google LLC,AS15169,NA,North America,US,United States,false,37.09024,"37.09024,-95.712891",-95.712891,Google LLC,172.217.0.0/24,America/Chicago,172.217.0.0/16,America/Chicago,false
13.107.21.200,"abuse@microsoft.com,averykim@microsoft.com,dabedard@microsoft.com,ioc@microsoft.com,iphostmaster@microsoft.com,msndcc@microsoft.com,pracsin@microsoft.com,secure@microsoft.com,someshch@microsoft.com",AS8075,NA,North America,US,United States,microsoft.com,false,37.09024,"37.09024,-95.712891",-95.712891,MSFT,Microsoft Corporation,AS8075,AS,Asia,JP,Japan,false,36.204824,"36.204824,138.252924",138.252924,Microsoft Corporation,13.104.0.0/24,Asia/Tokyo,13.104.0.0/14,America/Chicago,false

Data Storage#

The downloaded Geolocus database is stored in the standard XDG cache directory:

  • Linux/macOS: $XDG_CACHE_HOME/geolocus-cli/ or ~/.cache/geolocus-cli/
  • Windows: Similar location based on environment variables

License#

MIT