Skip to content
Documentation Center
Internals & Reference
CLI Reference

CLI Reference

The super binary is the primary way to interact with the daemon.

Global Flags:

  • --server <URL>: Override the server URL (default: http://127.0.0.1:9002).

Starting superd (daemon binary)

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

ModeCommand / configWhen to use
Foreground (default)superd or superd --foregroundsystemd (Type=simple), Docker, debugging
Self-daemonize (Unix)superd --daemon or [server] daemon = trueBare metal without systemd; writes $SUPER_ROOT/run/superd.pid by default

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

Core Management

list

List all managed programs and their status.

super list

add

Register a new program without a config file.

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

Flags:

  • --name <NAME>: Custom name (defaults to binary name).
  • --autostart: Enable autostart (default: true).
  • --cwd <DIR>: Working directory.
  • --env <KEY=VAL>: Set environment variables (can be used multiple times).
  • --env-file <PATH>: Load environment variables from a file at spawn time.
  • --user <USER>: Run as specific user.
  • --numprocs <N>: Spawn N instances.

update

Update configuration for an existing program.

super update <TARGET> [FLAGS]

Flags:

  • --command, --args, --cwd, --user, --group: Execution settings.
  • --env <KEY=VAL>, --env-file <PATH>: Environment (--env-file "" clears).
  • --autostart, --retry-limit, --autorestart, --exitcodes, --startsecs, --stopsecs.
  • --no-health-check: Disable health check.
  • --artifact-url, --artifact-sha256: OTA download URL and expected SHA256 checksum.
  • --artifact-destination: Absolute path on the host filesystem where the binary lives (e.g. /usr/local/bin/my-app). Required on first OTA setup if the program has no existing artifact; omit on later updates if unchanged.
  • --artifact-extract: Extract archive before swap (default: false).
  • Full flow: Atomic OTA Updates.
  • Scheduled tasks: --cron (see Scheduled Tasks).
  • Licensed (isolation plugin): --cpu, --memory (Linux only; warns if plugin not loaded).

rm (or remove)

Remove a program configuration. It must be stopped first.

super rm <TARGET>

Process Control

All control commands support targeting by ID, Name, all, or @group.

start

Start a stopped process.

super start <TARGET> [--wait]

stop

Stop a running process.

super stop <TARGET> [--wait] [--timeout N]

restart

Restart a process.

super restart <TARGET> [--wait]

signal

Send a specific POSIX signal.

super signal <TARGET> --sig <SIGNAL>
  • Signals: hup, int, term, kill, quit, usr1, usr2.

Observability

info

Show detailed JSON/Table information about a specific program.

super info <TARGET>

logs

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

super logs <TARGET>              # live stream (WebSocket)
super logs <TARGET> --tail 200   # last 200 lines from disk
super logs <TARGET> --tail 50 --follow   # tail then follow live
FlagDescription
--tail NRead last N lines from log files (GET /api/v1/programs/{id}/logs)
--sourcestdout or stderr only
--followAfter --tail, keep streaming via WebSocket

System

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 <TARGET>     # SIGHUP to program(s) — e.g. nginx config reload

apply

Apply a declarative stack configuration (JSON).

super apply <FILE>

export

Export current state as a stack JSON.

super export

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, daemon health, license status, and local [server].daemon / pidfile hints (systemd conflict, stale pidfile).

super doctor

check

Validate super.toml (syntax, bind, licensed-mode requirements) without requiring a running daemon.

super check

Security (requires security plugin 💎)

When the security plugin is loaded, use the same super CLI:

# Bootstrap only (no Access Tokens yet), or after all tokens were revoked:
super login <auth_secret>          # save credentials to ~/.super/cli.json

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

# or pass token per invocation:
super --token sk-... list
export SUPER_TOKEN=sk-...

auth_secret stays usable by default; Admins may explicitly disable it after creating an Admin Access Token. See Authentication.

Without the plugin, super login fails (404 on /api/v1/auth/login). OSS deployments without auth can use super list directly on localhost.

Alternative via curl:

# Bootstrap (login with auth_secret only when no tokens exist yet):
curl -X POST http://127.0.0.1:9002/api/v1/auth/login \
  -H "Authorization: Bearer <auth_secret>"

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

See Authentication for details.

Config ReferenceAPI Reference