---
title: "MMDBio CLI | Read, Export, Import, Diff & Inspect MMDB Files"
slug: "/cli/mmdbio"
parent: "IP Geolocation CLI"
description: "MMDBio is a cross-platform command-line tool for working with MaxMind MMDB files, supporting read, metadata, export, import, diff, inspect, stats, and verify operations."
---

# MMDB CLI Tool Documentation

#### Overview

This documentation provides an overview and usage guide for the MMDB CLI tool. The tool allows working with MaxMind MMDB files including reading, exporting, comparing, inspecting, verifying, and viewing statistics.

* * *

## Installation

* * *

### 1. 1. Go install

To install `mmdbio` using `go install` , run:

```
go install github.com/IPGeolocation/mmdbio@latest
```

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

```
mmdbio --help
```

* * *

### 2. 2. Download and Build from Source

Ensure you have Go installed and set up. Clone the repository and build the CLI:

```
git clone github.com/IPGeolocation/mmdbio
cd mmdbio
go build -o mmdbio .
```

You can now use `./mmdbio` to run the CLI.

* * *

### 3. 3. Download Pre-Built Binaries

#### I. Overview

These are prebuilt binaries for the `mmdbio` tool. Users can download these files directly from GitHub Releases without needing to build from source.

The tool allows working with MaxMind DB files (MMDB) for geolocation purposes, including reading, converting, and analyzing `.mmdb` files.

#### II. Prebuilt Binaries

| Platform | Architecture | File Name |
| --- | --- | --- |
| Linux | amd64 | mmdbio-1.1.0-linux-amd64.tar.gz |
| Linux | arm64 | mmdbio-1.1.0-linux-arm64.tar.gz |
| macOS | amd64 | mmdbio-1.1.0-darwin-amd64.tar.gz |
| macOS | arm64 | mmdbio-1.1.0-darwin-arm64.tar.gz |
| Windows | amd64 | mmdbio-1.1.0-windows-amd64.zip |

#### III. Installation Instructions

##### i. 1. Linux

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

```
tar -xzf mmdbio-1.1.0-linux-amd64.tar.gz -C /usr/local/bin
```

1.  Rename the binary for simplicity:

```
mv /usr/local/bin/mmdbio-1.1.0-linux-amd64 /usr/local/bin/mmdbio
```

1.  Make the binary executable:

```
chmod +x /usr/local/bin/mmdbio
```

1.  Verify installation:

```
mmdbio --help
```

##### ii. 2. macOS

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

```
tar -xzf mmdbio-1.1.0-darwin-amd64.tar.gz -C /usr/local/bin
```

1.  Rename the binary:

```
mv /usr/local/bin/mmdbio-1.1.0-darwin-amd64 /usr/local/bin/mmdbio
```

1.  Make executable:

```
chmod +x /usr/local/bin/mmdbio
```

1.  Verify installation:

```
mmdbio --help
```

##### iii. 3. Windows

1.  Download the `.zip` file.
2.  Extract the `mmdbio-1.1.0-windows-amd64.exe` to a folder included in your system `PATH` .
3.  Rename the binary to `mmdbio.exe` for convenience.
4.  Open Command Prompt and verify:

```
mmdbio --help
```

##### iv. Notes

*   Ensure execution permissions on Linux/macOS.
*   Recommended folder for binaries: `/usr/local/bin` or any folder in your PATH.
*   For updates, check GitHub Releases.
*   If `go install` fails due to proxy caching, use:

```
GOPROXY=direct go install github.com/IPGeolocation/mmdbio@latest
```

##### v. 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.

* * *

## Commands

* * *

### 1. read

**Description:** Read IP data from an MMDB file. Supports single IP, batch input, or CIDR range.

**Flags:**

*   `--db` (required): Path to the `.mmdb` file.
*   `--ip` : Single IP to lookup.
*   `--fields` : Comma-separated list of fields to extract (e.g., `location.country.name,city.names.en` ).
*   `--input` : Path to file with IPs (or `-` for stdin).
*   `--out` : Optional output file path.
*   `--range` : CIDR range to lookup all IPs.

