Skip to main content

SSR management client with shell interface

Project description


Build Status Code Coverage Known Vulnerabilities Maintainability

SSR management client on Linux with command line interface


  • Command line interface, which is friendly for headless environment
  • All-in-one management for SSR application, configuration and subscription
  • pacman-style commands, which is short and easy for use
  • Support subscription update, configuration share URL and more useful function


  • Python >= 3.6
  • git for SSR installation
  • lsof to check local port

Get Started

First install this package from PyPI:

pip3 install ssrcli

Then use ssrcli to install SSR:

ssrcli --install

Following XDG Base Directory Specification, SSR will be downloaded to ~/.local/share/shadowsocksr

Then add your SSR configuration using ssrcli and use it. For example, if you have a SSR subscription url, do:

# Add a subscription
ssrcli -Saj '{"name": "<the name>", "url": "<the url>"}'
# Update all subscription
ssrcli -Sua
# List all got configuration
ssrcli -Cla
# Choose one. With its id, use the configuration
ssrcli -Csc '<the id>'
# Start SSR
ssrcli -O
# Or restart SSR, which would ensure SSR is on
ssrcli -R

For more information, refer to the below content of this readme or ssrcli -h


We recommend not to use a custom ssrcli config file for the default config is enough and good

ssrcli will go through XDG_CONFIG_DIRS to search for ssrcli/ssrcli-config.json to load. Following XDG Standard, you should put your config file as ~/.config/ssrcli/ssrcli-config.json. This is a JSON file which can optionally contains the below options. Both upper case and lower case is OK.

Name Default Value Description
DB_PATH ~/.local/share/ssrcli/db.sqlite3 Path to the database file containing all data
SSR_APP_PATH ~/.local/share/shadowsocksr Path to the folder containing SSR
SSR_CONF_PATH ~/.config/ssrcli/ssr-config.json Path to the SSR config file
SSR_LOCAL_PORT 1080 Local port used by SSR
SSR_CONF_EXTRA_FIELDS See below Extra JSON content added to SSR config file
UPDATE_TIMEOUT 10 Timeout when updating (Unit: s)
UPDATE_RETRY 5 Retry times when update failed

The default value of SSR_CONF_EXTRA_FIELDS is:

  "local_address": "",
  "local_port": "$SSR_LOCAL_PORT",
  "timeout": 300

In this JSON $SSR_LOCAL_PORT will be replaced by the same-name config argument SSR_LOCAL_PORT


Show help and version:

More options could be found here

ssrcli -h
ssrcli -V

Below we shorten configuration as conf and subscription as sub

Install/remove SSR with --install and --remove

Start/stop/restart SSR with -O(on), -F(off) and -R(restart)

Test SSR integrity with --test

Manage conf with -C and sub with -S

Both conf and sub support -l(list), -n(add), -d(delete)

Conf additionally support -s(use), sub additionally support -u(update)

You can pass multi -c <id> to choose multi objects to be processed

You can pass -j <json> to provide information. The option value should be a valid JSON with all required fields.

You can add -a to perform action on all objects, and usually without -a, the default objects of a action is all objects except for -d(delete). Without given objects -d(delete) will raise a exception.

As for update, when updating a sub, all old conf belonging to the sub will be removed

You can pass -r(current) to ssrcli when using -l(list) to show currently used SSR conf

For more information, type ssrcli -h to read. The below is some examples:

# Show help
ssrcli -h
# Add a conf from JSON
ssrcli -Caj '{
  "server": "::1",
  "server_port": 30000,
  "protocol": "origin",
  "method": "none",
  "obfs": "plain",
  "password": "test",
  "obfs_param": "",
  "protocol_param": "",
  "remarks": "test",
  "group": "test"
# Add a sub from JSON
ssrcli -Caj '{"name": "test", "url": "https://test.test"}'
# List all conf with currently used conf
ssrcli -Clar
# Update all sub with proxy
ssrcli -Suap '{"socks5": ""}'


First install the test requirements in requirements.txt

Then Move to tests folder and start the tests with script:

cd tests  # IMPORTANT, as many tests would rely on the relative path

In tests, port 1080, 8001, 8002 will be used. Make sure them bindable or change the ports in and

Internet is required to download SSR. Or you can use another pytest command in with downloading SSR to tests/shadowsocksr previously.

For the use of Popen, after a failed test port 1080 may be bind by left SSR. Just kill it.



Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ssrcli-3.1.2.tar.gz (13.6 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page