Scientific Surfing

A CLI for surfing the internet scientifically, written in Go.

Features

• Clash RSS Subscription Support: Download and transform clash rss subscriptions
• Hook System: Customizable scripts for extending functionality
• Core Configuration Management: Import, export, and manage core configurations
• Binary Management: Automatic updates for core (mihomo) components
• Service Management: Install/start/stop/reload mihomo as a system service on Linux (systemd), macOS (launchd), and Windows (native Service Control Manager)

Installation

1. Clone and build

git clone ssh://git@gitea.epss.net.cn:2223/klesh/ss.git
cd ss
go build -o ss ./cmd/ss

This produces a single ss (or ss.exe on Windows) binary with no runtime dependencies — templates and hook scripts are embedded in the binary.

2. Add the binary to your system PATH

Quick Start

Subscription Management

# add a subscription
ss subscription add <name> <clash-rss-subscription-url>

# refresh a subscription (with optional backup)
ss subscription refresh <name> [--backup]

# delete a subscription
ss subscription rm <name>

# rename a subscription
ss subscription rename <name> <new-name>

# update subscription URL
ss subscription set-url <name> <new-url>

# show the URL for a subscription
ss subscription get-url <name>

# activate a subscription
ss subscription activate <name>

# list all subscriptions
ss subscription list

# show storage information
ss subscription storage

Hook Management

# initialize hooks directory with template scripts
ss hook init

# show hooks directory location and list all scripts
ss hook list

# edit a hook script with system editor
ss hook edit <script-name>

# remove a hook script
ss hook rm <script-name>

Core Configuration Management

# import configuration from file
ss config import <file-path> [--config-file <config.yaml>]

# export configuration to file
ss config export <file-path> [--config-file <config.yaml>]

# edit configuration with system editor
ss config edit [--config-file <config.yaml>]

# reset configuration to default values
ss config reset [--config-file <config.yaml>]

# show current configuration
ss config show [--config-file <config.yaml>]

# apply subscription to generate final config (with advanced options)
ss config apply \
	[--config-file <config.yaml>] \
	[--output-file <output.yaml>] \
	[--subscription <subscription-name>]

Options (available on every ss config subcommand):

• --config-file <config.yaml>: Use a custom config file instead of the default.
• --output-file <output.yaml>: Specify the output path for the generated config file.
• --subscription <subscription-name>: Use a specific subscription (not just the active one) for config generation.

Core Management

# update mihomo core binary
ss core update [--version <version>] [--force]

Service Management

ss service install [--name <name>] [--description <description>]
ss service uninstall [--name <name>]
ss service start [--name <name>]
ss service stop [--name <name>]
ss service restart [--name <name>]
ss service reload [--name <name>]   # reload config via mihomo's API, no restart
ss service status [--name <name>]

install/uninstall/start/stop/restart need root/admin privileges:

• Linux / macOS: just run the command directly — ss re-execs itself under sudo automatically, prompting for your password if needed.
• Windows: run from an elevated/Administrator shell — ss.exe service install.

Development

go build ./...
go vet ./...
go test ./...

License

MIT License - see LICENSE file for details.