ipwhoami 1.1.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +114 -126
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,66 +1,105 @@
1
- # ipwhoami
1
+ <p align="center">
2
+ <h1 align="center">ipwhoami</h1>
3
+ <p align="center">
4
+ <strong>IP geolocation lookup from your terminal</strong>
5
+ </p>
6
+ <p align="center">
7
+ Query multiple providers. Compare results side-by-side. Zero dependencies.
8
+ </p>
9
+ <p align="center">
10
+ <a href="https://www.npmjs.com/package/ipwhoami"><img src="https://img.shields.io/npm/v/ipwhoami?color=blue&label=npm" alt="npm version"></a>
11
+ <a href="https://github.com/vineethkrishnan/ipwhoami/actions/workflows/ci.yml"><img src="https://github.com/vineethkrishnan/ipwhoami/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
12
+ <a href="https://github.com/vineethkrishnan/ipwhoami/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/ipwhoami?color=green" alt="License"></a>
13
+ <a href="https://www.npmjs.com/package/ipwhoami"><img src="https://img.shields.io/npm/dm/ipwhoami?color=orange" alt="Downloads"></a>
14
+ <a href="https://img.shields.io/node/v/ipwhoami"><img src="https://img.shields.io/node/v/ipwhoami?color=brightgreen" alt="Node version"></a>
15
+ </p>
16
+ <p align="center">
17
+ <a href="https://ipwhoami-docs.vineethnk.in"><strong>Documentation</strong></a>
18
+ &nbsp;&bull;&nbsp;
19
+ <a href="https://github.com/vineethkrishnan/ipwhoami/issues">Report Bug</a>
20
+ &nbsp;&bull;&nbsp;
21
+ <a href="https://github.com/vineethkrishnan/ipwhoami/issues">Request Feature</a>
22
+ </p>
23
+ </p>
24
+
25
+ <br/>
2
26
 
3
- IP geolocation lookup from your terminal. Query multiple providers and compare results side-by-side.
4
-
5
- Works on **macOS**, **Linux**, and **Windows**. Zero dependencies.
6
-
7
- ## Features
27
+ ```bash
28
+ $ ipwhoami 8.8.8.8
8
29
 
9
- - Look up geolocation for any IP address (or auto-detect yours)
10
- - Choose from 3 providers: [ipinfo.io](https://ipinfo.io), [ipapi.co](https://ipapi.co), [ip-api.com](http://ip-api.com)
11
- - Compare results across all providers at once
12
- - Raw JSON output for scripting and piping
13
- - No API keys required
14
- - Zero dependencies
15
- - Cross-platform: Node.js, Bash, and PowerShell
30
+ [ipinfo]
31
+ IP 8.8.8.8
32
+ City Mountain View
33
+ Region California
34
+ Country US
35
+ Org AS15169 Google LLC
36
+ Location 37.4056,-122.0775
37
+ Timezone America/Los_Angeles
38
+ ```
16
39
 
17
- ## Install
40
+ <br/>
18
41
 
19
- ### npm (recommended)
42
+ ## Quick Start
20
43
 
21
44
  ```bash
45
+ # Install globally
22
46
  npm install -g ipwhoami
47
+
48
+ # Or run instantly without installing
49
+ npx ipwhoami 8.8.8.8
23
50
  ```
24
51
 
