{"id":15645314,"url":"https://github.com/ido50/svsh","last_synced_at":"2025-07-16T12:05:34.905Z","repository":{"id":28890153,"uuid":"32414823","full_name":"ido50/Svsh","owner":"ido50","description":"Process supervision shell for daemontools, perp, s6 and runit","archived":false,"fork":false,"pushed_at":"2023-11-16T15:22:51.000Z","size":746,"stargazers_count":56,"open_issues_count":0,"forks_count":2,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-30T11:55:56.204Z","etag":null,"topics":["bash","perl","process-supervision","runit","s6","supervision-suite","supervisor"],"latest_commit_sha":null,"homepage":"https://ido50.github.io/Svsh/","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ido50.png","metadata":{"files":{"readme":"README.md","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-17T19:19:42.000Z","updated_at":"2025-03-15T00:37:27.000Z","dependencies_parsed_at":"2023-11-16T16:37:39.375Z","dependency_job_id":"fe2a8035-0e0b-4d4a-a4a3-dc7de623cef8","html_url":"https://github.com/ido50/Svsh","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ido50/Svsh","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido50%2FSvsh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido50%2FSvsh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido50%2FSvsh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido50%2FSvsh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ido50","download_url":"https://codeload.github.com/ido50/Svsh/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ido50%2FSvsh/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265508195,"owners_count":23779089,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","perl","process-supervision","runit","s6","supervision-suite","supervisor"],"created_at":"2024-10-03T12:06:18.841Z","updated_at":"2025-07-16T12:05:34.258Z","avatar_url":"https://github.com/ido50.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NAME\n\nsvsh - Process supervision shell for daemontools/perp/s6/runit\n\n# SYNOPSIS\n\nsvsh \\[OPTIONS\\]\n\nOptions:\n\n    --basedir=BASEDIR (-d)   Service directory (on which supervisor was started).\n    --suite=SUITE     (-s)   Supervision suite managing the directory (perp, s6 or runit).\n    --bindir=BINDIR   (-b)   Directory where the supervisor is installed (e.g. /usr/sbin). Optional.\n    --collapse        (-c)   Collapse numbered services into one line.\n\nExample:\n\n    svsh --suite perp --basedir /etc/services\n    svsh --suite runit --basedir /var/services restart nginx\n\n# DESCRIPTION\n\n![screenshot](https://ido50.github.io/Svsh/screenshot.png)\n\n`svsh` is a command line shell for process supervision suites of the [daemontools](http://cr.yp.to/daemontools.html) family. Currently, it supports\ndaemontools, [perp](http://b0llix.net/perp/), [s6](http://www.skarnet.org/software/s6/index.html)\nand [runit](http://smarden.org/runit/). It provides a unified interface allowing easy inspection\nand manipulation of services (i.e. processes) managed by supported supervision suites.\n\n`svsh` does not require any configurations or changes to your suite's service directories;\njust point it at a base directory and you immediately get a usable shell, listing all\nservices and their statuses, and accepting commands to perform on them.\n\nThe shell provides a very simple syntax that is easy to remember, far simpler than the\nparticular syntax of the underlying supervision suite. Instead of having to execute\n`perpctl -b /services q nginx` to restart an `nginx` service running from `/services/nginx`,\njust execute `restart nginx`. Couldn't be simpler. Want to send a `HUP` signal to all\nservices whose names begin with `\"worker\"`? just execute `signal hup worker*`.\n\n`svsh` is inspired by [supervisord](http://www.supervisord.org/)'s `supervisorctl` shell. I've\nattempted to provide a similar syntax and feature set.\n\n# OPTIONS\n\n## -s, --suite\n\nThe supervision suite managing the base directory. Either `daemontools`, `perp`,\n`s6` or `runit`. If not provided, the `SVSH_SUITE` environment variable will\nbe checked. An error will be raised if no suite is defined.\n\n## -d, --basedir\n\nBase directory of services supervised by the supervision suite. If not provided,\nthe `SVSH_BASE` environment variable will be checked, and if not set, the default\nbase directory of the selected suite will be used. Check the documentation of\nthe specific suite class for its default directory. If no directory is found,\nan error will be raised.\n\n## -b, --bindir\n\nIf the supervision suite's tools are not in the environment `PATH` variable,\nyou can provide the directory where they are located (e.g. `/usr/local/bin`).\n\n## -c, --collapse\n\nCollapse multi-process services to one line in `status`. See [\"COLLAPSE\"](#collapse)\nfor more details. This can be changed from inside the shell too.\n\n# COMMANDS\n\nThe following commands are provided by `svsh`. Note that some suites do not\nsupport all commands.\n\n## status\n\nPrints a list of all services, their statuses (up, down, etc.), uptimes (or\ndowntimes) and process IDs. This command is automatically executed upon\ninitialization of the shell.\n\n## start service, ...\n\nStarts a list of one or more services, if they are not already up.\n\n        svsh\u003e start nginx haproxy\n\n## stop service, ...\n\nStops a list of one or more services. The services stopped will not be restarted.\n\n        svsh\u003e stop nginx haproxy\n\n## restart service, ...\n\nRestarts a list of one or more services. Generally, this means sending a QUIT signal\nto the services, which _should_ cause them to shutdown and be restarted by the\nsupervisor.\n\n        svsh\u003e restart nginx haproxy\n\n## signal sig service, ...\n\nSend a UNIX signal to a list of one or more services. The name of the signal can\nbe lowercase or uppercase, and may include the prefix `\"SIG\"`.\n\n        svsh\u003e signal term nginx\n        svsh\u003e signal SIGUSR1 haproxy\n\n## rescan\n\n_Alias: update_.\n\nCauses the supervision suite to rescan the base directory for new or removed services.\n\n## fg service\n\n\"Moves\" a service to the foreground, so that its output streams (at least standard output,\npossibly standard error) are printed on screen. In reality, it determines where the process'\nlog file is located, and tails it with `tail -f`. See [\"LOG INSPECTION\"](#log-inspection) for more details, as this\nis a complicated subject.\n\n        svsh\u003e fg nginx\n\n## terminate\n\n_Alias: shutdown_.\n\nTerminate the supervision suite. This will cause all services managed by the supervisor to\nterminate as well.\n\n## toggle option\n\nToggles a shell option on or off. Currently, only the `collapse` option is supported. The\n`status` command will be automatically called after toggling the option.\n\n        svsh\u003e toggle collapse\n\n## help \\[ command \\]\n\nPrints help information. Can also provide information about specific commands.\n\n        svsh\u003e help signal\n\n## quit\n\n_Alias: exit_.\n\nQuits the shell.\n\n# ADVANCED FEATURES AND IMPORTANT INFORMATION\n\n## LOG INSPECTION\n\nAll of the supported supervision suites do not enforce a logging scheme on managed\nservices. While all of them provide a logging tool (`daemontools` provides `multilog`,\n`perp` provides `tinylog` and `sissylog`; `s6` provides `s6-log`; `runit`\nprovides `svlogd`), none of them enforce their usage. It is actually not uncommon\namong users of these suites to use a logging tool provided by one suite for services\nmanaged by another one. This means it is hard for an external program such as `svsh`\nto determine where log files are stored, if at all.\n\nCurrently, `svsh` will attempt to find the log file of a service by checking the\npid of the associated log process, and if (and only if) that process is one of the\nsupported loggers (`multilog`, `tinylog`, `s6-log` or `svlogd`), it will try to find the\nfile descriptor used by that process under `/proc/\u003cpid\u003e/fd`. As long as your services\nare being logged by one of these tools, `svsh` _should_ be able to `tail` their log\nfiles  when the [fg](#fg-service) command is used. However, if the log file is being rotated\nwhile it is being tailed, behavior is currently undefined (will probably stop working until\nthe command is run again).\n\n## HISTORY\n\n`svsh` provides bash-like history so you can use your up arrow key to cycle back through\npast commands, or use `Ctrl+R` to search your history. The history file is saved under\nthe name `.svsh_history` under the home directory of the running user (`~/.svsh_history`).\n\nNote that history is saved only when the shell is properly terminated, such as with the\n[quit](https://metacpan.org/pod/quit) command. `Ctrl+C` will not trigger history saving.\n\nIt is highly recommended to install [Term::ReadLine::Gnu](https://metacpan.org/pod/Term%3A%3AReadLine%3A%3AGnu) for proper history support.\n\n## AUTOCOMPLETION\n\n`svsh` provides autocompletion for all its commands. Tap the tab key at any moment while\ntyping in commands and arguments, and `svsh` will attempt to autocomplete your current\nword, or display a list if multiple options are available. Again, [Term::ReadLine::Gnu](https://metacpan.org/pod/Term%3A%3AReadLine%3A%3AGnu)\nis recommended for better autocompletion.\n\n## WILDCARDS\n\n`svsh` makes it easy to manipulate multiple services at once. Wildcards are supported\nby the `start`, `stop`, `restart` and `signal` commands. If, for example, you have\nseveral services whose names start with \"worker\", you can stop them all by executing\n`stop worker*`. Wildcards are also supported at the beginning of the name, so\n`signal term *d` will send a `TERM` signal to all services whose names end with \"d\".\n\n        svsh\u003e status\n           process |     status | duration |   pid\n          worker-1 |         up |    9813s | 25984\n          worker-2 |         up |    9813s | 25976\n          worker-3 |         up |    4393s | 2990\n\n        svsh\u003e stop worker*\n\n        svsh\u003e status\n           process |     status | duration |   pid\n          worker-1 |       down |       2s |     -\n          worker-2 |       down |       2s |     -\n          worker-3 |       down |       2s |     -\n\n## COLLAPSE\n\nOften times you would like to run a certain service with X number of identical processes.\nNone of the supervision suites have any mechanism to allow this (none that I\nknow of at least), apart from creating identical copies of a service directory for every\nprocess needed. While `svsh` can't help you with that, it provides a nice feature for collapsing\nthese identical services in the output of the [\"status\"](#status) command to just one line. This can\nbe very useful with lots of multi-process services.\n\nCurrently, `svsh` determines multi-process services if their names are postfixed with a dash\nand a number. For example, if you have a service called `worker` that you need 3 processes\nof which to run, you can create `worker-1`, `worker-2` and `worker-3` service directories.\nIf the [collapse](#c-collapse) option is on, `svsh` will collapse all of these into\njust one line, under the name `status`.\n\n        svsh\u003e status\n           process |     status | duration |   pid\n          worker-1 |         up |    9813s | 25984\n          worker-2 |         up |    9813s | 25976\n          worker-3 |         up |    4393s | 2990\n\n        svsh\u003e toggle collapse\n           process |     status | duration |   pid\n            worker |       3 up |    9850s |     -\n\nThis feature combines well with the [\"WILDCARDS\"](#wildcards) feature.\n\nHopefully, future versions will find a more generic way of identifying multi-process services.\n\n# CONFIGURATION AND ENVIRONMENT\n\n`svsh` requires no configuration files or environment variables.\n\n# DEPENDENCIES\n\n`svsh` depends on the following modules:\n\n- [Moo](https://metacpan.org/pod/Moo)\n- [namespace::clean](https://metacpan.org/pod/namespace%3A%3Aclean)\n- [Proc::Killall](https://metacpan.org/pod/Proc%3A%3AKillall)\n- [Term::ShellUI](https://metacpan.org/pod/Term%3A%3AShellUI)\n\nFor proper history and autocompletion support, and generally a better\nworking shell, it is recommended to install [Term::ReadLine::Gnu](https://metacpan.org/pod/Term%3A%3AReadLine%3A%3AGnu).\n\n# BUGS AND LIMITATIONS\n\nPlease report any bugs or feature requests to\n[https://github.com/ido50/Svsh/issues](https://github.com/ido50/Svsh/issues).\n\n# AUTHOR\n\nIdo Perlmuter \u003cido@ido50.net\u003e\n\nThanks to the guys at the [supervision mailing list](http://skarnet.org/lists.html#supervision),\nespecially Colin Booth, for helping out with suggestions and information.\n\n# LICENSE AND COPYRIGHT\n\nCopyright (c) 2015-2023, Ido Perlmuter `ido@ido50.net`.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fido50%2Fsvsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fido50%2Fsvsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fido50%2Fsvsh/lists"}