CLI Reference

The super binary is the primary way to interact with the daemon. Commands are grouped by category below; run super --help for inline help.

Edition legend (same convention as Config reference — Edition legend):

Global Flags:

Endpoint selection (how super picks a daemon to talk to):

1. --server <URL> — highest priority; used for this command only.
2. ~/.super/cli.json server_url — persisted by super login <secret> [--url <URL>]; all subsequent commands follow it.
3. Auto-discovery (only when neither of the above applies, i.e. no --server and no ~/.super/cli.json): if $SUPER_ROOT/run/superd.sock (or ./run/superd.sock without SUPER_ROOT) exists and is a real socket file, the CLI uses unix:// there; otherwise it falls back to the default http://127.0.0.1:9002.

When the daemon listens on both TCP and a Unix socket, an unconfigured CLI therefore prefers the Unix socket automatically. To force TCP, pass --server http://host:port or run super login <secret> http://host:port to persist it. Auto-discovery only recognizes the conventional run/superd.sock path — a custom socket path or a non-default TCP port still needs an explicit --server (or a persisted login).

Starting superd (daemon binary)

superd is separate from the super CLI. It reads $SUPER_ROOT/conf/super.toml and listens for API/CLI traffic.

CLI overrides: --daemon / --foreground / --pidfile <PATH>. See Config reference and Installation — Start by hand. Program control (start / stop / shutdown) is unchanged either way.

Command index

Runtime & Monitoring

Lifecycle

Config & Stack

System & Daemon

Authentication

Runtime & Monitoring

list

List all managed programs and their status.

super list

info

Show detailed JSON/Table information about a specific program. When the program has a provenance label (see import — Provenance), the table includes a Source: line such as Source: import:supervisor or Source: stack:app.toml.

super info <name|id>

events

Show the persisted event history for a program — all lifecycle events are recorded (crashes, OOM kills, backoff retries, recoveries, exits, cron runs, system startup/shutdown), not just anomalies. Newest first. For storage, retention, and workflow guidance, see Event History.

super events <name|id>                    # all recorded events
super events <name|id> --limit 10         # last 10 events
super events <name|id> --type process_fatal   # only fatal events
super events <name|id> --exit-code 1      # only runs that exited with code 1
super events <name|id> --q "oom"          # free-text match on the message
super events <name|id> --from 1735689600 --to 1735776000   # time window (Unix seconds)
super events <name|id> --stats            # retention statistics instead of the list

Events are persisted by superd to a SQLite database (default data/events.db) — see Event History for storage, retention (events_keep_days), and the full event catalog. Every event carries a Unix timestamp (ts, seconds) and a millisecond-precision ts_ms; the table’s Time column renders it as local time. The signal column shows the terminating signal — 9 (SIGKILL) typically indicates a cgroup/kernel OOM kill under resource_limits. Backed by GET /api/v1/programs/{id}/events (plus GET /api/v1/events and GET /api/v1/events/stats).

logs

Read historical lines from disk and/or stream live output via WebSocket.

super logs <name|id>              # live stream (WebSocket)
super logs <name|id> --tail 200   # last 200 lines from disk
super logs <name|id> --tail 50 --follow   # tail then follow live

top

Real-time monitoring interface (like htop). Polls /api/v1/programs every second and renders a full-screen table; navigate with arrow keys, quit with q.

super top

Lifecycle

Target syntax

Control commands take a single target, written PM2-style as a union:

super <start|stop|restart|remove> <name|@group|id|all>

• <name> — exact program name (like PM2’s app_name).
• @<group> — every program in that group (like PM2’s namespace).
• <id> — program UUID; unambiguous prefixes are accepted.
• all — every managed program (PM2’s 'all').

Super has no json_conf target — declarative batches go through a stack file instead (super apply <file>, TOML default / JSON compatible). A target that matches several programs is rejected as ambiguous, with the candidates listed.

Batch targets are protected by three safety knobs (global flags, accepted on any control command):

Without --yes, a batch operation on more than one program prints the affected program list and asks [y/N]; answering anything other than y/yes aborts. Single-target operations never prompt.

add

Register a new program without a config file.

super add <COMMAND> [ARGS...] [FLAGS]

Flags:

update

Update configuration for an existing program.

super update <name|id> [FLAGS]

Flags:

Every flag is optional — omitted flags keep the program’s current value.

