Binary reference

ip-fetch

IP Geolocation data fetcher for Kodachi OS - Fetches and displays IP address information including geolocation, ISP, and network details

Version10.0.1 (build 1)Size8.8MBAuthorWarith Al MaawaliLicenseProprietaryWebsitehttps://www.digi77.com

File Information

Property	Value
Binary Name	ip-fetch
Version	10.0.1 (build 1)
Build Date	Not disclosed
Rust Version	1.82.0
File Size	8.8MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	IP Geolocation data fetcher for Kodachi OS - Fetches and displays IP address information including geolocation, ISP, and...
Git Commit	unknown
Metadata Generated	2026-09-10T20:35:22Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

d62bfd9d7abbb68999b447cd655fe55ef71956649c51f74961ca86ecb1593307

Features

#	Feature
1	Multi-source IP geolocation with fallback support
2	IPv4 and IPv6 dual-stack support
3	Bulk IP lookup with optimized performance
4	Offline mode with cached data
5	VPN and proxy detection
6	ISP and organization information
7	Secure API communication with certificate pinning
8	Rate limiting and retry logic
9	Comprehensive error handling

Security Features

Feature	Description
Authentication	Not provided by cli-core (see online-auth)
Encryption	Not provided by cli-core
Input Validation	Argument parsing via clap; per-command validation is the consumer's responsibility
Rate Limiting	Not provided by cli-core

System Requirements

Requirement	Value
OS	Linux (Debian-based)
Privileges	root/sudo for system operations
Dependencies	OpenSSL, libcurl

Global Options

Flag	Description
`-h, --help`	Print help information
`-v, --version`	Print version information
`-n, --info`	Display detailed information
`-e, --examples`	Show usage examples
`--json`	Output in JSON format
`-o, --output-format <FORMAT>`	Force output format (text\|json)
`--json-pretty`	Pretty-print JSON output with indentation
`--json-human`	Enhanced JSON output with improved formatting (like jq)
`--json-filter <FIELD1,FIELD2>`	Return only specified JSON fields (comma-separated)
`--fields <FIELD_LIST>`	Select specific fields to include in output (comma-separated)
`--limit <NUMBER>`	Limit number of results returned
`--offset <NUMBER>`	Skip first N results (for pagination)
`-d, --work-dir <PATH>`	Working directory (defaults to auto-detected base directory)
`--port <PORT>`	Set custom port number (1024-65535)
`--log-level <LEVEL>`	Set log level (error\|warn\|info\|debug)
`--verbose`	Enable verbose output
`--quiet`	Suppress non-essential output
`--no-color`	Disable colored output
`--config <FILE>`	Use custom configuration file
`--timeout <SECS>`	Set operation timeout in seconds (optional; no default applied)

Commands

Basic Operations

`plain-ip`

Simple plain text IP address retrieval

Usage:

ip-fetch plain-ip [OPTIONS]

Options:

-4, --ipv4: Return the IPv4 address (default)
-6, --ipv6: Return the IPv6 address
--both: Dual-stack is unsupported for this subcommand and is rejected at runtime. Use 'ip-fetch --both' instead
--server-index <INDEX>: Use one specific plain-text server by its index instead of the default

Examples:

ip-fetch plain-ip --ipv4

ip-fetch plain-ip --ipv6

ip-fetch plain-ip --ipv4 --server-index 5

Cache Management

`cache`

Manage IP cache for improved performance

Usage:

ip-fetch cache [OPTIONS]

Options:

status: Show cache statistics and status (subcommand)
list: List every cached IP address (subcommand)
clear [IP]: Clear the whole cache, or only the given IP (subcommand)
set-ttl <TTL>: Set the default cache TTL, e.g. 24h, 7d, 1w (subcommand)

Examples:

ip-fetch cache status

ip-fetch cache list

ip-fetch cache clear 208.67.222.222

ip-fetch cache clear

ip-fetch cache set-ttl 24h

Comprehensive Testing

`test-all`

Complete test suites for all functionality

Usage:

ip-fetch test-all [OPTIONS]

Options:

