The ip2geo command line

Locate IP addresses, resolve domains, browse the ASN directory, and run your whole ip2geo account from the terminal: everything the SDK and the dashboard do.

$ ip2geo 8.8.8.8
8.8.8.8  · IPv4

  Location        Mountain View, California, United States 🇺🇸 (US)
  Coordinates     37.4056, -122.0775 (within 1,000 km)
  Time zone       America/Los_Angeles (14:26 there now)
  Network         AS15169 · Google LLC
  ...

Installing

npm i -g @ip2geo/cli

Or with Bun:

bun add -g @ip2geo/cli

Or run it once without installing: npx @ip2geo/cli 8.8.8.8, bunx @ip2geo/cli 8.8.8.8.

It needs Node.js 20 or newer (22 or newer for ip2geo live), or Bun, and has no dependencies. On a machine with Bun but no Node.js, run it with bunx --bun @ip2geo/cli, since the installed ip2geo starts with Node.

Signing in

Converting needs either a login or a secret API key.

ip2geo login                        # emails you a 6-digit code, as the dashboard's email sign-in does
ip2geo keys create "My laptop" --use  # optional: convert with an API key, 5,000 addresses per request

Accounts made with Google or GitHub sign in with the same email address. Without a terminal (CI), sign in in two steps: ip2geo login --email [email protected], then ip2geo login --email [email protected] --code 123456.

A code only signs in the address it was sent to, expires after 10 minutes, takes 5 tries and works once; an address can be sent one code a minute and 5 an hour. See Signing In.

An API key can also come from --key, from IP2GEO_API_KEY, or from ip2geo config set api-key <key>, in that order. Only secret keys (i2g_sk_) work here: public keys (i2g_pk_) only work in a browser, on their website's domain. A key only reaches its own project, so naming another with --project or IP2GEO_PROJECT converts through your login.

Quick lookups

ip2geo 8.8.8.8                             # one address, in full
ip2geo 8.8.8.8 1.1.1.1 2606:4700:4700::1111  # several, as a table
cat ips.txt | ip2geo -o csv > locations.csv  # any number, from a pipe or --file, 5,000 per request
ip2geo 8.8.8.8 --fields country_code       # just one field: prints "us"
ip2geo me                                  # the address you connect from
ip2geo github.com                          # a domain's addresses, located (free)
ip2geo dns github.com --type MX,TXT        # its DNS records (free)
ip2geo AS13335                             # a network from the ASN directory (free)
ip2geo ipv6 8.8.8.8                        # every IPv4 and IPv6 notation (offline)

Values that are not IP addresses are never sent, so they never cost a conversion. They are reported, and make the exit code 1 unless --skip-invalid drops them.

Commands

| Command | What it does | | --- | --- | | convert, me, domain, dns, asn, notation, validate, fields | Lookups, as in the SDK and the free tools | | conversions list, conversions get | Stored conversions, with --select, --search and --all | | login, logout, whoami, account, usage | Your account and this period's usage | | projects, keys, websites, members, invites | Everything on the dashboard's project pages | | analytics, live, billing | Analytics, the live view, plans, invoices and checkout | | config, status, completion, help, version | The CLI itself |

ip2geo help <command> shows a command's options. Keys, websites, members and projects can be named by id or by name.

Members are invited as admins or viewers. A project keeps one owner: nobody can be made an owner, the owner cannot be removed, and nobody removes themselves (ip2geo projects leave instead). Team Members lists what each role can do.

Scripting

Every command prints --json (or -o json, -o ndjson, -o csv) on stdout, and only messages on stderr, so output pipes cleanly. Lists stream: an interrupted run keeps everything already printed, and JSON stays a valid array.

| Exit code | Meaning | | --- | --- | | 0 | Done | | 1 | Failed (an API error, or some entries invalid or not converted) | | 2 | Wrong usage: an unknown command or option, a bad value | | 3 | Not signed in, or the key or role was refused | | 4 | Not found | | 5 | A limit was reached: the plan's conversions, the most keys, projects or members, or too many sign-in codes | | 6 | Network failure, timeout or maintenance | | 130 | Canceled with Ctrl+C |

Reads are retried on transient failures. Anything that spends conversions or changes your account is only retried when the request never left the machine, so nothing is ever converted or changed twice.

Configuration

ip2geo config lists the settings; config set and config unset change them (api-key, api-url, output, timeout, update-check). They live in ~/.config/ip2geo/config.json (%APPDATA%\ip2geo on Windows), readable only by you.

| Variable | Use | | --- | --- | | IP2GEO_API_KEY | API key, ahead of the config | | IP2GEO_PROJECT | Project for commands and, through a login, conversions (--project does the same once) | | IP2GEO_API_URL | Another API, like a local one | | IP2GEO_CONFIG_DIR, IP2GEO_CACHE_DIR | Where the config and the cache live | | IP2GEO_NO_UPDATE_CHECK | Never check npm for a newer version | | NO_COLOR, FORCE_COLOR | Colors off, or on everywhere |

Shell completion

source <(ip2geo completion zsh)    # or bash; add it to your shell's rc file
ip2geo completion fish > ~/.config/fish/completions/ip2geo.fish