ipwhoami 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vineeth Krishnan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# ipwhoami
+
+IP geolocation lookup from your terminal. Query multiple providers and compare results side-by-side.
+
+Works on **macOS**, **Linux**, and **Windows**. Zero dependencies.
+
+## Features
+
+- Look up geolocation for any IP address (or auto-detect yours)
+- Choose from 3 providers: [ipinfo.io](https://ipinfo.io), [ipapi.co](https://ipapi.co), [ip-api.com](http://ip-api.com)
+- Compare results across all providers at once
+- Raw JSON output for scripting and piping
+- No API keys required
+- Zero dependencies
+- Cross-platform: Node.js, Bash, and PowerShell
+
+## Install
+
+### npm (recommended)
+
+```bash
+npm install -g ipwhoami
+```
+
+Or run directly without installing:
+
+```bash
+npx ipwhoami 8.8.8.8
+```
+
+### Homebrew (macOS / Linux)
+
+```bash
+brew tap vineethkrishnan/ipwhoami
+brew install ipwhoami
+```
+
+### Scoop (Windows)
+
+```powershell
+scoop bucket add ipwhoami https://github.com/vineethkrishnan/scoop-ipwhoami
+scoop install ipwhoami
+```
+
+### Docker
+
+```bash
+docker run --rm vineethkrishnan/ipwhoami 8.8.8.8
+docker run --rm vineethkrishnan/ipwhoami -c 1.1.1.1
+```
+
+### Standalone Bash script (macOS / Linux)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/vineethkrishnan/ipwhoami/main/install.sh | bash
+```
+
+### Standalone PowerShell script (Windows)
+
+```powershell
+Invoke-WebRequest -Uri "https://raw.githubusercontent.com/vineethkrishnan/ipwhoami/main/scripts/ipwhoami.ps1" -OutFile "$HOME\ipwhoami.ps1"
+Add-Content $PROFILE 'Set-Alias ipwhoami "$HOME\ipwhoami.ps1"'
+```
+
+## Usage
+
+```
+ipwhoami [options] [ip]
+```
+
+### Options
+
+| Flag | Description |
+|------|-------------|
+| `-p, --provider NAME` | Use a specific provider: `ipinfo`, `ipapi`, `ip-api` (default: `ipinfo`) |
+| `-c, --compare` | Compare results from all providers |
+| `-r, --raw` | Output raw JSON |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
+
+### Examples
+
+```bash
+# Look up your own public IP
+ipwhoami
+
+# Look up a specific IP
+ipwhoami 8.8.8.8
+
+# Compare across all providers
+ipwhoami -c 1.1.1.1
+
+# Use a specific provider
+ipwhoami -p ipapi 8.8.8.8
+
+# Get raw JSON (great for piping)
+ipwhoami -r 8.8.8.8 | jq .city
+```
+
+### Sample Output
+
+```
+$ ipwhoami -c 8.8.8.8
+Comparing geolocation for: 8.8.8.8
+────────────────────────────────────────
+
+[ipinfo]
+  IP:        8.8.8.8
+  City:      Mountain View
+  Region:    California
+  Country:   US
+  Org:       AS15169 Google LLC
+  Location:  37.4056,-122.0775
+  Timezone:  America/Los_Angeles
+
+[ipapi]
+  IP:        8.8.8.8
+  City:      Mountain View
+  Region:    California
+  Country:   United States
+  Org:       Google LLC
+  Location:  37.4223, -122.085
+  Timezone:  America/Los_Angeles
+
+[ip-api]
+  IP:        8.8.8.8
+  City:      Mountain View
+  Region:    California
+  Country:   United States
+  ISP:       Google LLC
+  Location:  37.4056, -122.0775
+  Timezone:  America/Los_Angeles
+```
+
+## Providers
+
+| Provider | HTTPS | Rate Limit | Notes |
+|----------|-------|------------|-------|
+| [ipinfo.io](https://ipinfo.io) | Yes | 50k/month free | Default provider |
+| [ipapi.co](https://ipapi.co) | Yes | 1k/day free | Good detail |
+| [ip-api.com](http://ip-api.com) | No (HTTP) | 45/min free | Includes ISP info |
+
+## Adding a Provider
+
+Providers live in `src/providers/`. To add a new one:
+
+1. Create a new file in `src/providers/` (see existing ones for the pattern)
+2. Implement the `lookup(ip)` method returning a normalized result object
+3. Register it in `src/providers/index.js`
+
+## Project Structure
+
+```
+ipwhoami/
+├── bin/
+│   └── ipwhoami.js              # CLI entry point
+├── src/
+│   ├── cli.js                # Argument parsing & command routing
+│   ├── colors.js             # Terminal color helpers
+│   ├── config.js             # Constants & defaults
+│   ├── formatter.js          # Output formatting
+│   ├── ip.js                 # IP validation & public IP resolution
+│   └── providers/
+│       ├── base.js           # Shared HTTP fetch logic
+│       ├── index.js          # Provider registry
+│       ├── ipinfo.js         # ipinfo.io
+│       ├── ipapi.js          # ipapi.co
+│       └── ip-api.js         # ip-api.com
+├── scripts/
+│   ├── ipwhoami.sh              # Standalone Bash version
+│   └── ipwhoami.ps1             # Standalone PowerShell version
+├── test/                     # Unit & integration tests
+├── docs/                     # Starlight documentation site
+├── Dockerfile
+├── .github/workflows/
+│   ├── ci.yml                # Lint & test on PRs
+│   ├── release.yml           # Release Please + npm + Docker + Homebrew + Scoop
+│   └── deploy-docs.yml       # Cloudflare Pages docs deploy
+├── package.json
+├── CHANGELOG.md
+├── LICENSE
+└── README.md
+```
+
+## Release
+
+Releases are fully automated via [Release Please](https://github.com/googleapis/release-please):
+
+1. Push commits to `main` using [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, etc.)
+2. Release Please auto-creates a **Release PR** that bumps `package.json`, `src/config.js`, and `CHANGELOG.md`
+3. Merge the PR to trigger the full release pipeline:
+   - Creates a GitHub Release with auto-generated notes
+   - Publishes to npm
+   - Builds and pushes Docker images (Docker Hub + GHCR)
+   - Updates the Homebrew formula
+   - Updates the Scoop manifest
+
+## Requirements
+
+- **npm / Homebrew / Scoop**: Node.js >= 18
+- **Docker**: No requirements (Node.js included in image)
+- **Bash script**: `curl` + `jq`
+- **PowerShell script**: PowerShell 5.1+ or 7+
+
+## License
+
+[MIT](LICENSE)

package/bin/ipwhoami.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../src/cli.js';
+
+run(process.argv.slice(2));

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "ipwhoami",
+  "version": "1.0.0",
+  "description": "IP geolocation lookup from your terminal. Query multiple providers, compare results side-by-side.",
+  "type": "module",
+  "bin": {
+    "ipwhoami": "./bin/ipwhoami.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/ipwhoami.js",
+    "lint": "node --check src/**/*.js bin/**/*.js",
+    "test": "node --test test/config.test.js test/ip.test.js test/colors.test.js test/formatter.test.js test/providers.test.js test/cli.test.js",
+    "test:unit": "node --test test/config.test.js test/ip.test.js test/colors.test.js test/formatter.test.js test/providers.test.js",
+    "test:integration": "node --test test/cli.test.js"
+  },
+  "keywords": [
+    "ip",
+    "geolocation",
+    "ipinfo",
+    "ip-lookup",
+    "cli",
+    "terminal",
+    "network",
+    "geo",
+    "ipapi",
+    "ip-api",
+    "whois",
+    "location"
+  ],
+  "author": "Vineeth Krishnan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vineethkrishnan/ipwhoami.git"
+  },
+  "homepage": "https://github.com/vineethkrishnan/ipwhoami#readme",
+  "bugs": {
+    "url": "https://github.com/vineethkrishnan/ipwhoami/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,146 @@
+import { VERSION, DEFAULT_PROVIDER, PROVIDER_NAMES } from './config.js';
+import { bold, dim, green, red } from './colors.js';
+import { validateIP, getPublicIP } from './ip.js';
+import { getProvider, getAllProviders } from './providers/index.js';
+import { formatResult, formatRaw, formatCompareHeader } from './formatter.js';
+
+function printUsage() {
+  console.log(`${bold('ipwhoami')} - IP geolocation lookup from your terminal
+
+${bold('USAGE')}
+  ipwhoami [options] [ip]
+
+${bold('ARGUMENTS')}
+  ip                    IP address to look up (defaults to your public IP)
+
+${bold('OPTIONS')}
+  -p, --provider NAME   Use a specific provider: ${PROVIDER_NAMES.join(', ')} (default: ${DEFAULT_PROVIDER})
+  -c, --compare         Compare results from all providers
+  -r, --raw             Output raw JSON (no formatting)
+  -h, --help            Show this help message
+  -v, --version         Show version
+
+${bold('EXAMPLES')}
+  ipwhoami                          Look up your own public IP
+  ipwhoami 8.8.8.8                  Look up a specific IP
+  ipwhoami -c                       Compare your IP across all providers
+  ipwhoami -c 1.1.1.1              Compare a specific IP across all providers
+  ipwhoami -p ipapi 8.8.8.8        Use a specific provider
+  ipwhoami -r 8.8.8.8              Raw JSON output (pipe-friendly)`);
+}
+
+function parseArgs(argv) {
+  const opts = {
+    ip: null,
+    provider: DEFAULT_PROVIDER,
+    compare: false,
+    raw: false,
+    help: false,
+    version: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        opts.help = true;
+        break;
+      case '-v':
+      case '--version':
+        opts.version = true;
+        break;
+      case '-c':
+      case '--compare':
+        opts.compare = true;
+        break;
+      case '-r':
+      case '--raw':
+        opts.raw = true;
+        break;
+      case '-p':
+      case '--provider':
+        i++;
+        opts.provider = argv[i];
+        if (!opts.provider) {
+          die('--provider requires a value.');
+        }
+        break;
+      default:
+        if (arg.startsWith('-')) {
+          die(`unknown option: ${arg}. Use --help for usage.`);
+        }
+        opts.ip = arg;
+    }
+  }
+
+  return opts;
+}
+
+function die(message) {
+  console.error(`${red('error:')} ${message}`);
+  process.exit(1);
+}
+
+async function lookup(ip, providerName, raw) {
+  const provider = getProvider(providerName);
+  const result = await provider.lookup(ip);
+
+  if (raw) {
+    console.log(formatRaw(result));
+  } else {
+    console.log(formatResult(providerName, result));
+  }
+}
+
+async function compare(ip, raw) {
+  console.log(formatCompareHeader(ip));
+  console.log();
+
+  for (const { name, provider } of getAllProviders()) {
+    const result = await provider.lookup(ip);
+    if (raw) {
+      console.log(`// ${name}`);
+      console.log(formatRaw(result));
+    } else {
+      console.log(formatResult(name, result));
+    }
+    console.log();
+  }
+
+  console.log(dim('Done.'));
+}
+
+export async function run(argv) {
+  const opts = parseArgs(argv);
+
+  if (opts.help) {
+    printUsage();
+    return;
+  }
+
+  if (opts.version) {
+    console.log(`ipwhoami ${VERSION}`);
+    return;
+  }
+
+  let ip = opts.ip;
+
+  try {
+    if (!ip) {
+      console.log(dim('Fetching your public IP...'));
+      ip = await getPublicIP();
+      console.log(`${bold('Your IP:')} ${green(ip)}\n`);
+    } else {
+      validateIP(ip);
+    }
+
+    if (opts.compare) {
+      await compare(ip, opts.raw);
+    } else {
+      await lookup(ip, opts.provider, opts.raw);
+    }
+  } catch (err) {
+    die(err.message);
+  }
+}

