mmdbctl is an MMDB file management CLI by IPinfo.io that provides you
the following features:
- Read data for IPs in an MMDB file.
- Import data in non-MMDB format into MMDB.
- Export data from MMDB format into non-MMDB format.
- See the difference between two MMDB files.
- Print the metadata of an MMDB file.
- Check that an MMDB file is not corrupted or invalid.
The mmdbctl CLI is available for download via multiple mechanisms.
Install the latest amd64 version:
curl -Ls https://github.com/ipinfo/mmdbctl/releases/download/mmdbctl-1.4.6/macos.sh | shcurl -Ls https://github.com/ipinfo/mmdbctl/releases/download/mmdbctl-1.4.6/deb.sh | shOR
curl -LO https://github.com/ipinfo/mmdbctl/releases/download/mmdbctl-1.4.6/mmdbctl_1.4.6.deb
sudo dpkg -i mmdbctl_1.4.6.debNote: run powershell as administrator before executing this command.
iwr -useb https://github.com/ipinfo/mmdbctl/releases/download/mmdbctl-1.4.6/windows.ps1 | iexMake sure that $GOPATH/bin is in your $PATH, because that's where this gets
installed:
go install github.com/ipinfo/mmdbctl@latestThe pre-built binaries for all platforms are available on GitHub via artifacts in releases. You need to simply download, unpack and move them to your shell's binary search path.
The following OS & arch combinations are supported (if you use one not listed on here, please open an issue):
darwin_amd64
darwin_arm64
dragonfly_amd64
freebsd_386
freebsd_amd64
freebsd_arm
freebsd_arm64
linux_386
linux_amd64
linux_arm
linux_arm64
netbsd_386
netbsd_amd64
netbsd_arm
netbsd_arm64
openbsd_386
openbsd_amd64
openbsd_arm
openbsd_arm64
solaris_amd64
windows_386
windows_amd64
windows_arm
After choosing a platform PLAT from above, run:
# for Windows, use ".zip" instead of ".tar.gz"
curl -LO https://github.com/ipinfo/mmdbctl/releases/download/mmdbctl-1.4.6/mmdbctl_1.4.6_${PLAT}.tar.gz
# OR
wget https://github.com/ipinfo/mmdbctl/releases/download/mmdbctl-1.4.6/mmdbctl_1.4.6_${PLAT}.tar.gz
tar -xvf mmdbctl_1.4.6_${PLAT}.tar.gz
mv mmdbctl_1.4.6_${PLAT} /usr/local/bin/mmdbctlInstalling from source requires at least the Golang version specified in
go.mod. You can install the Golang toolchain from
the official site.
Once the correct Golang version is installed, simply clone the repository and install the binary:
git clone https://github.com/ipinfo/mmdbctl
cd mmdbctl
go install .
$GOPATH/bin/mmdbctlYou can add $GOPATH/bin to your $PATH to access mmdbctl directly from
anywhere.
Alternatively, you can do the following to output the binary somewhere specific:
git clone https://github.com/ipinfo/mmdbctl
cd mmdbctl
go build -o <path> .Replace <path> with the required location.
This will help you quickly get started with the mmdbctl CLI.
By default, invoking the CLI shows a help message:
You can read from MMDB files in various different ways - as individual IPs, CIDRs or IP ranges, coming from the command line as arguments, or from files, or from stdin.
Pretty JSON format:
$ mmdbctl read -f json-pretty 8.8.8.8 location.mmdb
{
"city": "Mountain View",
"country": "US",
"geoname_id": "5375480",
"latitude": "37.4056",
"longitude": "-122.0775",
"postalcode": "94043",
"region": "California",
"timezone": "America/Los_Angeles"
}CSV format:
$ mmdbctl read -f csv 8.8.8.8 location.mmdb
ip,city,country,geoname_id,latitude,longitude,postalcode,region,timezone
8.8.8.8,Mountain View,US,5375480,37.4056,-122.0775,94043,California,America/Los_AngelesTSV format:
$ mmdbctl read -f tsv 8.8.8.8 location.mmdb
ip city country geoname_id latitude longitude postalcode region timezone
8.8.8.8 Mountain View US 5375480 37.4056 -122.0775 94043 California America/Los_AngelesVia a file:
$ cat ips.txt
8.8.8.8
8.8.8.0/31
8.8.8.0-8.8.8.1
8.8.8.0,8.8.8.1
$ mmdbctl read ips.txt location.mmdb | sort -u
{"city":"Mountain View","country":"US","geoname_id":"5375480","latitude":"37.4056","longitude":"-122.0775","postalcode":"94043","region":"California","timezone":"America/Los_Angeles"}Via stdin:
$ echo 8.8.8.8 | mmdbctl read location.mmdb
{"city":"Mountain View","country":"US","geoname_id":"5375480","latitude":"37.4056","longitude":"-122.0775","postalcode":"94043","region":"California","timezone":"America/Los_Angeles"}Multiple inputs are also possible - these all return the same thing:
$ echo -e '8.8.8.8\n1.2.3.4' | mmdbctl read location.mmdb
$ mmdbctl read 8.8.8.8 1.2.3.4 location.mmdb
{"city":"Mountain View","country":"US","geoname_id":"5375480","latitude":"37.4056","longitude":"-122.0775","postalcode":"94043","region":"California","timezone":"America/Los_Angeles"}
{"city":"Brisbane","country":"AU","geoname_id":"2174003","latitude":"-27.48203","longitude":"153.01358","postalcode":"4101","region":"Queensland","timezone":"Australia/Brisbane"}Can check CIDRs and ranges - these will all return the same thing:
$ mmdbctl read 8.8.8.0/31 location.mmdb
$ mmdbctl read 8.8.8.0-8.8.8.1 location.mmdb
$ mmdbctl read 8.8.8.0,8.8.8.1 location.mmdb
{"city":"Mountain View","country":"US","geoname_id":"5375480","latitude":"37.4056","longitude":"-122.0775","postalcode":"94043","region":"California","timezone":"America/Los_Angeles"}
{"city":"Mountain View","country":"US","geoname_id":"5375480","latitude":"37.4056","longitude":"-122.0775","postalcode":"94043","region":"California","timezone":"America/Los_Angeles"}
{"city":"Mountain View","country":"US","geoname_id":"5375480","latitude":"37.4056","longitude":"-122.0775","postalcode":"94043","region":"California","timezone":"America/Los_Angeles"}Importing allows taking in files as CSV/TSV/JSON, and outputting an MMDB file.
Importing is one of the most powerful/flexible features in mmdbctl. However,
we only allow strings throughout the data at the current time.
See mmdbctl import --help for full details on usage.
Here are some basic examples:
# basic CSV importing into MMDB.
$ mmdbctl import --in data.csv --out data.mmdb
# generate MMDB from a TSV file containing IPv4 data.
$ cat data.tsv | mmdbctl import --ip 4 --tsv --out data.mmdb
# don't include the implicit `network` field in the output MMDB:
$ mmdbctl import --no-network --in data.csv --out data.mmdb
# generate an MMDB without any fields, just IP ranges that meet a criteria.
$ mmdbctl import \
--size 24 --no-fields --ip 4 \
--in anycast.csv --out anycast.mmdbExporting allows taking in an MMDB file and outputting CSV/TSV/JSON.
See mmdbctl export --help for full details on usage.
# basic export.
$ mmdbctl export data.mmdb data.csv
# basic export without a header.
$ mmdbctl export --no-header data.mmdb data.csv
# just see the number of entries it'd output.
$ mmdbctl export --no-header --format csv data.mmdb | wc -lYou can retrieve data in the metadata section of the MMDB file using the
metadata subcommand.
Pretty format:
$ mmdbctl metadata location.mmdb
- Binary Format 2.0
- Database Type ipinfo location.mmdb
- IP Version 4
- Record Size 32
- Node Count 123456789
- Description
en ipinfo location.mmdb
- Languages en
- Build Epoch 123456789JSON format:
$ mmdbctl metadata -f json location.mmdb
{
"binary_format": "2.0",
"db_type": "ipinfo location.mmdb",
"ip": 4,
"record_size": 32,
"node_count": 123456789,
"description": {
"en": "ipinfo location.mmdb"
},
"languages": [
"en"
],
"build_epoch": 123456789
}You can verify if a MMDB file is correctly structured with the verify
subcommand:
$ mmdbctl verify location.mmdb
validLet's force it to be invalid and check again:
$ cp location.mmdb location-tmp.mmdb
$ cat location.mmdb >> location-tmp.mmdb
$ mmdbctl verify location-tmp.mmdb
invalid: received decoding error (the MaxMind DB file's data section contains bad data (uint16 size of 11)) at offset of 13825601Auto-completion is supported for at least the following shells:
bash
zsh
fish
NOTE: it may work for other shells as well because the implementation is in Golang and is not necessarily shell-specific.
Installing auto-completions is as simple as running one command (works for
bash, zsh and fish shells):
mmdbctl completion installIf you want to customize the installation process (e.g. in case the auto-installation doesn't work as expected), you can request the actual completion script for each shell:
# get bash completion script
mmdbctl completion bash
# get zsh completion script
mmdbctl completion zsh
# get fish completion script
mmdbctl completion fishIf your shell is not listed here, you can open an issue.
Note that as long as the COMP_LINE environment variable is provided to the
binary itself, it will output completion results. So if your shell provides a
way to pass COMP_LINE on auto-completion attempts to a binary, then have your
shell do that with the mmdbctl binary itself (or any of our binaries).
All our CLIs respect either the --nocolor flag or the
NO_COLOR environment variable to disable color
output.
To enable color support for the Windows command prompt, run the following to
enable Console Virtual Terminal Sequences.
REG ADD HKCU\CONSOLE /f /v VirtualTerminalLevel /t REG_DWORD /d 1You can disable this by running the following:
REG DELETE HKCU\CONSOLE /f /v VirtualTerminalLevelThere are official IPinfo client libraries available for many languages including PHP, Python, Go, Java, Ruby, and many popular frameworks such as Django, Rails and Laravel. There are also many third party libraries and integrations available for our API.
See https://ipinfo.io/developers/libraries for more details.
Founded in 2013, IPinfo prides itself on being the most reliable, accurate, and in-depth source of IP address data available anywhere. We process terabytes of data to produce our custom IP geolocation, company, carrier, VPN detection, hosted domains, and IP type data sets. Our API handles over 40 billion requests a month for businesses and developers.