--include-tor: Also run the Tor SOCKS proxy tests
--socks-port <PORT>: Force the Tor SOCKS port used by --include-tor instead of auto-probing
--verbose: Show per-source detail instead of the summary (cli-core global flag)

Examples:

ip-fetch test-all

ip-fetch test-all --verbose

ip-fetch test-all --include-tor

ip-fetch test-all --include-tor --socks-port 10000 --json

DNS Operations

`dns`

DNS-based IP resolution and testing

Usage:

ip-fetch dns [OPTIONS]

Options:

-4, --ipv4: Resolve over IPv4 DNS queries (default)
-6, --ipv6: Resolve over IPv6 DNS queries
--both: Dual-stack is unsupported for this subcommand and is rejected at runtime. Use 'ip-fetch --both' instead
--query-index <INDEX>: Run one specific DNS query by index, or 'all' for every query

Examples:

ip-fetch dns --ipv4

ip-fetch dns --ipv4 --query-index 0

ip-fetch dns --ipv6 --query-index all --json

Geolocation Services

`geo`

Geolocation API testing with various IPs

Usage:

ip-fetch geo [OPTIONS]

Options:

--ip <IP>: IP address to geolocate. Omit to use your current IP

Examples:

ip-fetch geo

ip-fetch geo --ip 208.67.222.222

ip-fetch geo --ip 1.1.1.1 --json

IP Operations

`fetch`

Fetch IP geolocation information (default command)

Usage:

ip-fetch fetch [OPTIONS]

Options:

<IP>...: IP addresses to look up. Omit to look up your own public IP
-4, --ipv4: Request IPv4 only (default behavior)
-6, --ipv6: Request IPv6 only
--both: Request both IPv4 and IPv6 in one call
--bulk: Force bulk mode. Requires online-auth authentication
--nobulk: Disable bulk mode, look each IP up individually
--server <URL>: Use a custom server URL for the lookup
--nohistory: Do not save this lookup to the IP history
--no-cache: Bypass the cache and fetch fresh data
--cache-only: Serve from cache only, fail if the IP is not cached
--refresh-cache: Refresh the cache even if it is still valid

Examples:

ip-fetch

ip-fetch fetch

ip-fetch 208.67.222.222 --json

ip-fetch --both

ip-fetch --no-cache

ip-fetch --cache-only 208.67.222.222

ip-fetch --nohistory

ip-fetch --bulk 1.1.1.1 9.9.9.9 208.67.222.222

Network Testing

`tor`

Test IP lookup through Tor SOCKS proxy

Usage:

ip-fetch tor [OPTIONS]

Options:

<SCOPE>: Pass 'all' to query every source (positional). Default is one random source
-4, --ipv4: Request IPv4 only (default)
-6, --ipv6: Request IPv6 only
--both: Dual-stack is unsupported for this subcommand and is rejected at runtime. Use 'ip-fetch --both' instead
--socks-port <PORT>: Force a SOCKS port. Without it, 9050, 9150 and the Kodachi pool 10000-10019 are auto-probed
--torsafe: Use only the 14 Tor-safe IPv4 URLs instead of all 19

Examples:

ip-fetch tor

ip-fetch tor --ipv4

ip-fetch tor --ipv4 all --torsafe

ip-fetch tor --ipv4 --socks-port 9150

ip-fetch tor --ipv6 all --json

`check-tor`

Check if connection is using Tor network

Usage:

ip-fetch check-tor [OPTIONS]

Options:

--ip-only: Print only the IP address (mutually exclusive with --status-only)
--status-only: Print only the Tor status, true or false (mutually exclusive with --ip-only)

Examples:

ip-fetch check-tor

ip-fetch check-tor --status-only

ip-fetch check-tor --ip-only

ip-fetch check-tor --json

Testing Operations

`test-fallback`

Test fallback mechanisms and multiple source verification

Usage:

ip-fetch test-fallback [OPTIONS]

Options:

<FORMAT>: Source format to exercise: 'json' or 'plain' (positional)
-4, --ipv4: Test IPv4 sources (default)
-6, --ipv6: Test IPv6 sources
--both: Dual-stack is unsupported for this subcommand and is rejected at runtime. Use 'ip-fetch --both' instead

Examples:

