IPinfo CLI: The Unix-Native Way to Query IP Geolocation at Scale

Hook

While most developers reach for web UIs or language-specific SDKs for IP lookups, the IPinfo CLI processes thousands of IPs per second through standard Unix pipes—no code required.

Context

IP geolocation has long suffered from a tooling gap. On one side, you have web interfaces—convenient for one-off lookups but useless for automation. On the other, language-specific SDKs that require writing scripts, managing dependencies, and deploying runtime environments just to answer simple questions like "where are these IPs coming from?" For DevOps engineers analyzing logs, security teams investigating incidents, or network administrators auditing traffic patterns, neither option fits naturally into existing shell-based workflows.

The IPinfo CLI emerged to fill this gap by treating IP data as a first-class Unix citizen. Built in Go and wrapping the IPinfo.io API, it provides both a unified command-line interface and a collection of standalone utilities that integrate seamlessly with grep, awk, and other standard tools. Instead of context-switching to web browsers or writing Python scripts for simple batch operations, you can pipe server logs directly through IP lookup commands and get structured output in seconds.

Technical Insight

The architecture of IPinfo CLI reflects a deliberate commitment to Unix philosophy: do one thing well, compose easily, and handle text streams naturally. The core binary (ipinfo) serves as the primary interface for API interactions, while specialized utilities (grepip, cidr2range, range2cidr, prips) ship as standalone executables. This dual distribution model is brilliant—teams can install just grepip to extract IP addresses from logs without pulling in the full API client, or use the unified ipinfo binary which includes all utilities as subcommands.

The streaming pipeline support is where the tool truly shines. Consider this real-world scenario: you have nginx access logs and need to identify which countries are hitting your API endpoints most frequently. With IPinfo CLI, it's a one-liner:

cat access.log | grepip | ipinfo bulk | jq -r '.country' | sort | uniq -c | sort -rn

The grepip utility extracts IP addresses from unstructured text (no regex wrestling), ipinfo bulk performs batch lookups with automatic rate limiting and concurrency management, and you pipe through standard Unix tools for aggregation. The bulk command reads from stdin and writes JSON objects to stdout—one per line—making it trivially composable. Behind the scenes, the CLI batches requests, handles retries, and manages authentication transparently.

For more complex workflows, the tool supports multiple output formats through flags. CSV output (--csv) integrates directly with spreadsheet tools or database imports, while JSON allows programmatic processing:

# Find all IPs from privacy VPN services in your traffic
cat access.log | grepip | ipinfo bulk --field privacy | jq 'select(.privacy.vpn == true)'

# Generate a summary report of IP ranges by organization
cat ip-list.txt | ipinfo bulk | ipinfo summarize

The summarize subcommand deserves special mention—it aggregates IP data into human-readable summaries by ASN, country, or custom fields, transforming thousands of individual lookups into actionable intelligence. This is where the CLI transcends simple API wrapping and becomes an analysis tool.

Authentication and caching show thoughtful engineering choices. API tokens live in ~/.ipinfo/config.json or the IPINFO_TOKEN environment variable, following standard conventions. The client-side cache (optional, enabled with --cache) stores responses locally to avoid redundant API calls during iterative analysis—essential when you're burning through your monthly quota. Cache TTL respects the API's data freshness guarantees while optimizing for repeated queries.

The standalone utilities deserve exploration beyond simple IP extraction. The cidr2range and range2cidr tools convert between CIDR notation and IP ranges, while prips (print IP addresses) generates all IPs in a range—invaluable for network scanning workflows:

# Generate all IPs in a subnet and check their geolocation
prips 10.0.1.0/24 | ipinfo bulk --field country

# Convert AWS IP ranges (published as CIDRs) to explicit ranges
curl -s https://ip-ranges.amazonaws.com/ip-ranges.json | \
  jq -r '.prefixes[].ip_prefix' | \
  cidr2range

Being written in Go means the CLI compiles to a single static binary with zero runtime dependencies. No Python virtual environments, no Node.js version managers, no Java classpaths—just download and run. The cross-compilation story is exceptional: the project ships binaries for Linux, macOS, Windows, FreeBSD, OpenBSD across amd64, arm64, and 386 architectures. Installation through native package managers (Homebrew, apt, scoop, AUR) removes the friction of manual binary management entirely.

Gotcha

The most significant limitation isn't in the CLI itself but in its API dependency model. All core geolocation functionality requires connectivity to IPinfo.io's servers—there's no offline mode or local database fallback. If you're analyzing IPs in air-gapped environments, during internet outages, or need guaranteed availability independent of a third-party service, this tool won't work. You'd need MaxMind's geoiplookup with locally downloaded MMDB files instead.

Rate limiting and quota exhaustion hit faster than you might expect. The free tier allows 50,000 requests per month, which sounds generous until you're processing production logs. A moderately busy web server generates thousands of unique IPs daily—run a week's worth of logs through bulk lookup and you've consumed your quota. The CLI doesn't include built-in quota monitoring or warnings; you'll only discover the limit when API calls start failing. Paid plans scale to millions of requests but represent ongoing operational costs. The caching helps, but only for repeated analysis of the same dataset—new log files mean new API calls. Also worth noting: bulk operations and certain data fields (like privacy detection or ASN details) require authentication even within your quota, so the completely anonymous free tier is limited to basic single-IP lookups.

Verdict

Use if: You're integrating IP geolocation into shell scripts, CI/CD pipelines, or log analysis workflows where Unix-style composition matters. The streaming bulk lookup capability and zero-dependency binary distribution make it ideal for DevOps automation, security incident response, and network administration tasks. It's also excellent if you're already using or planning to adopt IPinfo.io's API service—the CLI unlocks that investment for command-line productivity. Skip if: You need offline IP lookups without internet connectivity, require a different geolocation provider (MaxMind, IP2Location), or only perform occasional manual lookups where a web interface suffices. Also consider alternatives if you're processing massive datasets that would quickly exhaust API quotas, prefer self-hosted solutions for data sovereignty, or need more specialized OSINT features beyond basic geolocation.