🛡️ ipsafe

A simple CLI tool that validates network connectivity before executing commands

🚀 What is ipsafe?

ipsafe is a command-line tool that checks a network condition before executing any command. If the condition passes, it executes the command. If the condition fails, it blocks execution.

Default behavior: Fetches https://www.google.com and checks if the HTTP status code is 2xx.

📦 Installation

npm install -g ipsafe

🎯 Usage

Simply prefix any command with ipsafe:

# Check connectivity before npm install
ipsafe "npm install"

# Verify connection before git operations  
ipsafe "git push origin main"

# Safe API calls
ipsafe "curl https://api.example.com/data"

# Configuration commands
ipsafe --init              # Setup global config
ipsafe --config            # Show current config
ipsafe --help              # Show help

Output Example

$ ipsafe "npm install"
🔍 Checking network connectivity to https://www.google.com...
✅ Network connectivity verified
🚀 Executing: npm install

# ... npm install output (streamed in real-time)

✨ Command completed successfully

Visual Features:

• 🎨 Colorful output - Green for success, red for errors, cyan for info
• 📺 Real-time streaming - See command output as it happens
• 🎯 Clear status indicators - Emojis and colors make status obvious

⚙️ Configuration

Quick Setup

Create a global configuration that works everywhere:

# Create global config with defaults
ipsafe --init

# Check current configuration
ipsafe --config

# See where config file is located
ipsafe --config-path

Configuration Locations

ipsafe follows standard configuration practices with this search order:

Priority 1 - Project Config (highest priority)

• ./ipsafe.config.json (current directory)

Priority 2 - Global User Config

• macOS/Linux: ~/.config/ipsafe/config.json
• Windows: %APPDATA%/ipsafe/config.json

Priority 3 - Simple Dotfile (fallback)

• ~/.ipsafe.json

Priority 4 - Built-in Defaults

Configuration Format

{
  "testUrl": "https://www.google.com",
  "timeout": 3000,
  "retries": 1,
  "method": "GET",
  "userAgent": "ipsafe/1.0.3",
  "checkContent": false,
  "searchText": null,
  "searchType": "contains",
  "headers": {},
  "commandTimeout": 0
}

Benefits of Global Config

✅ Works everywhere - No need to create config in each project
✅ Standard locations - Follows OS conventions (~/.config/)
✅ Easy setup - One command creates global config
✅ Flexible override - Project configs can override global settings
✅ Portable - Sync via dotfiles across machines

Configuration Options

Option	Default	Description
testUrl	https://www.google.com	URL to test connectivity against
timeout	3000	Request timeout in milliseconds
retries	1	Number of retry attempts
method	GET	HTTP method to use
userAgent	ipsafe/1.0.3	User-Agent header
checkContent	false	Enable content validation
searchText	null	Text/pattern to search for in response
searchType	contains	Search method: contains or regex
headers	{}	Custom HTTP headers
commandTimeout	0	Command execution timeout in ms (0 = no timeout)

🔧 How it Works

1. Condition Check: Makes HTTP request to configured URL
2. Status Validation: Verifies HTTP status code is 2xx (200-299)
3. Content Validation (optional): Searches for specific text/pattern in response
4. Command Execution: If all checks pass, executes the provided command with real-time output
5. Streaming Output: Shows command output as it happens (great for long-running commands)
6. Signal Handling: Supports Ctrl+C to interrupt long-running commands
7. Blocking: If any check fails, blocks command execution

📝 Examples

Basic Usage (Default Google Check)

# Uses default https://www.google.com check
ipsafe "npm install express"

Long-Running Commands

# Streaming output for long commands
ipsafe "ping -c 10 google.com"

# Works with any long-running command
ipsafe "npm run build"
ipsafe "docker build -t myapp ."

# Infinite commands (use Ctrl+C to stop)
ipsafe "ping google.com"
ipsafe "tail -f /var/log/system.log"

Interactive Commands

# CLI tools with prompts (using --print for non-interactive)
ipsafe 'claude --print "What is 2+2?"'

# Piped input works too
echo "Explain Docker" | ipsafe "claude --print"

# Commands that need full terminal access
ipsafe "vim myfile.txt"     # Opens vim with full TTY
ipsafe "htop"               # Interactive process monitor

Custom URL Check

{
  "testUrl": "https://api.github.com"
}

IP Location Service Example (IPLocate)

IPLocate (https://www.iplocate.io/) provides a free IP geolocation API that's perfect for personal daily usage. We thank IPLocate for offering this valuable service to the community!

To use IPLocate, you'll need to get a free API key from their website. They offer generous free quotas that should cover most personal usage needs.

{
  "testUrl": "https://iplocate.io/api/lookup?apikey=<your_api_key>",
  "method": "GET",
  "checkContent": true,
  "searchText": "ip",
  "searchType": "contains",
  "headers": {
    "Accept": "application/json"
  }
}

This configuration will:

1. Check connectivity by querying your current IP information
2. Validate that the response contains IP data
3. Only execute your command if the API responds correctly

Replace <your_api_key> with your actual API key from IPLocate.

Content Validation with Regex

{
  "testUrl": "https://httpbin.org/json",
  "checkContent": true,
  "searchText": "\"slideshow\".*\"title\"",
  "searchType": "regex"
}

Custom Headers and Authentication

{
  "testUrl": "https://api.private.com/health",
  "headers": {
    "Authorization": "Bearer your-api-key",
    "Accept": "application/json"
  },
  "checkContent": true,
  "searchText": "healthy"
}

✅ Success Conditions

The tool considers the condition successful when:

• HTTP status code is 2xx (200-299)
• Response is received within timeout period
• No network errors occur
• Content validation passes (if enabled)

❌ Failure Conditions

The tool considers the condition failed when:

• HTTP status code is not 2xx
• Request times out
• Network errors (DNS resolution, connection refused, etc.)
• Content validation fails (if enabled)
• All retry attempts are exhausted

🛠️ Development

git clone <repository-url>
cd ipsafe
npm install
npm test          # Run tests
npm run lint      # Run linter

📄 License

MIT © nocoo

💡 Why ipsafe?

Have you ever started a long-running command only to realize you're offline? ipsafe prevents this frustration by checking connectivity first.

Perfect for:

• 🏠 Remote work with unstable connections
• ✈️ Working while traveling
• 🔄 CI/CD pipelines requiring network validation
• 🛡️ Any script that depends on internet connectivity