ip-fetch test-fallback --ipv4 json

ip-fetch test-fallback --ipv4 plain

ip-fetch test-fallback --ipv6 json --json

`verify-multi`

Verify multiple sources

Usage:

ip-fetch verify-multi [OPTIONS]

Options:

-4, --ipv4: Verify across all IPv4 sources (default)
-6, --ipv6: Verify across all IPv6 sources
--both: Dual-stack is unsupported for this subcommand and is rejected at runtime. Use 'ip-fetch --both' instead
--verbose: Show each source's raw response (cli-core global flag)

Examples:

ip-fetch verify-multi --ipv4

ip-fetch verify-multi --ipv4 --verbose

ip-fetch verify-multi --ipv6 --json

`random`

Test random server selection functionality

Usage:

ip-fetch random [OPTIONS]

Options:

--type <TYPE>: Source type: plain, json or dns
-4, --ipv4: Pick a random IPv4 source (default)
-6, --ipv6: Pick a random IPv6 source

Examples:

ip-fetch random --type plain --ipv4

ip-fetch random --type json --ipv4 --json

ip-fetch random --type dns --ipv6 --json

Operational Scenarios

Scenario-oriented workflows generated from the binary's built-in -e --json examples.

Scenario 1: Usage Examples

Common usage patterns for ip-fetch

Step 1: Get your current public IP

ip-fetch

Expected Output: Current IP with geolocation data

Step 2: Run the default fetch command explicitly

ip-fetch fetch

Expected Output: Current IP with geolocation data

Note

Equivalent to the bare ip-fetch command

Step 3: Show usage examples

ip-fetch --examples

Expected Output: Display all usage patterns

Scenario 2: Basic Usage

Common IP lookup operations

Step 1: Get your current public IP from Kodachi Cloud (primary) with automatic fallback

ip-fetch

Expected Output: Current IP with geolocation data

Step 2: Look up specific IP address

ip-fetch 208.67.222.222

Expected Output: Geolocation data for 208.67.222.222

Step 3: Look up multiple IP addresses

ip-fetch 208.67.222.222 1.1.1.1

Expected Output: Bulk lookup results

Note

Automatically uses bulk mode for better performance

Step 4: Force refresh cache and get latest IP data

ip-fetch --refresh-cache

Expected Output: Fresh IP data bypassing cache

Scenario 3: Output Formats

Different ways to format output

Step 1: Get your current IP in JSON format from primary source with fallback

ip-fetch --json

Expected Output: JSON object with complete IP information

Step 2: Formatted JSON with indentation

ip-fetch --json-pretty

Expected Output: Pretty-printed JSON output

Step 3: Enhanced human-readable JSON output with colors (like jq)

ip-fetch --json-human

Expected Output: Colorized JSON output for better readability

Scenario 4: Basic IP Lookups

Own IP lookup and single IP lookup operations

Step 1: Explicitly request IPv4 from primary source with fallback

ip-fetch --ipv4

Expected Output: Shows your IPv4 address with geolocation data

Step 2: Get your current public IPv6 from Kodachi Cloud (primary) with automatic fallback

ip-fetch --ipv6

Expected Output: Shows your IPv6 address with geolocation data

Step 3: Get your IPv6 in JSON format from primary source with fallback

ip-fetch --ipv6 --json

Expected Output: JSON object with IPv6 geolocation data

Step 4: Get both IPv4 and IPv6 information from primary sources with fallback

ip-fetch --both

Expected Output: Shows both IPv4 and IPv6 with full details

Step 5: Get both IPs in JSON format from primary sources with fallback

ip-fetch --both --json

Expected Output: JSON object with both IPv4 and IPv6 data

Scenario 5: Fallback and Multi-Source Testing

Exercise the fallback chain (test-fallback walks sources until one answers) and cross-check every source against the others (verify-multi). Both work on one IP family at a time.

Step 1: Test IPv4 JSON sources with automatic fallback

ip-fetch test-fallback --ipv4 json

Expected Output: IPv4 JSON fallback test results

Step 2: Test IPv6 JSON sources with automatic fallback

ip-fetch test-fallback --ipv6 json --json

