Features

• Auto-Login Daemon: Runs in the background (LaunchAgent on macOS, systemd on Linux). Automatically handles captive portals so you never see a login page.
• Menu Bar Plugin: Generate a macOS (SwiftBar) or Linux (Argos) plugin to view status, switch networks, and see data usage straight from the menu bar!
• Captive Portal Logout: Log out your current session so you can connect your phone or iPad to the campus WiFi without hitting the device limit.
• Smart WiFi Scanner: Scan nearby access points and get recommendations on the strongest network to connect to.
• Data Export: Export your historical data usage to a CSV file for Excel/Numbers.
• Multi-Network Support: Seamlessly switch between multiple campus WiFi networks (e.g. T-VIT, M-VIT) with the same credentials.
• Fast Status Dashboard: Real-time stats on your WiFi signal, SNR, channel, data usage, and latency.
• Live Ping Monitor: Trace packet loss and latency spikes in real-time.
• Speed Test: Built-in CLI speed test (using Cloudflare CDN) without requiring external packages.
• Data Usage & History: View daily download/upload totals and a 7-day historical sparkline graph directly from network interface counters.
• Data Limits: Get desktop notifications when you exceed a daily data limit.
• Cross-Platform: Zero external dependencies. Uses native system tools (networksetup, ioreg, system_profiler on macOS; nmcli, ip on Linux).

Installation

The easiest way to install NetPulse is globally via NPM:

npm install -g netpulse-wifi

(This allows you to run the netpulse command from anywhere in your terminal.)

Manual Installation (No Node/NPM required): If you don't have Node installed, you can simply clone and link the bash script:

git clone https://github.com/ryanfer123/NetPulse.git
cd NetPulse
chmod +x netpulse.sh
mkdir -p ~/.local/bin
ln -sf $(pwd)/netpulse.sh ~/.local/bin/netpulse

Setup

Save your WiFi credentials securely. On macOS, this uses the native Keychain. On Linux, it saves to a restricted file (~/.netpulse-credentials with 600 permissions).

netpulse setup

Usage

Run netpulse to open the interactive menu, or use direct commands:

netpulse                # Open interactive menu
netpulse setup          # Store credentials & target networks
netpulse login          # One-shot portal login
netpulse logout         # Disconnect from captive portal
netpulse status         # Print detailed network status
netpulse scan           # Smart WiFi Scanner
netpulse speedtest      # Run a quick ping/download/upload test
netpulse ping           # Live connection monitor
netpulse data           # View data usage stats & history
netpulse export         # Export data usage to CSV
netpulse dashboard      # Open live-updating network monitor
netpulse install        # Install the auto-login background daemon
netpulse uninstall      # Remove the background daemon
netpulse logs           # View logs from the background daemon
netpulse menubar        # Print macOS/Linux menubar plugin code
netpulse faq            # Troubleshooting & common questions

FAQ

Q: I connect to different networks across campus.
A: During setup, enter all network names separated by commas: T-VIT,M-VIT. NetPulse will auto-login on any of them.

Q: Where are my credentials stored?
A: On macOS, they are stored securely in the native Keychain (encrypted). On Linux, they are stored in ~/.netpulse-credentials with chmod 600 (only your user can read it).

Q: Login shows "Failed" or "HTTP 000".
A: This usually means one of:

• You're not on the campus WiFi (e.g. mobile hotspot).
• The portal server 10.10.0.1 is unreachable.
• Your credentials are wrong.
• The campus network is genuinely down.

Q: It says "Offline" but I have internet.
A: NetPulse checks Google, Apple, and Cloudflare to detect internet. Some networks or hotspots may block these. Try running netpulse status for a detailed check.

Q: What is the daily data limit?
A: During setup, you can set a limit in MB (e.g. 500). The daemon will send a desktop notification when you exceed it. Leave blank during setup to disable.