package/src/colors.js

@@ -0,0 +1,11 @@
+const isTTY = process.stdout.isTTY;
+
+function wrap(code) {
+  return isTTY ? (s) => `\x1b[${code}m${s}\x1b[0m` : (s) => s;
+}
+
+export const bold = wrap('1');
+export const dim = wrap('2');
+export const cyan = wrap('36');
+export const green = wrap('32');
+export const red = wrap('31');

package/src/config.js

@@ -0,0 +1,7 @@
+export const VERSION = '1.0.0';
+
+export const SELF_IP_URL = 'https://api.ipify.org';
+
+export const DEFAULT_PROVIDER = 'ipinfo';
+
+export const PROVIDER_NAMES = ['ipinfo', 'ipapi', 'ip-api'];

package/src/formatter.js

@@ -0,0 +1,33 @@
+import { bold, cyan, dim } from './colors.js';
+
+const FIELDS = [
+  ['IP', 'ip'],
+  ['City', 'city'],
+  ['Region', 'region'],
+  ['Country', 'country'],
+  ['Org', 'org'],
+  ['Location', 'location'],
+  ['Timezone', 'timezone'],
+];
+
+export function formatResult(providerName, result) {
+  const lines = [cyan(bold(`[${providerName}]`))];
+
+  for (const [label, key] of FIELDS) {
+    const value = result[key] || 'n/a';
+    lines.push(`  ${label.padEnd(10)} ${value}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function formatRaw(result) {
+  return JSON.stringify(result, null, 2);
+}
+
+export function formatCompareHeader(ip) {
+  return [
+    `${bold('Comparing geolocation for:')} ${ip}`,
+    dim('\u2500'.repeat(40)),
+  ].join('\n');
+}

package/src/ip.js

@@ -0,0 +1,31 @@
+import { SELF_IP_URL } from './config.js';
+
+const IPV4_REGEX = /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+
+export function validateIP(ip) {
+  if (IPV4_REGEX.test(ip) || ip.includes(':')) {
+    return true;
+  }
+  throw new Error(`invalid IP address: ${ip}`);
+}
+
+export async function getPublicIP() {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 5000);
+
+  try {
+    const res = await fetch(SELF_IP_URL, { signal: controller.signal });
+    const text = (await res.text()).trim();
+    if (!text) {
+      throw new Error('got empty response when fetching public IP.');
+    }
+    return text;
+  } catch (err) {
+    if (err.name === 'AbortError') {
+      throw new Error('timed out fetching your public IP. Check your internet connection.');
+    }
+    throw new Error(`failed to fetch your public IP: ${err.message}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/providers/base.js

@@ -0,0 +1,19 @@
+export async function fetchJSON(url) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 10000);
+
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}`);
+    }
+    return await res.json();
+  } catch (err) {
+    if (err.name === 'AbortError') {
+      throw new Error(`request to ${url} timed out.`);
+    }
+    throw new Error(`request to ${url} failed: ${err.message}`);
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/providers/index.js

@@ -0,0 +1,21 @@
+import { ipinfo } from './ipinfo.js';
+import { ipapi } from './ipapi.js';
+import { ipApiCom } from './ip-api.js';
+
+const providers = new Map([
+  ['ipinfo', ipinfo],
+  ['ipapi', ipapi],
+  ['ip-api', ipApiCom],
+]);
+
+export function getProvider(name) {
+  const provider = providers.get(name);
+  if (!provider) {
+    throw new Error(`unknown provider: ${name}. Available: ${[...providers.keys()].join(', ')}`);
+  }
+  return provider;
+}
+
+export function getAllProviders() {
+  return [...providers.entries()].map(([name, provider]) => ({ name, provider }));
+}

package/src/providers/ip-api.js

@@ -0,0 +1,22 @@
+import { fetchJSON } from './base.js';
+
+export const ipApiCom = {
+  name: 'ip-api',
+  displayName: 'ip-api.com',
+  url: (ip) => `http://ip-api.com/json/${ip}`,
+
+  async lookup(ip) {
+    const data = await fetchJSON(this.url(ip));
+    return {
+      ip: data.query,
+      city: data.city,
+      region: data.regionName,
+      country: data.country,
+      org: data.isp,
+      location: data.lat && data.lon
+        ? `${data.lat}, ${data.lon}`
+        : undefined,
+      timezone: data.timezone,
+    };
+  },
+};

