Skip to main content

​
status

Check the health of services known to the running supervisor. 
$ sysg status
When a supervisor is running, sysg status asks that supervisor for an aggregate view of every registered project. It reads current persisted state such as cron history and uses each project’s configured status.snapshot_mode for runtime detail. Use --live when you need systemg to force immediate runtime collection for that request. sysg status does not require a config file. If no supervisor is running and you do not provide --config, it reports No running supervisor. Use --config only when you want to scope status to a specific config/project or when you explicitly want the no-supervisor disk fallback for that config.

​
Interactive Mode

By default, sysg status displays an interactive table where you can:
  • ↓ / Tab (Down) - Move to the next service
  • ↑ / Shift+Tab (Up) - Move to the previous service
  • → / ← (Right / Left) - Move the focused cell across columns in the selected row
  • I or Enter - Open the inspect view for the selected service
  • H - Open the health report explaining why the selected unit is Warn or Failing (see below)
  • L - Open a live log snapshot stream for the selected service
  • R - Restart the selected service
  • q, ESC, or Ctrl+C - Exit the status view
:::info Cron units The R restart control applies to service units only. Cron units are scheduler entries, not persistent services, so pressing R on a cron row is a no-op: systemg shows a notice that cron units cannot be restarted directly and that you should reload the project to reschedule them. ::: The focused cell in the selected row is drawn in reverse video, so it stands out as lighter on a dark terminal and darker on a light terminal. This makes it obvious which cell you are on as you tab across the row.

​
Why is it Warn or Failing?

The HEALTH column is a verdict, not an explanation. To see why a unit holds its health, select it and press H. systemg opens a full-screen, README-style health report in the same window: 
# 'api' is stopped but should be serving

Severity: 5/10 (Warn)

TLDR: A long-running service is intentionally stopped.

## Description

'api' has intent 'Serve', meaning it is expected to stay available, but it is
currently stopped. Nothing is serving requests for this unit right now.

## Recommended Fix

Start it again if it should be up:

    sysg restart -s api --log-level debug

If it is meant to stay down, this is expected and can be ignored.
The report wraps to at most 80 columns, narrowing to 80% of the terminal width on smaller terminals. Press any key to return to the status table.
Info: Press L while a UNIT row is selected to open that unit’s logs without leaving the status workflow. The shortcut runs sysg logs -s <UNIT> -l 100 --stream 2, giving you the latest 100 log lines and refreshing the snapshot every 2 seconds.
Info: Press R while a UNIT row is selected to run sysg restart -s <UNIT> for that unit. When the row belongs to a project, the shortcut also passes --project <PROJECT_ID> so only that project’s unit is restarted.

​
Options

ShortLongDescription
-c--configScope output to the project represented by this configuration file
-s--serviceShow a specific service/unit
-p--projectFilter by stable project id
---allShow all services including orphaned state outside the selected project/config set
---sysOpt into privileged system mode. Requires running as root
---formatEmit machine-readable output (json or xml) instead of a table; defaults to json when no value is provided (disables interactive mode)
---no-colorDisable ANSI colors in output
---liveForce immediate runtime collection instead of the configured snapshot mode
---streamContinuously refresh status at the provided interval (e.g., 5, 1s, 2m) (disables interactive mode)
---log-levelSet verbosity (debug, info, warn, error)

​
Examples

​
View all registered projects

$ sysg status

╔════════════════════════════════════════════════════════════════════════════════╗
║  Status: HEALTHY                                                             ║
╟───────────────┬──────────────────────────────────────────────────────────────╢
║  Units        │ 4                                                            ║
║  Health       │ Healthy 4  •  Idle 0     •  Warn 0     •  Failing 0         ║
║  State        │ Running 4                                                   ║
║  Intent       │ Serve 4                                                     ║
╚═══════════════╧══════════════════════════════════════════════════════════════╝

UNIT       KIND  STATE    INTENT  USER  PID    CPU   RSS    UPTIME  CMD            LAST_EXIT  HEALTH
postgres   srvc  Running  Serve   app   14823  0.1%  92 MB  2h      postgres       -          Healthy
redis      srvc  Running  Serve   app   14824  0.0%  18 MB  2h      redis-server   -          Healthy
api        srvc  Running  Serve   app   14826  1.2%  64 MB  2h      python app.py  -          Healthy
worker     srvc  Running  Serve   app   14827  0.3%  41 MB  2h      python worker  -          Healthy

