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

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

Short	Long	Description
-c	--config	Scope output to the project represented by this configuration file
-s	--service	Show a specific service/unit
-p	--project	Filter by stable project id
-	--all	Show all services including orphaned state outside the selected project/config set
-v	--verbose	Print operation progress
-	--sys	Opt into privileged system mode. Requires running as root
-	--drop-privileges	Accepted globally but ignored; status does not spawn services
-	--format	Emit machine-readable output (json or xml) instead of a table; defaults to json when no value is provided (disables interactive mode)
-	--no-color	Disable ANSI colors in output
-	--plain	Agent-friendly output: disable color and print full, un-truncated unit names
-	--full-cmd	Show complete command lines instead of table truncation
-	--live	Force immediate runtime collection instead of the configured snapshot mode
-	--stream	Continuously refresh status at the provided interval (e.g., 5, 1s, 2m) (disables interactive mode)
-	--log-level	Set logging verbosity for this invocation (trace through off, or 5-0)

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    USER  PID    CPU   RSS    UPTIME  CMD            LAST_EXIT  HEALTH
postgres   srvc  Running  app   14823  0.1%  92 MB  2h      postgres       -          Healthy
redis      srvc  Running  app   14824  0.0%  18 MB  2h      redis-server   -          Healthy
api        srvc  Running  app   14826  1.2%  64 MB  2h      python app.py  -          Healthy
worker     srvc  Running  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%
RSS: 64 MB
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.
• 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

State	Meaning
Running	The unit has a live tracked process.
Done	The unit completed successfully.
Failed	The unit exited unsuccessfully or its latest cron run failed.
Stopped	The unit was intentionally stopped and has no live process.
Skipped	A configured skip rule prevented startup.
Lost	systemg has PID state, but the process is no longer present.
Zombie	The tracked process is a zombie.
Queued	A cron unit is waiting for its next scheduled run.
Overlap	A cron run was blocked by an existing run.
Unknown	No reliable runtime or lifecycle fact is available.

Intent values

Intent describes what systemg expects from each unit. It appears in the overview summary box (the Intent row), not as a per-unit table column.

Intent	Meaning
Serve	The unit is expected to stay available as a long-running service.
Once	The unit is expected to run once and stop after success.
Cron	The unit is schedule driven.
Manual	systemg has no stronger configured expectation for the unit.
Skip	The unit is configured to be skipped when its skip rule passes.
Orphan	The state entry no longer matches a configured unit.

Health values

Health	Meaning
Healthy	The unit is doing what systemg expects.
Idle	The unit is inactive by design and does not require action.
Warn	The unit is not in the expected state, but is not a hard failure.
Failing	The 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