Expected Output: IPv6 JSON fallback test results in JSON format

Step 3: Test IPv4 plain text sources with automatic fallback

ip-fetch test-fallback --ipv4 plain

Expected Output: IPv4 plain text fallback results

Step 4: Test IPv6 plain text sources with automatic fallback

ip-fetch test-fallback --ipv6 plain

Expected Output: IPv6 plain text fallback results

Step 5: Test ALL IPv4 sources to verify consistency

ip-fetch verify-multi --ipv4

Expected Output: IPv4 multi-source verification report

Note

verify-multi is authentication gated. On an unauthenticated shell it fails with 'Authentication required'. Run 'online-auth authenticate' first.

Step 6: Verify all IPv4 sources and print each source's raw response

ip-fetch verify-multi --ipv4 --verbose

Expected Output: Per-source responses followed by the consistency verdict

Step 7: Test ALL IPv6 sources with JSON output

ip-fetch verify-multi --ipv6 --json

Expected Output: JSON IPv6 multi-source verification

Scenario 6: Tor Detection

Check if your connection is using Tor

Step 1: Check if connection is using Tor and show IP

ip-fetch check-tor

Expected Output: Tor status and current IP address

Step 2: Get just the IP address

ip-fetch check-tor --ip-only

Expected Output: Your current IP address

Step 3: Get just the Tor status

ip-fetch check-tor --status-only

Expected Output: true or false

Step 4: Get Tor status and IP in JSON format

ip-fetch check-tor --json

Expected Output: JSON object with IsTor and IP fields

Step 5: Pretty-printed JSON output

ip-fetch check-tor --json-pretty

Expected Output: Formatted JSON with Tor status

Step 6: Colorized JSON output (like jq)

ip-fetch check-tor --json-human

Expected Output: Colored JSON with Tor status

Scenario 7: Tor Network Testing

Route the IP lookup through a Tor SOCKS5 proxy. Tor must already be running: without a reachable SOCKS port every source fails. Pass 'all' to query every source instead of one random source. This subcommand handles IPv4 or IPv6, not both at once.

Step 1: Get IPv4 through Tor SOCKS5 proxy from ONE random source

ip-fetch tor --ipv4

Expected Output: IP address via Tor proxy

Step 2: Test ALL IPv4 sources through Tor SOCKS5 proxy

ip-fetch tor --ipv4 all

Expected Output: Comprehensive Tor IPv4 test results

Step 3: Test ALL IPv6 sources through Tor SOCKS5 proxy with JSON output

ip-fetch tor --ipv6 all --json

Expected Output: JSON array with all Tor IPv6 results

Step 4: Get IPv4 JSON response through Tor SOCKS5 proxy

ip-fetch tor --ipv4 --json

Expected Output: JSON IPv4 data via Tor

Step 5: Default IPv4 source via Tor (auto-detects local SOCKS5: 9050, 9150, or Kodachi pool 10000-10019)

ip-fetch tor

Expected Output: IPv4 IP via Tor; output shows which SOCKS port was picked

Note

Pass --socks-port to disable auto-detect.

Step 6: Force the Tor Browser bundle SOCKS port (9150), one random IPv4 source

ip-fetch tor --ipv4 --socks-port 9150

Expected Output: IPv4 via Tor Browser bundle

Step 7: Force a Kodachi multi-instance pool port (10000) and query ALL IPv4 sources

ip-fetch tor --ipv4 all --socks-port 10000

Expected Output: All IPv4 sources via Kodachi instance #0

Step 8: Query only the Tor-safe IPv4 sources

ip-fetch tor --ipv4 all --torsafe

Expected Output: Results from the 14 verified Tor-safe URLs instead of all 19

Note

Use this when some sources block or rate-limit Tor exit nodes and produce false failures.

Scenario 8: DNS Resolution Testing

DNS-based IP resolution and testing

Step 1: Test DNS-based IPv4 resolution using ONE random DNS query

ip-fetch dns --ipv4

Expected Output: IPv4 address from DNS query

Step 2: Test DNS-based IPv6 resolution using ONE random DNS query

ip-fetch dns --ipv6

Expected Output: IPv6 address from DNS query