package/src/providers/ipapi.js

@@ -0,0 +1,22 @@
+import { fetchJSON } from './base.js';
+
+export const ipapi = {
+  name: 'ipapi',
+  displayName: 'ipapi.co',
+  url: (ip) => `https://ipapi.co/${ip}/json`,
+
+  async lookup(ip) {
+    const data = await fetchJSON(this.url(ip));
+    return {
+      ip: data.ip,
+      city: data.city,
+      region: data.region,
+      country: data.country_name,
+      org: data.org,
+      location: data.latitude && data.longitude
+        ? `${data.latitude}, ${data.longitude}`
+        : undefined,
+      timezone: data.timezone,
+    };
+  },
+};

package/src/providers/ipinfo.js

@@ -0,0 +1,20 @@
+import { fetchJSON } from './base.js';
+
+export const ipinfo = {
+  name: 'ipinfo',
+  displayName: 'ipinfo.io',
+  url: (ip) => `https://ipinfo.io/${ip}/json`,
+
+  async lookup(ip) {
+    const data = await fetchJSON(this.url(ip));
+    return {
+      ip: data.ip,
+      city: data.city,
+      region: data.region,
+      country: data.country,
+      org: data.org,
+      location: data.loc,
+      timezone: data.timezone,
+    };
+  },
+};