Full flow: Atomic OTA Updates. Artifact schema (same fields on API / stack / dashboard): Config reference — artifact. Scheduled-task and licensed (isolation plugin) flags behave as in super add; licensed flags warn if the plugin is not loaded.

start

Start a stopped process.

super start <name|@group|id|all> [--wait] [--wait-healthy] [--timeout N]

stop

Stop a running process.

super stop <name|@group|id|all> [--wait] [--timeout N] [--force]

restart

Restart a process.

super restart <name|@group|id|all> [--wait] [--wait-healthy] [--timeout N]

A multi-target restart (@group, all, or an ID list) is one coordinated two-phase cycle — all targets stop in reverse dependency order, Super waits for them to exit, then all targets start in dependency order (see Dependencies). A single-name restart keeps the simpler stop-then-start semantics on that one program.

signal

Send a specific POSIX signal.

super signal <name|@group|id|all> --sig <SIGNAL>

remove (alias rm)

Remove a program configuration. It must be stopped first (see Process Operations).

super remove <name|@group|id|all>

Config & Stack

reload

Reload system configuration from super.toml (logging, includes, event hooks), or send SIGHUP to a running program when a target is given.

super reload                              # reload super.toml (no program restart)
super reload --wait [--timeout N]         # reload and wait for affected programs to become Healthy
super reload <name|@group|id|all>         # SIGHUP to program(s) — e.g. nginx config reload

apply

Apply a declarative stack configuration. Stack files are TOML by default (.toml or no extension); legacy JSON (.json) stacks keep working.

super apply <FILE> [--dry-run] [--force-prune]

prune safety (irreversible): omitted / prune = false never deletes programs. If the file sets prune = true and any managed program is missing from the stack, the CLI prints a full apply diff first — keep/update, create, and every program that would be REMOVED (removal names are never truncated) — then requires you to type confirmed exactly to continue (y / yes / prune / global --yes are not accepted). The Dashboard Stack Editor uses the same diff + typed-confirmed gate. Automation must pass --force-prune after reviewing --dry-run. Prefer prune = false except for deliberate full-inventory GitOps applies. Stacks loaded via [include] on daemon start / super reload have no prompt — keep prune = false there and use super apply (or the Dashboard) for intentional prunes.

import

Convert a foreign process-manager config file into Super stack services: parse, map fields, print every warning, then apply through the same endpoint as super apply (create-or-update, never prunes). Supported formats: supervisor (INI with [program:*] sections, [include] files, [group:*], %(ENV_…)/%(here)s/%(program_name)s placeholders, numprocs/process_name templates).

super import supervisor /etc/supervisor/conf.d/app.conf --dry-run
super import supervisor /etc/supervisor/conf.d/app.conf --emit-toml app-stack.toml
# Name-collision handling — three ways to choose the mode:
super import supervisor /etc/supervisor/conf.d/app.conf --on-collision rename                       # flag (scripted)
super import supervisor /etc/supervisor/conf.d/app.conf --on-collision rename --collision-suffix staging   # fixed suffix -> web-staging
super import supervisor /etc/supervisor/conf.d/app.conf          # interactive prompt offers [y/r/o/N]
super import supervisor /etc/supervisor/conf.d/app.conf --yes --on-collision override                # scripted override (update in place)
super import supervisor /etc/supervisor/conf.d/app.conf [--yes] [--no-start] [--remap-logs]

Collision modes in detail. skip (default) is idempotent — rerunning the same import only fills in missing programs. rename picks {name}-{6-char hex} (e.g. web-c41f9a), guarantees the target is unique against the daemon and the rest of the batch, and prints the old→new mapping in both the plan and the final report — use it to run the imported copy next to the live one, verify, then retire the old program manually. override feeds the collided services through the stack API’s create-or-update semantics so the existing program’s config is replaced; interactive runs must type override (or answer o at the prompt) — it is never triggered by --yes alone.

Three ways to choose a mode: the --on-collision flag, the interactive prompt ([y] skip / [r] rename / [o] override / [N] abort — shown whenever collisions exist and no explicit mode was given), or --dry-run + re-run with the chosen flag. The preview always shows the exact outcome before anything is applied:

Import plan:
  + web-worker: /usr/bin/python3 manage.py celery_worker … [autostart, x3, @webapp]
  ~ web: exists -> will import as web-c41f9a (renamed)
  ~ db: already exists — skipped (not overwritten)