Step 3: Test specific DNS query by index

ip-fetch dns --ipv4 --query-index 0

Expected Output: IPv4 from specific DNS query

Step 4: Test ALL available IPv6 DNS queries with JSON output

ip-fetch dns --ipv6 --query-index all --json

Expected Output: JSON array with all IPv6 DNS results

Scenario 9: Comprehensive Testing Suite

Complete test suites for all functionality

Step 1: Complete test suite results

ip-fetch test-all

Expected Output: Full functionality test report

Step 2: Complete test suite including Tor tests

ip-fetch test-all --include-tor

Expected Output: Comprehensive test results with Tor

Step 3: Complete test suite including Tor tests, forced to Kodachi pool port 10000 (skip auto-detect)

ip-fetch test-all --include-tor --socks-port 10000 --json

Expected Output: JSON formatted test results with the specified Tor SOCKS port

Step 4: JSON formatted complete test results

ip-fetch test-all --json

Expected Output: Structured test suite results

Scenario 10: Random Source Testing

Test random IP sources for reliability

Step 1: Test ONE random IPv4 plain text source

ip-fetch random --type plain --ipv4

Expected Output: Random IPv4 source test result

Step 2: Test ONE random IPv4 JSON source with JSON output

ip-fetch random --type json --ipv4 --json

Expected Output: Random IPv4 JSON source test result

Step 3: Test ONE random DNS IPv4 query

ip-fetch random --type dns --ipv4

Expected Output: Random DNS IPv4 query result

Step 4: Test ONE random DNS IPv6 query with JSON output

ip-fetch random --type dns --ipv6 --json

Expected Output: Random DNS IPv6 query result in JSON

Scenario 11: Geolocation API Testing

Test geolocation APIs with various IPs

Step 1: Test geo APIs with current IP

ip-fetch geo

Expected Output: Geolocation test results for your IP

Step 2: Test geo APIs with specific IP

ip-fetch geo --ip 208.67.222.222

Expected Output: Geolocation test results for 208.67.222.222

Step 3: Compare every geo API side by side as indented JSON

ip-fetch geo --json-pretty

Expected Output: One indented JSON block per geolocation API that answered

Note

geo always prints each API's raw response, so there is no separate verbose mode.

Step 4: Geo data for IP in JSON

ip-fetch geo --ip 1.1.1.1 --json

Expected Output: JSON geolocation data for 1.1.1.1

Scenario 12: Plain Text IP Retrieval

Get IP addresses in plain text format

Step 1: Get IPv4 plain text

ip-fetch plain-ip --ipv4

Expected Output: Your IPv4 address as plain text

Step 2: Get IPv6 plain text

ip-fetch plain-ip --ipv6

Expected Output: Your IPv6 address as plain text

Step 3: Use specific server by index

ip-fetch plain-ip --ipv4 --server-index 5

Expected Output: IPv4 from server index 5

Scenario 13: Bulk Operations

Look several IPs up in one round trip. Bulk mode turns on automatically for more than one IP. Every bulk lookup is authentication gated: run 'online-auth authenticate' first or the command fails with 'Authentication required'.

Step 1: Efficient bulk lookup of multiple IPs

ip-fetch --bulk 1.1.1.1 9.9.9.9 208.67.222.222

Expected Output: Bulk results for all IPs

Note

Requires an authenticated session. Run 'online-auth authenticate' first.

Step 2: Bulk lookup with JSON output

ip-fetch --bulk 1.1.1.1 9.9.9.9 --json

Expected Output: JSON array with all IP data

Step 3: Disable bulk mode for individual lookups

ip-fetch --nobulk 1.1.1.1 9.9.9.9

Expected Output: Individual lookup results

Step 4: Bulk IPv4-only lookups

ip-fetch --bulk --ipv4 1.1.1.1 9.9.9.9

Expected Output: Bulk IPv4 results

Step 5: Bulk lookup without saving to history

ip-fetch --bulk --nohistory 1.1.1.1 9.9.9.9 208.67.222.222

Expected Output: Bulk results (not saved)

Scenario 14: Cache Management

Inspect and manage the IP cache, and control the cache on a single lookup with --no-cache, --cache-only or --refresh-cache.

