stopweb 0.1.4

A CLI tool to temporarily block websites by modifying the hosts file

StopWeb

Block websites permanently to help you stay focused. Works by editing your system's hosts file. You can also set a temporary duration if needed.

I built this because I kept getting distracted by social media and news sites when trying to work. Simple solution: block them until you decide to unblock.

What it does

• Blocks websites until you manually unblock them
• Works on Mac, Linux, and Windows
• Lets you see what's currently blocked
• Can unblock sites early if needed

Install

pip install stopweb

Basic usage

Block Facebook permanently:

sudo stopweb facebook.com

Block multiple sites at once:

sudo stopweb facebook.com youtube.com reddit.com

See what's blocked:

sudo stopweb --list

Unblock a site:

sudo stopweb --remove facebook.com

Remove all blocks:

sudo stopweb --clear

Temporarily block a site (expires automatically):

sudo stopweb -d 2h twitter.com      # 2 hours
sudo stopweb --duration 1d reddit.com  # 1 day

How it works

StopWeb edits your hosts file to redirect blocked sites to localhost (127.0.0.1).

On Mac/Linux that's /etc/hosts, on Windows it's C:\Windows\System32\drivers\etc\hosts.

It adds lines like:

127.0.0.1    facebook.com    # StopWeb:
# For temporary blocks, an expiry is recorded, e.g.
127.0.0.1    twitter.com     # StopWeb: expires=2025-01-01T12:00:00

Blocked sites stay blocked until you run the remove or clear command.

Notes

• Requires sudo/admin privileges (needs to edit system files)
• You might need to clear your browser cache after blocking/unblocking
• Creates a backup of your hosts file before making changes
• If something goes wrong, your original hosts file is saved as hosts.stopweb_backup
• Temporary blocks are removed automatically by running stopweb --cleanup

Notifications (manual edits)

StopWeb can alert you if someone edits your hosts file and removes or changes StopWeb entries by hand. It does not notify on additions.

• Default recipient: [e-mail]
• Snapshot is checked whenever you run a StopWeb command; if differences are found since the last run, an email is sent (or a file is saved in ~/.config/stopweb/outbox/ if SMTP isn't configured).
• To configure SMTP, edit ~/.config/stopweb/stopweb.json and set settings.notifications.smtp fields.

What triggers a notification:

• StopWeb line removed from hosts (e.g., someone deleted # StopWeb: lines)
• StopWeb line modified (e.g., IP or expires metadata changed)

What does not trigger a notification:

• Adding new StopWeb entries
• Normal StopWeb commands you run yourself (block/remove/clear/cleanup)

Audit and Watch

Single-run audit:

sudo stopweb --audit

Continuous watch (poll every 15 seconds):

sudo stopweb --watch --interval 15

Email Notifications Setup

Configure email notifications interactively:

sudo stopweb --config-email

This will prompt you for:

• Email recipients (comma-separated for multiple)
• SMTP settings (host, port, username, password)
• Option to send a test email

Example configuration for Gmail:

• SMTP host: smtp.gmail.com
• Port: 587
• Username: your Gmail address
• Password: Gmail app-specific password

Auto-Start Monitoring Service

Install background monitoring service that starts on boot:

sudo stopweb --install-service

This creates a system service (launchd on macOS, Task Scheduler on Windows, systemd on Linux) that:

• Runs stopweb --watch automatically on system startup
• Monitors hosts file every 30 seconds (configurable)
• Sends email notifications when manual changes detected

Uninstall the service:

sudo stopweb --uninstall-service

Manual Testing

Tip: for testing without touching your real hosts file, set an override:

export STOPWEB_HOSTS_PATH="/tmp/stopweb-hosts"

Then put some lines into that file and run stopweb --audit or --watch.

Why not just use browser extensions?

Browser extensions can be easily disabled when you're feeling weak. Editing the hosts file is more permanent - you'd have to remember the exact command to undo it.

Plus this works system-wide, not just in your browser.