25
- Or run directly without installing:
52
+ ## Why ipwhoami?
53
+
54
+ - **Zero dependencies** — Uses Node.js 18+ built-in `fetch`. No bloated `node_modules`.
55
+ - **Multiple providers** — Query [ipinfo.io](https://ipinfo.io), [ipapi.co](https://ipapi.co), and [ip-api.com](http://ip-api.com) from one tool.
56
+ - **Compare mode** — See how providers differ for the same IP, side-by-side.
57
+ - **Pipe-friendly** — Raw JSON output for scripting, CI pipelines, and composing with `jq`.
58
+ - **Cross-platform** — npm, Homebrew, Scoop, Docker, standalone Bash & PowerShell scripts.
59
+ - **No API keys** — Works out of the box with free tiers.
60
+
61
+ ## Install
62
+
63
+ <table>
64
+ <tr><td><strong>npm</strong></td><td>
26
65
 
27
66
  ```bash
28
- npx ipwhoami 8.8.8.8
67
+ npm install -g ipwhoami
29
68
  ```
30
69
 
31
- ### Homebrew (macOS / Linux)
70
+ </td></tr>
71
+ <tr><td><strong>Homebrew</strong></td><td>
32
72
 
33
73
  ```bash
34
- brew tap vineethkrishnan/ipwhoami
35
- brew install ipwhoami
74
+ brew tap vineethkrishnan/ipwhoami && brew install ipwhoami
36
75
  ```
37
76
 
38
- ### Scoop (Windows)
77
+ </td></tr>
78
+ <tr><td><strong>Scoop</strong></td><td>
39
79
 
40
80
  ```powershell
41
81
  scoop bucket add ipwhoami https://github.com/vineethkrishnan/scoop-ipwhoami
42
82
  scoop install ipwhoami
43
83
  ```
44
84
 
45
- ### Docker
85
+ </td></tr>
86
+ <tr><td><strong>Docker</strong></td><td>
46
87
 
47
88
  ```bash
48
89
  docker run --rm vineethnkrishnan/ipwhoami 8.8.8.8
49
- docker run --rm vineethnkrishnan/ipwhoami -c 1.1.1.1
50
90
  ```
51
91
 
52
- ### Standalone Bash script (macOS / Linux)
92
+ </td></tr>
93
+ <tr><td><strong>Shell</strong></td><td>
53
94
 
54
95
  ```bash
55
96
  curl -fsSL https://raw.githubusercontent.com/vineethkrishnan/ipwhoami/main/install.sh | bash
56
97
  ```
57
98
 
58
- ### Standalone PowerShell script (Windows)
99
+ </td></tr>
100
+ </table>
59
101
 
60
- ```powershell
61
- Invoke-WebRequest -Uri "https://raw.githubusercontent.com/vineethkrishnan/ipwhoami/main/scripts/ipwhoami.ps1" -OutFile "$HOME\ipwhoami.ps1"
62
- Add-Content $PROFILE 'Set-Alias ipwhoami "$HOME\ipwhoami.ps1"'
63
- ```
102
+ > See the [Installation Guide](https://ipwhoami-docs.vineethnk.in/installation/) for all methods including PowerShell and manual install.
64
103
 
65
104
  ## Usage
66
105
 
@@ -68,11 +107,9 @@ Add-Content $PROFILE 'Set-Alias ipwhoami "$HOME\ipwhoami.ps1"'
68
107
  ipwhoami [options] [ip]
69
108
  ```
70
109
 
71
- ### Options
72
-
73
110
  | Flag | Description |
74
111
  |------|-------------|
75
- | `-p, --provider NAME` | Use a specific provider: `ipinfo`, `ipapi`, `ip-api` (default: `ipinfo`) |
112
+ | `-p, --provider NAME` | Provider: `ipinfo`, `ipapi`, `ip-api` (default: `ipinfo`) |
76
113
  | `-c, --compare` | Compare results from all providers |
77
114
  | `-r, --raw` | Output raw JSON |
78
115
  | `-h, --help` | Show help |
@@ -81,23 +118,14 @@ ipwhoami [options] [ip]
81
118
  ### Examples
82
119
 
83
120
  ```bash
84
- # Look up your own public IP
85
- ipwhoami
86
-
87
- # Look up a specific IP
88
- ipwhoami 8.8.8.8
89
-
90
- # Compare across all providers
91
- ipwhoami -c 1.1.1.1
92
-
93
- # Use a specific provider
94
- ipwhoami -p ipapi 8.8.8.8
95
-
96
- # Get raw JSON (great for piping)
97
- ipwhoami -r 8.8.8.8 | jq .city
121
+ ipwhoami # Your public IP
122
+ ipwhoami 8.8.8.8 # Specific IP
123
+ ipwhoami -c 1.1.1.1 # Compare all providers
124
+ ipwhoami -p ipapi 8.8.8.8 # Choose provider
125
+ ipwhoami -r 8.8.8.8 | jq .city # Raw JSON, pipe to jq
98
126
  ```
99
127
 
100
- ### Sample Output
128
+ ### Compare Mode
101
129
 
102
130
  ```
103
131
  $ ipwhoami -c 8.8.8.8
@@ -105,103 +133,63 @@ Comparing geolocation for: 8.8.8.8
105
133
  ────────────────────────────────────────
106
134
 
107
135
  [ipinfo]
108
- IP: 8.8.8.8
109
- City: Mountain View
110
- Region: California
111
- Country: US
112
- Org: AS15169 Google LLC
113
- Location: 37.4056,-122.0775
114
- Timezone: America/Los_Angeles
136
+ IP 8.8.8.8
137
+ City Mountain View
138
+ Region California
139
+ Country US
140
+ Org AS15169 Google LLC
141
+ Location 37.4056,-122.0775
142
+ Timezone America/Los_Angeles
115
143
 
116
144
  [ipapi]
117
- IP: 8.8.8.8
118
- City: Mountain View
119
- Region: California
120
- Country: United States
121
- Org: Google LLC
122
- Location: 37.4223, -122.085
123
- Timezone: America/Los_Angeles
145
+ IP 8.8.8.8
146
+ City Mountain View
147
+ Region California
148
+ Country United States
149
+ Org Google LLC
150
+ Location 37.4223, -122.085
151
+ Timezone America/Los_Angeles
124
152
 
125
153
  [ip-api]
126
- IP: 8.8.8.8
127
- City: Mountain View
128
- Region: California
129
- Country: United States
130
- ISP: Google LLC
131
- Location: 37.4056, -122.0775
132
- Timezone: America/Los_Angeles
154
+ IP 8.8.8.8
155
+ City Mountain View
156
+ Region California
157
+ Country United States
158
+ ISP Google LLC
159
+ Location 37.4056, -122.0775
160
+ Timezone America/Los_Angeles
133
161
  ```
134
162
 
135
163
  ## Providers
136
164
 
137
165
  | Provider | HTTPS | Rate Limit | Notes |
138
166
  |----------|-------|------------|-------|
139
- | [ipinfo.io](https://ipinfo.io) | Yes | 50k/month free | Default provider |
140
- | [ipapi.co](https://ipapi.co) | Yes | 1k/day free | Good detail |
141
- | [ip-api.com](http://ip-api.com) | No (HTTP) | 45/min free | Includes ISP info |
142
-
143
- ## Adding a Provider
144
-
145
- Providers live in `src/providers/`. To add a new one:
167
+ | [ipinfo.io](https://ipinfo.io) | Yes | 50k/month | Default |
168
+ | [ipapi.co](https://ipapi.co) | Yes | 1k/day | Full country names |
169
+ | [ip-api.com](http://ip-api.com) | No | 45/min | ISP info |
146
170
 
147
- 1. Create a new file in `src/providers/` (see existing ones for the pattern)
148
- 2. Implement the `lookup(ip)` method returning a normalized result object
149
- 3. Register it in `src/providers/index.js`
171
+ ## Contributing
150
172
 
151
- ## Project Structure
173
+ Contributions are welcome! ipwhoami uses a clean **provider pattern** — adding a new geolocation source is just one file + one line.
152
174
 
175
+ ```bash
176
+ git clone https://github.com/vineethkrishnan/ipwhoami.git
177
+ cd ipwhoami
178
+ node bin/ipwhoami.js 8.8.8.8 # zero dependencies, works immediately
153
179
  ```
154
- ipwhoami/
155
- ├── bin/
156
- │ └── ipwhoami.js # CLI entry point
157
- ├── src/
158
- │ ├── cli.js # Argument parsing & command routing
159
- │ ├── colors.js # Terminal color helpers
160
- │ ├── config.js # Constants & defaults
161
- │ ├── formatter.js # Output formatting
162
- │ ├── ip.js # IP validation & public IP resolution
163
- │ └── providers/
164
- │ ├── base.js # Shared HTTP fetch logic
165
- │ ├── index.js # Provider registry
166
- │ ├── ipinfo.js # ipinfo.io
167
- │ ├── ipapi.js # ipapi.co
168
- │ └── ip-api.js # ip-api.com
169
- ├── scripts/
170
- │ ├── ipwhoami.sh # Standalone Bash version
171
- │ └── ipwhoami.ps1 # Standalone PowerShell version
172
- ├── test/ # Unit & integration tests
173
- ├── docs/ # Starlight documentation site
174
- ├── Dockerfile
175
- ├── .github/workflows/
176
- │ ├── ci.yml # Lint & test on PRs
177
- │ ├── release.yml # Release Please + npm + Docker + Homebrew + Scoop
178
- │ └── deploy-docs.yml # Cloudflare Pages docs deploy
179
- ├── package.json
180
- ├── CHANGELOG.md
181
- ├── LICENSE
182
- └── README.md
183
- ```
184
-
185
- ## Release
186
180
 
187
- Releases are fully automated via [Release Please](https://github.com/googleapis/release-please):
181
+ See the [Contributing Guide](https://ipwhoami-docs.vineethnk.in/guides/contributing/) and [Adding a Provider](https://ipwhoami-docs.vineethnk.in/guides/adding-a-provider/) docs.
188
182
 
189
- 1. Push commits to `main` using [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, etc.)
190
- 2. Release Please auto-creates a **Release PR** that bumps `package.json`, `src/config.js`, and `CHANGELOG.md`
191
- 3. Merge the PR to trigger the full release pipeline:
192
- - Creates a GitHub Release with auto-generated notes
193
- - Publishes to npm
194
- - Builds and pushes Docker images (Docker Hub + GHCR)
195
- - Updates the Homebrew formula
196
- - Updates the Scoop manifest
183
+ ## Documentation
197
184
 
198
- ## Requirements
185
+ Full documentation is available at **[ipwhoami-docs.vineethnk.in](https://ipwhoami-docs.vineethnk.in)**
199
186
 
200
- - **npm / Homebrew / Scoop**: Node.js >= 18
201
- - **Docker**: No requirements (Node.js included in image)
202
- - **Bash script**: `curl` + `jq`
203
- - **PowerShell script**: PowerShell 5.1+ or 7+
187
+ - [Getting Started](https://ipwhoami-docs.vineethnk.in/getting-started/)
188
+ - [Installation](https://ipwhoami-docs.vineethnk.in/installation/)
189
+ - [CLI Reference](https://ipwhoami-docs.vineethnk.in/reference/cli-options/)
190
+ - [Providers](https://ipwhoami-docs.vineethnk.in/reference/providers/)
191
+ - [Adding a Provider](https://ipwhoami-docs.vineethnk.in/guides/adding-a-provider/)
204
192
 
205
193
  ## License
206
194
 
207
- [MIT](LICENSE)
195
+ [MIT](LICENSE) &copy; [Vineeth Krishnan](https://github.com/vineethkrishnan)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ipwhoami",
3
- "version": "1.1.1",
3
+ "version": "1.2.0",
4
4
  "description": "IP geolocation lookup from your terminal. Query multiple providers, compare results side-by-side.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -39,7 +39,7 @@
39
39
  "type": "git",
40
40
  "url": "git+https://github.com/vineethkrishnan/ipwhoami.git"
41
41
  },
42
- "homepage": "https://github.com/vineethkrishnan/ipwhoami#readme",
42
+ "homepage": "https://ipwhoami-docs.vineethnk.in",
43
43
  "bugs": {
44
44
  "url": "https://github.com/vineethkrishnan/ipwhoami/issues"
45
45
  },