**Usage Examples:**

```
# Single IP lookup
mmdbio read --db GeoIP2-CitFlags:

--db (required): Path to the .mmdb file.
--sample-ip: Sample IP to inspect structure (defaults to 4.7.229.0 if not provided).
--out: Optional path to export schema as JSON.y.mmdb --ip 8.8.8.8

# Batch IP lookup from file
mmdbio read --db GeoIP2-City.mmdb --input ips.txt --out results.json

# CIDR range lookup
mmdbio read --db GeoIP2-City.mmdb --range 192.168.1.0/30
```

* * *

### 2. metadata

**Description:** Show metadata information from an MMDB file.

**Flags:**

*   `--db` (required): Path to the `.mmdb` file.

**Usage:**

```
mmdbio metadata --db GeoIP2-City.mmdb
```

* * *

### 3. export

**Description:** Export all records from an MMDB to JSON. Supports optional field and CIDR range filtering.

**Flags:**

*   `--db` (required): Path to the `.mmdb` file.
*   `--out` (required): Path to output JSON file.
*   `--fields` : Comma-separated list of fields to extract.
*   `--range` : Comma-separated CIDR ranges to filter networks.

**Usage:**

```
# Export entire database
mmdbio export --db GeoIP2-City.mmdb --out output.json

# Export with field filtering
mmdbio export --db GeoIP2-City.mmdb --fields location.country.name,city.names.en --out output.json

# Export only certain ranges
mmdbio export --db GeoIP2-City.mmdb --range 192.168.0.0/24,10.0.0.0/8 --out output.json
```

* * *

### 4. import

**Description:** Import JSON data into an MMDB file.

**Sample JSON:**

**Response Preview**

```json
{
  "2.2.2.2/32": {
    "fields": "anything"
  },
  "3.3.3.0-3.3.3.255": {
    "fields": "anything"
  }
}
```

**Flags:**

*   `--in, -i` (required): Input JSON file path (produced by the export command).
*   `--out, -o` (required): Output `.mmdb` file path.
*   `--ip` : IP version to import (4 or 6). Default is `6` .
*   `--size` : Record size for the MMDB file ( `24` , `28` , or `32` ). Default is `32` .
*   `--merge` : Merge strategy for duplicate entries. Options: `none` , `toplevel` , `recurse` . Default is `none` .
*   `--alias-6to4` : Enable IPv6 to IPv4 aliasing (for hybrid databases).
*   `--disallow-reserved` : Skip reserved IP ranges (e.g., `127.0.0.0/8` ).
*   `--title, -t` : Title for the `.mmdb` database. Default is `Custom-ip-database` .
*   `--description, -d` : Description for the `.mmdb` database. Default is `Custom IP Intelligence Database` .

**Usage:**

```
# Import IPv4 data
mmdbio import \
  --in ipv4_export.json \
  --out ipv4_data.mmdb \
  --ip 4 \
  --size 32

# Import IPv6 data
mmdbio import \
  --in ipv6_export.json \
  --out ipv6_data.mmdb \
  --ip 6

# Import mixed IPv4 + IPv6 data (requires aliasing)
mmdbio import \
  --in all_data.json \
  --out all.mmdb \
  --ip 6 \
  --alias-6to4

# Import while skipping reserved IPs
mmdbio import \
  --in dataset.json \
  --out filtered.mmdb \
  --disallow-reserved

# Import with custom title and description
mmdbio import \
  --in data.json \
  --out custom.mmdb \
  --title "Threat DB" \
  --description "Custom threat intelligence database"
```

**Notes:**

*   The input JSON must have CIDR blocks, single IPs, or IP ranges as keys, with metadata as values.
*   Nested maps and arrays are automatically converted into MMDB types.
*   Duplicate ranges are handled according to the `--merge` strategy.
*   Warnings for invalid entries are printed to `stderr` .

* * *

### 5. diff