Step 1: Bypass the cache and force a fresh lookup of your own IP

ip-fetch --no-cache

Expected Output: Live IP data fetched from the network, cache untouched

Note

Mutually exclusive with --cache-only.

Step 2: Answer from the cache only, never touch the network

ip-fetch --cache-only 208.67.222.222

Expected Output: Cached data for 208.67.222.222, or an error if it is not cached

Note

Useful offline. Fails rather than falling back to the network. Mutually exclusive with --no-cache.

Step 3: Fetch fresh data and overwrite the cached entry even if it is still valid

ip-fetch --refresh-cache

Expected Output: Fresh IP data, cache entry rewritten

Step 4: Show cache statistics and status

ip-fetch cache status

Expected Output: Cache size, entry count and configured TTL

Step 5: List all cached IP addresses

ip-fetch cache list

Expected Output: Every IP address currently held in the cache

Step 6: Clear the entire cache

ip-fetch cache clear

Expected Output: Confirmation that all cached entries were removed

Note

Pass an IP to clear only that entry, e.g. 'ip-fetch cache clear 208.67.222.222'

Step 7: Clear a specific IP from the cache

ip-fetch cache clear 208.67.222.222

Expected Output: Confirmation that 208.67.222.222 was removed from the cache

Step 8: Set the default cache TTL

ip-fetch cache set-ttl 24h

Expected Output: Confirmation that the cache TTL was updated

Note

Accepts duration strings such as '24h', '7d' or '1w'

Scenario 15: Custom Server Options

Use custom servers for IP lookup

Step 1: Use custom server for IP lookup

ip-fetch --server https://api.ipify.org

Expected Output: IP from custom server

Step 2: Custom server with JSON output

ip-fetch --server https://api.ipify.org --json

Expected Output: JSON from custom server

Step 3: Custom IPv4 server

ip-fetch --server https://ipv4.icanhazip.com --ipv4

Expected Output: IPv4 from custom server

Step 4: Custom IPv6 server

ip-fetch --server https://ipv6.icanhazip.com --ipv6

Expected Output: IPv6 from custom server

Scenario 16: Output Formatting Options

The cli-core output flags below work on every ip-fetch command, not just the default lookup.

Step 1: Indented JSON for one IP, readable in a terminal

ip-fetch 208.67.222.222 --json-pretty

Expected Output: Multi-line, indented JSON object for 208.67.222.222

Step 2: Colorized, jq-style JSON for reading at a glance

ip-fetch --json-human

Expected Output: Syntax-highlighted JSON of your own IP data

Step 3: Strip ANSI colors, for redirecting into a file or a pipe

ip-fetch --no-color

Expected Output: Plain, uncolored text output

Scenario 17: No History Operations

--nohistory belongs to the default lookup (the 'fetch' path) and only suppresses history there. It is NOT a global flag: writing it alongside a subcommand such as 'tor', 'dns' or 'geo' does not suppress anything, because those subcommands never read it. Every form below is a plain lookup, which is the only place the flag has an effect.

Step 1: Look up your own IP without writing it to the history file

ip-fetch --nohistory

Expected Output: Your current IP with geolocation data, nothing appended to history

Step 2: Look up one specific IP without recording it

ip-fetch --nohistory 208.67.222.222

Expected Output: Geolocation data for 208.67.222.222, nothing appended to history

Step 3: Get your IPv6 as JSON without recording it

ip-fetch --nohistory --ipv6 --json

Expected Output: JSON object with your IPv6 data, nothing appended to history

Step 4: Bulk lookup of several IPs without recording any of them

ip-fetch --bulk --nohistory 1.1.1.1 9.9.9.9 208.67.222.222

Expected Output: Bulk results for all three IPs, nothing appended to history

Note

Bulk mode is authentication gated. Run 'online-auth authenticate' first.

Environment Variables

Variable	Description	Default	Values
`NO_COLOR`	Disable all colored output when set	unset	1\|true\|yes (any value disables color)

Exit Codes

Code	Description
0	Success
1	General error
2	Invalid arguments
3	Permission denied
4	Network error
5	File not found