Safety: imports are always prune = false. Anything the converter could not map faithfully — stopsignal=QUIT, per-program log-rotation keys, [eventlistener:*], [fcgi-program:*] — is reported as a warning, never silently dropped. Full field mapping: Import tool.

Provenance: every program created or overridden by an import is stamped source = import:<format> (e.g. import:supervisor), visible via super info (line Source:) and the program detail API. Other write paths stamp similarly: super add → cli:add, super update → cli:update, super apply <file> → stack:<file>, and [include] stacks → include:<file>. This makes “where did this program come from?” answerable months later — for example when auditing what an import touched before retiring the old setup.

export

Export current state as a stack file. Defaults to TOML (the default stack format, round-trips cleanly with super apply / [include]); --format json keeps the legacy JSON shape for tooling that expects it.

super export [--format toml|json]

check

Validate super.toml without a running daemon: TOML syntax, bind/port, log/data paths, licensed-mode requirements, [include] stacks (TOML default, JSON compatible — same program-body checks as create), and rejected leftovers ([webhook], [[program]] tables that Super does not load). Include errors name the file and location: path:line:col: for TOML/JSON syntax, path: services[i] (name=…): field: for invalid services. Non-zero exit if any error is found. Use with super keyring when diagnosing license verification failures.

super check

System & Daemon

shutdown

Gracefully shut down the Super daemon and all child processes (works for foreground and --daemon instances).

super shutdown

doctor

One-shot diagnostics: config check (super check output), daemon health, license status, a Verifying keys summary line (same ids as super keyring), and local [server].daemon / pidfile hints (systemd conflict, stale pidfile). See Troubleshooting license verification.

super doctor

keyring

List Ed25519 verifying key ids (kid) compiled into this super binary — one row per key, so multiple rotation keys are all visible. Each kid uses the k_<8hex> convention (first four bytes of the public key as hex). Suggested when a license fails with an unknown signing key or to compare a local build with an official release. See Troubleshooting license verification.

super keyring
super keyring --json

Authentication

CLI auth talks to the same /api/v1/auth/* surface as the Dashboard. See Authentication.

OSS core auth (single admin secret)

When core auth is active (non-empty auth_secret in conf/super.toml), there is one admin Bearer secret — not an sk-… Access Token. That string is what you pass to login / --token (full detail: Can OSS use --token?):

SECRET='your-auth-secret'   # same as auth_secret in toml

super login "$SECRET"                          # saves ~/.super/cli.json
super login "$SECRET" --url http://127.0.0.1:9002
super list                                     # uses saved Bearer
super --token "$SECRET" list                   # one-shot: secret = Bearer
export SUPER_TOKEN="$SECRET"
super logout

Default loopback OSS without auth_secret stays open — no login is needed for super list. Non-loopback binds require auth_secret or the daemon refuses to start.

Multi-user Access Tokens 💎 (security plugin)

💎 Subscription. Token CRUD (super token …), roles, and day-to-day sk-… credentials require the licensed security plugin. super login / --token / SUPER_TOKEN still work for the bootstrap auth_secret and for Access Tokens once the plugin is loaded.

# Bootstrap only (no Access Tokens yet), or after all tokens were revoked:
super login <auth_secret>

# Day-to-day: use a generated token
super login sk-...
super token list
super token create ci-bot --role operator
super token revoke <id>

super --token sk-... list
export SUPER_TOKEN=sk-...

auth_secret stays usable by default under the plugin; Admins may explicitly disable it after creating an Admin Access Token. See Optional: disable auth_secret.

Alternative via curl (licensed token create):

# OSS core auth or licensed bootstrap:
curl -X POST http://127.0.0.1:9002/api/v1/auth/login \
    -H "Authorization: Bearer <admin-or-auth_secret>"

# 💎 security plugin — create an Access Token:
curl -X POST http://127.0.0.1:9002/api/v1/auth/tokens \
  -H "Authorization: Bearer <auth_secret>" \
  -H "Content-Type: application/json" \
  -d '{"name":"ci-bot","role":"operator"}'

curl -H "Authorization: Bearer sk-..." http://127.0.0.1:9002/api/v1/programs

Environment variables

superd and the super CLI read a small set of public environment variables (SUPER_ROOT, SUPER_TOKEN, SUPER_LICENSE, SUPER_LICENSE_STRICT) that override or configure daemon behavior without touching super.toml. See Environment Variables.