Process Operations

The super CLI tool allows you to interact with the daemon locally or remotely. It uses the HTTP API under the hood.

This page covers day-to-day process operations. Full flags, batch forms, and every subcommand: CLI Reference.

Basic Commands

List Processes

View the status of all managed programs.

$ super list

ID         Name      Group     Status   PID    CPU   Mem
--------   -------   -------   ------   ----   ---   ---
8f1a...    api-srv   backend   Running  4021   2%    45MB

Start / Stop / Restart

You can target a program by Name or ID.

# Start
super start api-srv

# Stop (sends SIGTERM)
super stop api-srv

# Restart (Stop -> Start)
super restart api-srv

Group Operations

If you assign a group to your programs (stack file, API, or CLI), you can control multiple processes at once using the @ prefix.

Config: (example: conf/conf.d/api-group.json)

{
  "services": [
    { "name": "api-1", "command": "/usr/bin/api", "group": "backend" },
    { "name": "api-2", "command": "/usr/bin/api", "group": "backend" }
  ]
}

CLI:

# Restart all services in the 'backend' group
super restart @backend

Also supported: super start all and super stop all.

Group operations are order-aware: starts run dependencies first, stops run dependents first, and a group restart is a two-phase bounce (everything stops, then everything starts in dependency order) — see Ordered group operations.

Multi-process programs (`numprocs`)

One program definition can start N OS processes — useful for queue workers and similar workloads. This is not a rolling release of two versions of the same service, and it is not Node.js cluster mode (shared listen port / in-process load balancing).

super add --name worker --numprocs 4 /usr/local/bin/worker

Or in a stack file:

[[services]]
name = "worker"
command = "/usr/local/bin/worker"
numprocs = 4
# optional: process_name = "worker-{num}"   # default is {name}-{num}

Each instance gets SUPER_PROCESS_NUM (0-based) and SUPER_PROCESS_TOTAL — see Environment Variables. Lifecycle commands (start / stop / restart) target the program and apply to all of its processes. Worked example: Django tutorial — scale Celery workers.

Sending Signals

Sometimes you need to send a specific POSIX signal (e.g., to reload configuration without restarting).

# Send SIGHUP (often used for config reload)
super signal api-srv --sig hup

# Send SIGUSR1
super signal api-srv --sig usr1

Supported signals: hup, int, term, kill, quit, usr1, usr2.

Wait Strategy

By default, CLI commands are async. You can use --wait to block until the operation is verified.

# Wait up to 10 seconds for the process to actually stop
super stop api-srv --wait --timeout 10

State Across Daemon Restarts

Super persists your intent, not a snapshot of which processes were running:

super stop — the program is held stopped: it stays down across daemon restarts, and a cron schedule on it is held as well. The hold is flushed to disk immediately.
super start — clears the hold and persists autostart = true: the program starts now, and again at every daemon (re)start.
On daemon boot, every program with autostart = true (except cron programs) starts automatically; autostart = false programs do not.

Consequences worth knowing:

A cron program that was manually stopped never comes back until an explicit super start — not when its schedule fires, and not when the daemon restarts.
Programs started implicitly as dependencies are not independently remembered. They return transitively: on boot, autostart = true entry points start and pull their dependencies. If an entire chain has no autostart = true entry point, that group stays stopped after a daemon restart — explicitly start any one of them and the chain recovers.
Super deliberately does not resurrect the exact previous process set (pm2-style). The desired state is the autostart flag plus the held-stopped set — both persisted and flushed immediately on every start/stop operation.