> ## Documentation Index
> Fetch the complete documentation index at: https://sysg.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# status

# status

Check the health of services known to the running supervisor.

```sh theme={null}
$ 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

| 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                                                          |
| `-`   | `--sys`       | Opt into privileged system mode. Requires running as root                                                                                   |
| `-`   | `--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                                                                                                               |
| `-`   | `--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 verbosity (`debug`, `info`, `warn`, `error`)                                                                                            |

## Examples

### View all registered projects

```sh theme={null}
$ 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

```sh theme={null}
$ 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

```sh theme={null}
$ sysg status --project arbitration
```

Project filters use `project.id`, not the renameable project display name.

### View the project from a config

```sh theme={null}
$ 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

```sh theme={null}
$ 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

```sh theme={null}
$ 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

| 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   | 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`](/how-it-works/commands/logs) - View service output
* [`restart`](/how-it-works/commands/restart) - Restart services