**Description:** Compare two MMDB files and show differences. Lists networks that were added, removed, or modified.

**Flags:**

*   `--old` (required): Path to the old MMDB file.
*   `--new` (required): Path to the new MMDB file.
*   `--summary` : Show only summary counts.
*   `--json` : Output results as JSON.

**Usage:**

```
# Compare databases
mmdbio diff --old old.mmdb --new new.mmdb

# Summary only
mmdbio diff --old old.mmdb --new new.mmdb --summary

# JSON output
mmdbio diff --old old.mmdb --new new.mmdb --json
```

* * *

### 6. inspect

**Description:** Inspect MMDB structure and optionally export schema to JSON.

**Flags:**

*   `--db` (required): Path to the `.mmdb` file.
*   `--sample-ip` : Sample IP to inspect structure (defaults to `4.7.229.0` if not provided).
*   `--out` : Optional path to export schema as JSON.

**Usage:**

```
# Inspect database structure
mmdbio inspect --db GeoIP2-City.mmdb

# Inspect and export schema
mmdbio inspect --db GeoIP2-City.mmdb --out schema.json
```

* * *

### 7. stats

**Description:** Display statistics and metadata of an MMDB file.

**Flags:**

*   `--db` (required): Path to the `.mmdb` file.
*   `--json` : Output in JSON format.

**Usage:**

```
# View stats
mmdbio stats --db GeoIP2-City.mmdb

# View stats in JSON
mmdbio stats --db GeoIP2-City.mmdb --json
```

* * *

### 8. verify

**Description:** Verify the validity of an MMDB file.

**Flags:**

*   `--db` (required): Path to the `.mmdb` file.

**Usage:**

```
# Verify MMDB validity
mmdbio verify --db GeoIP2-City.mmdb
```

**Behavior:**

*   Prints `valid` if the MMDB is valid.
*   Prints `invalid` and error message if the MMDB is invalid.
*   Exit code `0` if valid, `1` if invalid.

* * *

### 9. completion

The `completion` command generates shell completion scripts for `mmdbio` , making it easier to use with Bash, Zsh, Fish, and PowerShell.

**Usage**

```
mmdbio completion [bash|zsh|fish|powershell]
```

**Available Shells**

*   `bash`
*   `zsh`
*   `fish`
*   `powershell`

**Examples**

_**Bash**_

Load completions for the current session:

```
source <(mmdbio completion bash)
```

Install completions permanently:

```
# Linux
mmdbio completion bash > /etc/bash_completion.d/mmdbio

# macOS
mmdbio completion bash > /usr/local/etc/bash_completion.d/mmdbio
```

_**Zsh**_

Load completions:

```
echo "autoload -U compinit; compinit" >> ~/.zshrc
mmdbio completion zsh > "${fpath[1]}/_mmdbio"
```

_**Fish**_

Load completions:

```
mmdbio completion fish | source
```

Install completions permanently:

```
mmdbio completion fish > ~/.config/fish/completions/mmdbio.fish
```

_**PowerShell**_

Load completions:

```
mmdbio completion powershell | Out-String | Invoke-Expression
```

Install completions permanently:

```
mmdbio completion powershell > mmdbio.ps1
```

**Notes**

*   Ensure that you use the appropriate file path for your shell when installing completions permanently.
*   The `completion` command supports exactly **one argument**, which must be one of the valid shells listed above.

* * *

## Examples

```
# Single IP lookup
mmdbio read --db GeoIP2-City.mmdb --ip 8.8.8.8 --fields location.country.name

# Export database
mmdbio export --db GeoIP2-City.mmdb --out export.json --fields location.country.name,city.names.en

# Compare old and new databases
mmdbio diff --old old.mmdb --new new.mmdb --summary

# Inspect database structure and export schema
mmdbio inspect --db GeoIP2-City.mmdb --out schema.json

# View statistics
mmdbio stats --db GeoIP2-City.mmdb --json

# Verify MMDB
mmdbio verify --db GeoIP2-City.mmdb
```