​
View specific service

$ sysg status --service api
When multiple registered projects contain the same service name, combine --service with --project. 
Service: api
State: Running
Health: Healthy
PID: 14826
Uptime: 2h3m
CPU: 1.2%
Memory: 4.5%
Command: python app.py

​
View a project

$ sysg status --project arbitration
Project filters use project.id, not the renameable project display name.

​
View the project from a config

$ sysg status --config ./systemg.yaml
This loads the config to find its project.id, then filters the supervisor status view to that project. If no supervisor is running, systemg falls back to the persisted disk state for that config.

​
Stream status updates

$ sysg status --stream 5
Stream mode polls supervisor status using the configured snapshot mode. It does not force detailed runtime collection on each redraw.

​
Force live runtime collection

$ sysg status --live
--live forces immediate runtime collection for this invocation. Regular requests still read current persisted state such as cron history, while the configured snapshot mode controls how much runtime process detail is collected.

​
Performance

The default status.snapshot_mode: summary keeps status inexpensive for larger systems by skipping process tree expansion, runtime command lookups, and per-pid user/uptime lookups. Use status.snapshot_mode: detailed when you want richer process and spawn-tree detail in status/inspect views.

​
Output fields

  • UNIT - Service, cron job, or orphaned state entry name.
  • KIND - Unit type: srvc for a managed service, cron for a cron job, or orph for orphaned state that no longer matches the current configuration.
  • STATE - Current observed runtime state or last persisted lifecycle outcome. STATE answers “what is this unit doing, or what happened most recently?” Values are Running, Done, Failed, Stopped, Skipped, Lost, Zombie, Queued, Overlap, and Unknown.
  • INTENT - What systemg expects from the unit. Values are Serve for long-running services, Once for one-shot services, Cron for scheduled jobs, Manual for manually controlled units, Skip for skipped units, and Orphan for persisted state without a matching config entry.
  • USER - Runtime process user when detailed runtime data is available.
  • PID - Runtime process ID when the unit has a tracked process.
  • CPU - Current CPU usage when runtime metrics are available.
  • RSS - Resident memory usage when runtime metrics are available.
  • UPTIME - Runtime process age when detailed runtime data is available.
  • CMD - Configured command, or the live command line when detailed runtime data is available.
  • LAST_EXIT - Last recorded exit code or signal when the unit has exited.
  • HEALTH - Operator action signal. HEALTH answers “does this unit need attention?” Values are Healthy, Idle, Warn, and Failing. Press H on a selected unit to open a health report explaining the verdict and how to fix it.

​
State values

StateMeaning
RunningThe unit has a live tracked process.
DoneThe unit completed successfully.
FailedThe unit exited unsuccessfully or its latest cron run failed.
StoppedThe unit was intentionally stopped and has no live process.
SkippedA configured skip rule prevented startup.
Lostsystemg has PID state, but the process is no longer present.
ZombieThe tracked process is a zombie.
QueuedA cron unit is waiting for its next scheduled run.
OverlapA cron run was blocked by an existing run.
UnknownNo reliable runtime or lifecycle fact is available.

​
Intent values

IntentMeaning
ServeThe unit is expected to stay available as a long-running service.
OnceThe unit is expected to run once and stop after success.
CronThe unit is schedule driven.
Manualsystemg has no stronger configured expectation for the unit.
SkipThe unit is configured to be skipped when its skip rule passes.
OrphanThe state entry no longer matches a configured unit.

​
Health values

HealthMeaning
HealthyThe unit is doing what systemg expects.
IdleThe unit is inactive by design and does not require action.
WarnThe unit is not in the expected state, but is not a hard failure.
FailingThe unit failed or has a broken runtime condition.
STATE, INTENT, and HEALTH are separate on purpose. STATE is factual, INTENT explains what should normally happen, and HEALTH says whether an operator should act. For example, Done + Once is Idle, while Stopped + Serve is Warn. The overview’s Status value is derived from unit health:
  • Failing if any unit is Failing
  • Warn if no unit is failing but at least one unit is Warn
  • Healthy otherwise
Idle units do not lower overall status.

​
See also

  • logs - View service output
  • restart - Restart services