cli

InternetData CLI

The official command line interface for the InternetData API.

List the IP and network databases your organization is licensed for, see what is inside one before you fetch it, and download it in CSV.GZ or MMDB, verified against its published checksum.

Getting Started

Every database command needs an API key carrying the db.download scope. internetdata login signs this machine in through your browser and stores one.

macOS

brew trust internetdata/tap
brew tap internetdata/tap
brew install internetdata

Homebrew won't load a formula from a third-party tap until you trust it. Skip that first line and it fails with invalid syntax in tap!, which is misleading: the formula is fine. brew trust arrived in Homebrew 7, so run brew update first if it comes back as an unknown command.

The CLI needs macOS 13 Ventura or later.

Debian / Ubuntu

Install from our apt repository, which keeps the CLI up to date with apt upgrade:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://apt.internetdata.io/public.key | sudo tee /etc/apt/keyrings/internetdata.asc > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/internetdata.asc] https://apt.internetdata.io/ /" | sudo tee /etc/apt/sources.list.d/internetdata.list
sudo apt update && sudo apt install internetdata

The repository is signed by the key with fingerprint 590AB7732517F95B056ED35317EA110D248C1B73, and apt refuses an index it did not sign. If you added the repository with [trusted=yes] before, replace that line with the one above: apt still installs from it, but warns on every update that it cannot check the signature.

Or install a single .deb without the repository:

curl -Ls https://github.com/internetdata/cli/releases/latest/download/deb.sh | sh

Windows

winget install InternetData.CLI

Or with Chocolatey:

choco install internetdata

Or install for the current user, which needs no admin rights:

iwr -useb https://github.com/internetdata/cli/releases/latest/download/windows.ps1 | iex

Docker

docker run --rm -e INTERNETDATA_API_KEY ghcr.io/internetdata/cli db list

Using go install

go install github.com/internetdata/cli@latest

The binary is named after the module, so rename it to internetdata if you want the examples below to read the same.

Using curl / wget

Binaries are published for 23 platform and architecture pairs on the releases page. Pick yours:

# Linux amd64; for Windows use ".zip" instead of ".tar.gz"
curl -LO https://github.com/internetdata/cli/releases/download/v1.4.13/internetdata_1.4.13_linux_amd64.tar.gz
tar -xzf internetdata_1.4.13_linux_amd64.tar.gz
sudo mv internetdata /usr/local/bin/

macOS has a one-line installer that picks the right architecture for you:

curl -Ls https://github.com/internetdata/cli/releases/latest/download/macos.sh | sh

Note that the binaries are not code-signed, so macOS Gatekeeper will ask before running one the first time, and Windows SmartScreen may warn.

From source

git clone https://github.com/internetdata/cli
cd cli
./scripts/build.sh

The result lands in build/. Go 1.26 or newer.

Quick Start

Default help message

Invoking the CLI with nothing shows what it can do:

$ internetdata
Usage: internetdata <cmd> [<opts>] [<args>]
...

Login

internetdata login opens your browser, you confirm a short code, and you pick which of your API keys this machine should hold:

$ internetdata login
opened your browser to finish signing in.

  https://app.internetdata.io/device

and confirm this code:  MA8A-T2WQ

waiting for you to approve...
stored key mk_9************************************Etjx in session "default", now active

Nothing is typed or pasted here, so the key never reaches your shell history. If no browser opens, the URL is printed and you can open it anywhere, including on your phone - which is what makes this work over SSH.

internetdata signup is the same thing with the sign-up page first, so a new account and a working CLI are one step.

For a CI job, set INTERNETDATA_API_KEY in the job's environment from your CI's secret store instead. Every command reads it, so nothing is stored on the runner, and the key never sits on a command line, where every account on the machine can read it from the process list:

$ export INTERNETDATA_API_KEY=...
$ internetdata db download vpn_ip_v1

internetdata login --paste prompts for one without opening a browser, and internetdata logout signs this machine out, which ends the authorization rather than only deleting the local file.

Sessions

Credentials are stored in named sessions, so one machine can hold several organizations' keys and switch between them without logging in again:

$ internetdata login --session work
$ internetdata login --session acme --base-url https://api.example.com
$ internetdata session list
   NAME     KEY                      API                      LAST USED
   acme     mk_4***************mnop  https://api.example.com  never
*  default  mk_1***************abcd  default                  never
   work     mk_9***************wxyz  default                  never

$ internetdata session use work
$ internetdata --session work db list    # one command, without switching

--base-url points a session at another deployment of the API; a session without one talks to https://internetdata.io.

A key can also come from --key or the INTERNETDATA_API_KEY environment variable, in that order of precedence. The config file is written 0600 inside a 0700 directory.

Who am I

$ internetdata whoami
key          mk_1************************abcd
from         session default
session      default
api          https://internetdata.io

DATABASE   STANDING  LICENSE   TERM
vpn_ip     licensed  standard  renews 2027-01-04
bogon_ip   licensed  standard

The databases listed are the ones your organization holds a license for, current, lapsed or yet to start; --json prints them as JSON. A license signed ahead of its start date reads expired until then, and its TERM says when it starts.

Databases

A license covers a database family, and a download names one of its versions, so the IDs below come from db list:

$ internetdata db list
ID            NAME      LICENSE   STANDING    TERM
vpn_ip_v1     VPN IP    standard  licensed    renews 2027-01-04
bogon_ip_v1   Bogon IP  standard  licensed
cdn_ip_v1     CDN IP              unlicensed

$ internetdata db metadata vpn_ip_v1
$ internetdata db checksum vpn_ip_v1 --format mmdb
$ internetdata db download vpn_ip_v1
$ internetdata db download vpn_ip_v1 --format mmdb vpn.mmdb
$ curl -fL "$(internetdata db url vpn_ip_v1)" -o vpn_ip_v1.csv.gz
$ internetdata db downloads

Every organization holds a standard license to the Open databases, bogon_ip_v1 and tor_ip_v1 among them, which are free under CC BY-SA 4.0. db list --json marks each one "open": true.

metadata carries the columns, the row count, the build date and the size of each file without downloading anything. Downloads are verified against the published sha256 and land through a .part file, so an interrupted transfer never leaves a truncated file that reads as a whole database. db url hands back a time-limited link that carries no API key, for a downloader or another machine. db downloads lists your organization's recent download attempts, refusals included, and marks the download of an evaluation sample (sample) beside its database.

Auto-Completion

Auto-completion is supported for at least the following shells:

bash
zsh
fish

It completes commands, flags, the values flags take, and the session names this machine actually holds.

NOTE: it may work for other shells as well, because the implementation is in Go and is not shell-specific.

Installation

Installing auto-completions is as simple as running one command, which covers bash, zsh and fish:

internetdata completion install

Start a new shell afterwards to pick it up.

If you want to customize the installation (for example when the auto-installation does not work as expected), you can request the completion line for each shell instead:

# get bash completion script
internetdata completion bash

# get zsh completion script
internetdata completion zsh

# get fish completion script
internetdata completion fish

internetdata completion uninstall removes it again.

Shell not listed?

If 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 internetdata binary itself.

Other Libraries

There are official InternetData client libraries available for many languages including PHP, Python, Go, Java, and Ruby. See our GitHub at https://github.com/internetdata for more.

About InternetData

Geolocation, anonymity, ownership and network databases for IP addresses and AS numbers, licensed as files you download and query yourself.

License

This project is licensed under the MIT License.