npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2025 – Pkg Stats / Ryan Hefner

the-shepherd

v0.3.29

Published

Control a herd of wild processes.

Downloads

165

Readme

The Shepherd

Manage groups of processes.

Install: npm install the-shepherd

Usage: shep <command> [options]

Global options:

--quiet or -q
--verbose or -v
--force or -f
--path <base-path> - Use `<base-path>/.shep` instead of searching.

Commands:

| Command | | Example | | ------- | ----------- | ------- | | init | Create a .shep folder here. | shep init | | up | Ensure the daemon is running. | shep up | | down | Stop the daemon. | shep down | | add | Add a process group. | shep add echo --exec "node echo.js" --port 8081 | | remove | Remove a process group. | shep remove echo | | replace | Replace a group with new settings. | shep replace echo --exec "node foo.js" | | start | Start processes (autostarts the daemon). | shep start echo-1 | | stop | Stop processes. | shep stop echo | | restart | Restart processes. | shep restart echo-1 | | disable | Disable an instance or group. | shep disable --group foo | | enable | Enable an instance or group. | shep enable --instance foo-1 | | status | Report the current status. | shep status --verbose | | config | Manage the config file. | shep config --list | | health | Manage a health-check on a group. | shep health --group foo --status 200 --interval 3 | | log | Manage the log output. | shep log --tail | | nginx | Configure the nginx integration. | shep nginx --file '%/nginx' | | scale | Scale a process group to a new size. | shep scale echo --count 2 |

Files

shep reads and writes state from a .shep directory. You can specify this directory using SHEPHERD_PATH in the environment, or using the --path argument to any command. If unspecified, shep will search for a .shep directory using the same rule Git uses to search for a .git folder: Start in the working directory, and check each parent until you find one. shep init is the only command that skips this search.

Files inside the .shep directory:

config - A list of commands to execute at daemon startup.
defaults - Will be copied to config by 'shep init'. This file should be in source control.
socket - A unix socket used by the daemon to listen for commands.
pid - Contains the pid of any currently running daemon.
log - The (default) location to log output from all managed processes.
nginx - The (default) location to keep an up-to-date set of nginx upstreams.

When reading the config file, any occurrence of "%" will be replaced with the full path to the .shep directory.

> shep init

init ensures that a .shep folder exists in the working directory.

If a .shep folder already exists, and has a defaults file, but no config file, it will copy defaults to config.

> shep up

up ensures that a daemon has been spawned to manage the current .shep directory.

--verbose - Launch the daemon with verbose logging.

If .shep/config exists, each line will be read in as if it had been given as a command to shep, eg:

log --file "%/log"	
add echo --cd test/echo --exec "node echo_server.js" --count 4 --port 9001
nginx --disable
start

When the daemon starts, it will create .shep/socket and .shep/pid, and possibly others.

Where indicated below, many commands cause the currently running configuration to be written to the config file (overwriting that file).

> shep down

down stops the current daemon, and all processes it was managing.

> shep add

add will add a group, it accepts a standard set of options for specifying a group:

--group <name> - Required. Process ids will be like <group-name>-1, etc.
--cd <path> - The working directory for new processes. Optional. Default "."
--exec <command> - The shell command to launch the process. Required.
--count <n> - Optional. Default 1
--port <port> - The starting port. If n > 0 then port will be incremented. Optional.
--grace <ms> - How long to allow the process to startup. Optional. Default 9000

If --port is specified, each new process is given PORT in it's environment. The process is "started" once it is listening on it's given PORT. Failure to listen on PORT within the --grace timeout will cause that process to become "failed" and not restarted.

If --port is not specified, then the process is "started" if it stays up for it's full --grace period. Be careful if you use long --grace times, with no --port, and high --count; this combination will lead to a slow start for that group.

This command causes config to be re-written.

> shep remove

remove will (stop and) remove a current process group.

--group <name>

This command causes config to be re-written.

> shep replace

replace will first remove then re-add a group, using the new options. Uses the same options as add.

All the processes in the group will be stopped (during the remove), and started (after the add).

This command causes config to be re-written.

> shep scale

scale will change just the --count option for a group, and will only effect current processes if the new <n> is smaller.

--group <name>
--count <n>

If the --group is started, then processes will be started or stopped immediately.

This command causes config to be re-written. The new config will not contain a --scale command directly, but instead this scaling will be reflected in the corresponding add --group command.

> shep start

start can start specified groups, or processes.

--group <name>
--instance <instance-id>

If no options are given, everything will be started.

If the daemon is not running, up will be called automatically.

> shep stop

stop can stop specified group, or processes.

--group <name>
--instance <instance-id>

If no options are given, everything will be stopped.

> shep restart

restart can start specified groups, or processes.

--group <name>
--instance <instance-id>

If no options are given, everything will be started.

Processes will be restarted serially within a group, but multiple groups will restart in parallel.

> shep log

log controls the combined output of all managed processes.

--file <path> - eg, the default is "%/log".
--disable - Don't write any log file to disk.
--tail - Stream the log output. Works even when log file is disabled.

When using --tail, it will keep the process open until you hit Ctrl-C, and behaves like tail -f api.log. The difference is that it streams from inside the daemon, through the socket file, and to the shep client (no file needed).

> shep nginx

nginx controls the built-in nginx integration.

--file <path> - Where to keep an up-to-date set of upstreams.
--keepalive <n> - How many connections should nginx keep-alive to each pool.
--reload <command> - How to notify nginx to reload an updated config.
--disable - Don't write any nginx configuration (default).

The generated upstreams file might look like this:

upstream group_name {
	server 127.0.0.1:9001 weight=0 down; # disabled
	server 127.0.0.1:9002 weight=1; # started
	server 127.0.0.1:9003 weight=1 down; # enabled, but not started
	
	keepalive 32;
}

This file is re-generated, and nginx is notified to (gently) check for configuration changes as process statuses change.